Network Monitoring¶

To help diagnose networking problems this API can be used to capture networking packets for further analysis by LumenRadio.

Note

This API is not guaranteed to be stable across versions.

Types¶

mira_diag_mac_logger_callback_t¶

typedef void(* mira_diag_mac_logger_callback_t) ( uint8_t status, uint8_t header_len, const uint8_t *header, mira_size_t data_len, const uint8_t *data);

mira_diag_mac_packet_filter_callback_t¶

typedef mira_bool_t(* mira_diag_mac_packet_filter_callback_t) (mira_diag_mac_packet_filter_t *metadata);

The callback function for filtering network packets.

The callback is invoked with the metadata of type mira_diag_mac_packet_filter_t. The function should implement the filtering criteria such that it returns:

Return value¶

Name	Description
MIRA_TRUE	For Filtering the network packet.
MIRA_FALSE	For NOT filtering the network packet.

mira_diag_net_topology_callback_t¶

typedef void(* mira_diag_net_topology_callback_t) (const mira_diag_net_topology_node_t *node_info, void *storage);

mira_diag_net_neighbour_data_handler_t¶

typedef void(* mira_diag_net_neighbour_data_handler_t) (const mira_diag_net_neighbour_data_t *nbr_data, void *storage);

Callback that receives neighbour data when mira_diag_net_get_neighbour_info() is called.

Enums¶

mira_diag_mac_logger_status_t¶

Status messages of packets sent to the network logger.

Name	Description
`MIRA_DIAG_MAC_LOGGER_STATUS_RX_PKT`
`MIRA_DIAG_MAC_LOGGER_STATUS_TX_PKT`
`MIRA_DIAG_MAC_LOGGER_STATUS_RX_ACK`
`MIRA_DIAG_MAC_LOGGER_STATUS_TX_ACK`
`MIRA_DIAG_MAC_LOGGER_STATUS_PKT_TYPE_MASK`
`MIRA_DIAG_MAC_LOGGER_STATUS_IS_OK`
`MIRA_DIAG_MAC_LOGGER_STATUS_IS_FILTERED`
`MIRA_DIAG_MAC_LOGGER_STATUS_IS_DROPPED`
`MIRA_DIAG_MAC_LOGGER_STATUS_COLLISION`

Structs¶

mira_diag_mac_packet_filter_t¶

Name	Type	Description
`source_address`	`uint8_t *`
`source_address_len`	`uint8_t`
`destination_address`	`uint8_t *`
`destination_address_len`	`uint8_t`

mira_diag_mac_statistics_t¶

Statistics about sent/received packets.

All Nodes LLMC are packets broadcasted to a node's neighbour. Custom LLMC are packets sent to neighbours that listen to the LLMC address. Unicast packets are packets sent to a specific neighbour.

Name	Type	Description
`rx_all_nodes_llmc_packets`	`uint32_t`	All Nodes Link-Layer Multicast
`rx_unicast_packets`	`uint32_t`
`rx_custom_llmc_packets`	`uint32_t`	Custom Link-Layer Multicast
`tx_all_nodes_llmc_packets`	`uint32_t`	All Nodes Link-Layer Multicast
`tx_unicast_packets`	`uint32_t`
`tx_custom_llmc_packets`	`uint32_t`	Custom Link-Layer Multicast
`rx_missed_slots`	`uint32_t`	Receive slots where packets couldn't receive because of lacking buffers
`rx_not_for_us_packets`	`uint32_t`	Packet received that wasn't for us.
`tx_dropped`	`uint32_t`	Unable to send because of full queues etc.
`tx_failed`	`uint32_t`	Failed to transmit
`used_tx_queue`	`uint32_t`
`rf_occupancy`	`uint32_t`	Measure of radio occupancy
`packet_rate`	`uint32_t`	Number of packets received
`tx_slots`	`uint32_t`	Number of tx slots
`rx_slots`	`uint32_t`	Number of rx slots
`scan_slots`	`uint32_t`	Number of scan slots
`calibrate_slots`	`uint32_t`	Number of calibrate slots
`unavailable_ms`	`uint32_t`	Radio resource unavailability time (ms)
`bytes_sent`	`uint32_t`	Number of bytes sent

mira_diag_net_topology_node_t¶

Topology data about a node.

Name	Type	Description
`lifetime_left_in_seconds`	`uint32_t`
`node_address`	`mira_net_address_t`
`parent_address`	`mira_net_address_t`

mira_diag_net_neighbour_data_t¶

Name	Type	Description
`addr`	`mira_net_address_t`	Address to the neighbour.
`link_met`	`mira_link_metric_t`	Link metric to the neighbour. Check mira_link_metric_t description for format. Calculated with a moving average. Starting value is 512.
`link_met_measurements`	`uint8_t`	Number of measurements in the link metric moving average. Stops counting after 255.
`rssi`	`int16_t`	Received Signal Strength Indicator to the neighbour in cBm. Calculated with a moving average.
`rate`	`uint8_t`	Network rate of the neighbour.

Functions¶

mira_diag_mac_set_packet_logger¶

mira_status_t mira_diag_mac_set_packet_logger(mira_diag_mac_logger_callback_t logger_cb);

Register a callback to log network packets.

The status parameter to the callback will describe what kind of packet is being logged. All received packets are sent here, even packets that are not for the current node and packets with errors.

The callback gets a status indicating what kind of packet is being logged and its state. The header and data pointers' memory should be logged after each other.

Note

This function should only be used at the request of LumenRadio.

mira_diag_mac_set_packet_filter¶

mira_status_t mira_diag_mac_set_packet_filter(mira_diag_mac_packet_filter_callback_t filter_cb);

Register a callback to filter network packets.

Parameters¶

Name	Description
filter_cb	The callback function that implements the filtering.

Return value¶

Name	Description
MIRA_SUCCESS	The filter callback successfully registered.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_diag_mac_get_statistics¶

mira_status_t mira_diag_mac_get_statistics(mira_diag_mac_statistics_t *stats);

Get MAC statistics.

The values are counted (with wrap around) from startup.

Parameters¶

Name	Description
stats	the collected statistics

Return value¶

Name	Description
MIRA_SUCCESS	Successfully got statistics.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.
MIRA_ERROR_UNKNOWN	Unknown error occurred.

mira_diag_net_get_topology¶

mira_status_t mira_diag_net_get_topology(mira_diag_net_topology_callback_t callback, void *storage);

Get network topology info.

The callback with be called with info about every node known to the current node.

The result can be used for network monitoring and diagnostics, but it should not be used for node reachability.

Note

Use UDP messages for heartbeat and reachability queries.

Parameters¶

Name	Description
callback	the callback called for every node.
storage	pointer passed on to the callback.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the topology.
MIRA_ERROR_NOT_SUPPORTED	Node is not root, or does not support topology output.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_diag_net_get_neighbour_info¶

mira_status_t mira_diag_net_get_neighbour_info(mira_diag_net_neighbour_data_handler_t callback, void *storage);

Register a callback that will get data about neighbouring nodes Supports multiple calls, but callback must be given and valid for each call.

Parameters¶

Name	Description
callback	Function pointer to callback that will be called for every neighbour found.
storage	Storage pointer sent to data_handler function.

Return value¶

Name	Description
MIRA_ERROR_INVALID_VALUE	data_handler is an invalid pointer.
MIRA_NET_ERROR_NOT_ASSOCIATED	network not started or joined.
MIRA_SUCCESS	neighbour data successfully sent to callback.

mira_diag_get_rank¶

mira_status_t mira_diag_get_rank(uint16_t *rank);

Get the RPL rank of the node.

Note

This value is based on a custom objective function available only within Mira and might be subject to change. It is only intended to be analyzed togheter with LumenRadio support.

Parameters¶

Name	Description
rank	RPL rank

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the rank.
MIRA_NET_ERROR_NOT_ASSOCIATED	Network not started or joined.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_diag_get_estimated_pdr¶

mira_status_t mira_diag_get_estimated_pdr(uint16_t *pdr);

Get the estimated PDR from the node to the root.

Note

Return a calculated estimate of the probability of a successful delivery for a packet sent to root. Note that the model is an estimation that is relying on information available without having impact on energy or performance, and may therefore differ from the actual PDR. The value is represented as fixed point see MIRA_DIAG_PDR_FP, where 32768 represents 100% PDR and 0 represents 0% PDR. It is only intended to be analyzed togeheter with LumenRadio support.

Parameters¶

Name	Description
pdr	Estimated PDR

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the estimated PDR.
MIRA_NET_ERROR_NOT_ASSOCIATED	Network not started or joined.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.
MIRA_ERROR_RESOURCE_UNAVAILABLE	Estimated PDR not available.

mira_diag_get_hop_count¶

mira_status_t mira_diag_get_hop_count(uint16_t *hop_count);

Get estimated number of hops to reach the root.

Note

It is only intended to be analyzed togheter with LumenRadio support.

Parameters¶

Name	Description
hop_count	Hop count

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the hop count.
MIRA_NET_ERROR_NOT_ASSOCIATED	Network not started or joined.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.
MIRA_ERROR_RESOURCE_UNAVAILABLE	Hop count not available.

mira_diag_get_path_etx¶

mira_status_t mira_diag_get_path_etx(mira_link_metric_t *path_etx);

Get the estimated total number of transmissions to reach root.

Note

Get the estimated total number of transmissions for any node in the path from current node to the root. This shows how much on-air time the packet is expected to have anywhere in the network. It is only intended to be analyzed togheter with LumenRadio support.

Parameters¶

Name	Description
path_etx	Path ETX (see description of mira_link_metric_t)

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the path ETX.
MIRA_NET_ERROR_NOT_ASSOCIATED	Network not started or joined.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.
MIRA_ERROR_RESOURCE_UNAVAILABLE	Path ETX not available.