Network general¶
Types¶
| Name | Type | Description |
|---|---|---|
mira_link_metric_t |
uint16_t |
Enums¶
mira_net_state_t¶
| Name | Value | Description |
|---|---|---|
MIRA_NET_STATE_NOT_ASSOCIATED |
The unit is not part of a network yet. |
|
MIRA_NET_STATE_IS_COORDINATOR |
Tells if the unit is the coordinator (root). |
|
MIRA_NET_STATE_ASSOCIATED |
The unit is in sync, but has no parent yet. |
|
MIRA_NET_STATE_JOINED |
The unit has its parent and is a part of the network-tree, can send packets. |
mira_net_rate_t¶
| Name | Value | Description |
|---|---|---|
MIRA_NET_RATE_FAST |
0 | |
MIRA_NET_RATE_MID |
8 | |
MIRA_NET_RATE_SLOW |
12 |
mira_net_antenna_t¶
| Name | Value | Description |
|---|---|---|
MIRA_NET_ANTENNA_ONBOARD |
0 | |
MIRA_NET_ANTENNA_EXTERNAL |
mira_net_mode_t¶
| Name | Value | Description |
|---|---|---|
MIRA_NET_MODE_ROOT |
0 | |
MIRA_NET_MODE_MESH |
||
MIRA_NET_MODE_LEAF |
Structs¶
mira_net_address_t¶
| Type | Name | Description |
|---|---|---|
uint8_t[16] |
u8 | |
uint16_t[8] |
u16 | |
uint32_t[4] |
u32 |
Structs¶
mira_net_config_t¶
| Type | Name | Description |
|---|---|---|
uint32_t |
pan_id | Network ID.Must be same for all nodes in the network. |
uint8_t[16] |
key | Encryption keyThe encryption key for all data in the network. Must be the same for all nodes in the network. |
mira_net_mode_t |
mode | Mode of operation. Set to mesh/leaf/root depending on current mode of operation.Not all modes may be supported by all builds. If not supported, mira_net_init() will fail with MIRA_ERROR_INVALID_VALUE |
uint8_t |
rate | Rate of network.Higher value of rate reduces power consumption at the expense of data rate.Different nodes in the network may have different rates, and routes with higher rates are preferred over routes with lower rates.Recommended values is defined in mira_net_rate_tRates 0-10 is supported for meshing nodes and root node Rates 0-12 is supported for leaf nodesRates 13 and higher is not supported. |
mira_net_antenna_t |
antenna | Preferred antennaThe antenna preferred for the system. If the specified antenna is not available on the module, the default antenna (usually the onboard chip antenna) will be selected. |
mira_net_address_t |
prefix | Custom network prefix. If unset, fd00::/64 is defaultThis parameter only applies when mode == MIRA_NET_MODE_ROOT, for other modes, the prefix is derived from the joined networkOnly first /64 is used. |
Network configuration.
Functions¶
mira_net_init¶
mira_status_t mira_net_init( const mira_net_config_t* config);
Initializes the mira network.
Parameters
| Parameter | Description |
|---|---|
config |
Network configuration |
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Mira net successfully initialized. |
MIRA_ERROR_INVALID_VALUE |
Unsupported configuration parameters |
MIRA_ERROR_UNKNOWN |
An unknown error occurred. |
mira_net_get_address¶
mira_status_t mira_net_get_address( mira_net_address_t* dst);
Gets the IP address.
Parameters
| Parameter | Description |
|---|---|
dst |
The destination where to store the retrieved IP address. |
Return
MIRA_SUCCESS if successful.
mira_net_get_state¶
mira_net_state_t mira_net_get_state( void);
Get the current state of network association.
Return
Current network state.
| Value | Description |
|---|---|
MIRA_NET_STATE_IS_COORDINATOR |
Node state is coordinator. |
MIRA_NET_STATE_NOT_ASSOCIATED |
Node state is not associated. |
MIRA_NET_STATE_ASSOCIATED |
Node state is associated. |
MIRA_NET_STATE_JOINED |
Node state is joined. |
mira_net_get_root_address¶
mira_status_t mira_net_get_root_address( mira_net_address_t* dst);
Gets the IP address of the root node.
Parameters
| Parameter | Description |
|---|---|
dst |
The destination where to store the retrieved IP address of the root node. |
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Got valid address. |
MIRA_NET_ERROR_NOT_ASSOCIATED |
Node is not associated. |
mira_net_get_parent_address¶
mira_status_t mira_net_get_parent_address( mira_net_address_t* dst);
Gets the IP address of the parent node.
Parameters
| Parameter | Description |
|---|---|
dst |
The destination where to store the retrieved IP address of the parent. |
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Got valid address. |
MIRA_NET_ERROR_NOT_ASSOCIATED |
Node is not associated. |
mira_net_get_parent_link_metric¶
mira_link_metric_t mira_net_get_parent_link_metric( void);
Gets the link quality metric to the parent node. The link metric (as a 9.7 fixed point number) is a quality index of a particular link between two nodes. The value returned is called ETX, which is an approximate number of transmissions required for a successful transfer. Range is from 1.0 (0x0080) to infinity (0xFFFF). A value of 1.0 means a perfect link. Higher numbers are worse. To calculate an approximate packet delivery rate use the following formula: PDR = 1.0 / ETX.
Return
A link quality metric as an unsigned 9.7 fix point number.
mira_net_reset_scanning¶
mira_status_t mira_net_reset_scanning( void);
Reset network scanning. Network scanning will timeout after 5 minutes and sleep to conserve battery power in the case that there is no network to join. The sleep period is 5 minutes the first time, and will double after each active scan period. The sleep period will never be longer than 23 hours.
Return
MIRA_SUCCESS if successful.
mira_net_set_low_power¶
mira_status_t mira_net_set_low_power( void);
Set low power mode. Disables any radio frontend present, limiting output power and lowering power consumption.
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Low power mode set successfully. |
MIRA_ERROR_UNKNOWN |
An unknown error occurred. |
MIRA_RADIO_ERROR |
Radio driver reported an error. |
MIRA_ERROR_INVALID_VALUE |
Value invalid. |
MIRA_ERROR_NOT_SUPPORTED |
Function not supported. |
mira_net_set_high_power¶
mira_status_t mira_net_set_high_power( void);
Set high power mode. Enbables use of a radio frontend, increasing the available output power and increases power consumption.
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
High power mode set successfully. |
MIRA_ERROR_UNKNOWN |
An unknown error occurred. |
MIRA_RADIO_ERROR |
Radio driver reported an error. |
MIRA_ERROR_INVALID_VALUE |
Value invalid. |
MIRA_ERROR_NOT_SUPPORTED |
Function not supported. |
mira_net_set_txpower¶
mira_status_t mira_net_set_txpower( int16_t power_cbm);
Set radio output power. Set the output power of the chip, without accounting for antenna gain. If in high power mode dynamically enables any present frontend amplification if needed.
Power levels are quantized and therefore rounded down to the nearest available power level. The available power level that was set can be obtained by mira_net_get_actual_txpower.
All power values is in the unit of cBm, or centi-bel-mW, which is tenth of dBm. For example, 100mW is 20.0dBm, which is 200cBm. Proper value to pass to the method is therefore 200.
Parameters
| Parameter | Description |
|---|---|
power_cbm |
Desired output power. |
Return
MIRA_SUCCESS if successful.
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Output power set successfully. |
MIRA_ERROR_UNKNOWN |
An unknown error occurred. |
MIRA_RADIO_ERROR |
Radio driver reported an error. |
MIRA_ERROR_INVALID_VALUE |
Invalid output power. |
MIRA_ERROR_NOT_SUPPORTED |
Function not supported. |
mira_net_get_actual_txpower¶
mira_status_t mira_net_get_actual_txpower( int16_t* power_cbm);
Get actual radio output power. Get the output power for the current configuration.
Since output power may be quantized, and frontend might be active/inactive, the actual output power may differ from the requested.
Parameters
| Parameter | Description |
|---|---|
power_cbm |
pointer to an int16_t of where to store the output power value. |
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Output power gotten successfully. |
MIRA_ERROR_UNKNOWN |
An unknown error occurred. |
MIRA_RADIO_ERROR |
Radio driver reported an error. |
MIRA_ERROR_INVALID_VALUE |
Invalid output power. |
MIRA_ERROR_NOT_SUPPORTED |
Function not supported. |
mira_net_set_antenna¶
mira_status_t mira_net_set_antenna( mira_net_antenna_t antenna);
Set active antenna. The antenna defaults to the onboard antenna. If setting an antenna the hardware doesn't support, it will default back to the onboard antenna.
Parameters
| Parameter | Description |
|---|---|
antenna |
Preferred antenna. |
Return
See enum definition.
| Value | Description |
|---|---|
MIRA_SUCCESS |
Antenna selected successfully. |
MIRA_ERROR_UNKNOWN |
An unknown error occurred. |
MIRA_RADIO_ERROR |
Radio driver reported an error. |
MIRA_ERROR_INVALID_VALUE |
Invalid antenna. |
MIRA_ERROR_NOT_SUPPORTED |
Function not supported. |