General¶

Types¶

mira_link_metric_t¶

typedef uint16_t mira_link_metric_t;

The link metric (as a Q9.7 fixed point number) is a quality index of a particular link between two nodes. The value 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.

mira_rssi_t¶

typedef int16_t mira_rssi_t;

Received Signal Strength Indicator (RSSI) A value of the average strength of the signal received in cBm (centibel-milliwatt) which is a tenth of a dBm.

mira_net_antenna_t¶

typedef uint8_t mira_net_antenna_t;

Antenna index type.

mira_net_state_callback_t¶

typedef void(* mira_net_state_callback_t) (mira_net_state_t net_state);

Callback called when network state changes.

Enums¶

mira_net_state_t¶

States of network association.

Name	Description
`MIRA_NET_STATE_NOT_ASSOCIATED`	The node is not part of a network yet.
`MIRA_NET_STATE_IS_COORDINATOR`	Tells if the node is the coordinator (root).
`MIRA_NET_STATE_ASSOCIATED`	The node is in sync, but has no parent yet.
`MIRA_NET_STATE_JOINED`	The node has a parent and can send packets. Packets may not be routable to this node.

mira_net_rate_t¶

Recommended data rates.

Name	Description
`MIRA_NET_RATE_FAST`
`MIRA_NET_RATE_MID`
`MIRA_NET_RATE_SLOW`

mira_net_mode_t¶

Network mode.

MIRA_NET_MODE_ROOT acts as the root node for a network. When starting it tries to reconnect to a previous network, for quicker root restarts. The drawback is that new networks will take longer to start. MIRA_NET_MODE_ROOT is useful for production networks where root restarts may occur.

MIRA_NET_MODE_ROOT_NO_RECONNECT is equal to MIRA_NET_MODE_ROOT, except it doesn’t try to reconnect to the network. It will immediately announce the network to other nodes, making it faster for initial network build. MIRA_NET_MODE_ROOT_NO_RECONNECT is useful during development, to get fast test cycles.

During normal operation, MIRA_NET_MODE_ROOT and MIRA_NET_MODE_ROOT_NO_RECONNECT is equal.

MIRA_NET_MODE_MESH is for mesh nodes that can route packets for other nodes.

MIRA_NET_MODE_LEAF are for leaf nodes. They use less energy than mesh nodes, but can not route messages.

MIRA_NET_PROVISIONING is only used with multichan.

Name	Description
`MIRA_NET_MODE_ROOT`
`MIRA_NET_MODE_MESH`
`MIRA_NET_MODE_LEAF`
`MIRA_NET_MODE_ROOT_NO_RECONNECT`

mira_net_compat_t¶

Name	Description
`MIRA_NET_COMPAT_DEFAULT`

Structs¶

mira_net_config_t¶

Network configuration.

Note

The struct mira_net_config_t can be updated with more fields in future versions. Therefore, it is recommended that the entire memory block of the structure is zeroed out before setting the desired fields.

Name	Type	Description
`pan_id`	`uint32_t`	Network ID. Network ID, must be same for all nodes in the network. The Pan ID shall be a 32-bit value, that meets the following requirements: It shall not be the Access Address for BLE advertisements (0x8E89BED6). It shall not have a sequence that only differs one bit from any other known PAN ID or BLE advertisement Access Address. It shall have a minimum of two transitions in the most significant six bits. It shall have no more than six consecutive zeros or ones. It shall have no more than 24 transitions. It shall not have all four octets equal.
`key`	`uint8_t[16]`	Encryption key. The encryption key for all data in the network. Must be the same for all nodes in the network.
`mode`	`mira_net_mode_t`	Mode of operation. Set to mesh/leaf/root depending on desired 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
`net_compat`	`mira_net_compat_t`	Compability mode.
`rate`	`uint8_t`	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 are defined in mira_net_rate_t. Rates 0 to 10 are supported for meshing nodes and root node. Rates 0 to 12 are supported for leaf nodes. Rates 13 and higher are not supported.
`antenna`	`mira_net_antenna_t`	Preferred antenna. The preferred antenna. If the specified antenna is not available on the module, the default antenna is selected.
`prefix`	`const mira_net_address_t *`	Custom network prefix. If unset, fd00::/64 is default. This parameter only applies when mode == MIRA_NET_MODE_ROOT or MIRA_NET_MODE_ROOT_NO_RECONNECT, for other modes, the prefix is derived from the joined network. Only first /64 is used.
`max_nbrs`	`mira_size_t`	Size of neighbour table. The neighbour table defines the number of nodes available within reach. It tracks the other nodes within hearable distance. If unset (set to 0), the default value of 64 is set.
`max_links`	`mira_size_t`	Size of link table. The link table tracks the topology of the entire network. Each node needs to have a slot in the link table. The link table only applies to root nodes, and is ignored on mesh or leaf nodes. If unset (set to 0), the default value of 250 is set.
`tx_queue_size`	`uint8_t`	Size of the TX queue. A value of less than eight uses the default size of eight.
`max_connections`	`uint8_t`	The maximum amount of open mira_net_connections. If unset (set to 0), the default value of 8 is used.
`max_fota_transfers`	`uint8_t`	How many concurrent FOTA transfers that are allowed. If the children are running at a slower rate than the parent, the network might be updated faster if this value is increased. This value should not exceed tx_queue_size - 6. If unset (set to 0), the default value of 2 is used.

Functions¶

mira_net_init¶

mira_status_t mira_net_init(const mira_net_config_t *config);

Initialize the mira network.

Note

When running MiraMesh, this needs to be run after a successful call to miramesh_init().

Parameters¶

Name	Description
config	Network configuration.

Return value¶

Name	Description
MIRA_SUCCESS	Mira net successfully initialized.
MIRA_ERROR_INVALID_VALUE	Unsupported configuration parameters.
MIRA_ERROR_NO_MEMORY	Not enough memory has been allocated.
MIRA_NET_ERROR_INVALID_CREDENTIALS	Incorrect network credentials.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_ERROR_NOT_INITIALIZED	Not all dependencies are initialized correctly.

mira_net_init_mc¶

mira_status_t mira_net_init_mc(const mira_net_config_t *config);

Initialize the mira network with multichan MAC layer.

Note

When running MiraMesh, this needs to be run after a successful call to miramesh_init().

Parameters¶

Name	Description
config	Network configuration.

Return value¶

Name	Description
MIRA_SUCCESS	Mira net successfully initialized.
MIRA_ERROR_INVALID_VALUE	Unsupported configuration parameters.
MIRA_ERROR_NO_MEMORY	Not enough memory has been allocated.
MIRA_NET_ERROR_INVALID_CREDENTIALS	Incorrect network credentials.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_ERROR_NOT_INITIALIZED	Not all dependencies are initialized correctly.

mira_net_is_init¶

int mira_net_is_init(void);

Tells if mira_net_init has been called.

Return value¶

Name	Description
0	mira_net_init has not been called.

mira_net_get_address¶

mira_status_t mira_net_get_address(mira_net_address_t *dst);

Get the IP address.

Parameters¶

Name	Description
dst	The destination where to store the retrieved IP address.

Return value¶

Name	Description
MIRA_SUCCESS	IP address stored successfully.

mira_net_get_ll_address¶

mira_status_t mira_net_get_ll_address(mira_net_address_t *dst);

Get the link local IP address.

This address is only guaranteed to be unique among the node's neighbours.

Use mira_net_get_address to get an address usable by the whole network.

Parameters¶

Name	Description
dst	The destination where to store the retrieved IP address.

Return value¶

Name	Description
MIRA_SUCCESS	IP address stored successfully.

mira_net_register_net_state_cb¶

void mira_net_register_net_state_cb(mira_net_state_callback_t cb);

Register callback to be triggered when network state changes.

Parameters¶

Name	Description
cb	Callback to be called when network state changes. If cb is set to NULL, no callback will be triggered on network state change.

mira_net_get_state¶

mira_net_state_t mira_net_get_state(void);

Get the current state of network association.

This function uses a signal, so it is possible to use the following for waiting to become joined.

PROCESS_WAIT_UNTIL(mira_net_get_state() == MIRA_NET_STATE_JOINED);

Please note that there is no way to locally see if this node is reachable from other nodes unless they send a packet to it. The joined state means this node is able to send packets to other nodes.

Return value¶

Name	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);

Get the IP address of the root node.

Parameters¶

Name	Description
dst	The destination where to store the retrieved IP address of the root node.

Note

The Mira Gateway has two addresses. One for the radio on the Miramesh side and one for the tun device on the host side. This function returns the radio interface's address.

Return value¶

Name	Description
MIRA_SUCCESS	Got valid address.
MIRA_NET_ERROR_NOT_ASSOCIATED	Node does not know root's address yet.

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¶

Name	Description
dst	The destination where to store the retrieved IP address of the parent.

Return value¶

Name	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.

Return value¶

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 doubles after each active scan period. The sleep period cannot be longer than 23 hours.

Return value¶

Name	Description
MIRA_SUCCESS	Scanning reset successfuly.

mira_net_rejoin¶

mira_status_t mira_net_rejoin(void);

Rejoin the network.

When joined, the node will leave the network and start scanning. If already scanning, will reset the network scanning.

Return value¶

Name	Description
MIRA_SUCCESS	Network left successfully.

mira_net_is_reachable¶

mira_bool_t mira_net_is_reachable(const mira_net_address_t *address);

Is the node reachable?

This function tells if a node is reachable.

A MIRA_TRUE return value does not guarantee that sent messages will reach the node. This function will continue to return MIRA_TRUE for many hours after a node has failed or if the network has become partitioned.

Note

This function only works on root nodes.