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.

Defines¶

MIRA_DIAG_PDR_FP¶

#define MIRA_DIAG_PDR_FP

100% PDR in Q1.15 fixed point format

mira_diag_get_estimated_pdr¶

#define mira_diag_get_estimated_pdr(pdr)

Alias for mira_diag_get_pdr_to_root.

MIRA_DIAG_MONITOR_ALL_FIELDS_ENABLED¶

#define MIRA_DIAG_MONITOR_ALL_FIELDS_ENABLED

MIRA_DIAG_MONITOR_MAX_REPORTED_NEIGHBOURS¶

#define MIRA_DIAG_MONITOR_MAX_REPORTED_NEIGHBOURS

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_monitor_receiver_callback_t¶

typedef void(* mira_diag_monitor_receiver_callback_t) (mira_diag_monitor_info_t monitor_info);

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`

mira_diag_monitor_sender_fields_t¶

Fields to send with the Mira monitoring service messages.

Name	Description
`MIRA_DIAG_MONITOR_ADDRESS`
`MIRA_DIAG_MONITOR_MAC_STATS`
`MIRA_DIAG_MONITOR_NEIGHBOUR_STATS`
`MIRA_DIAG_MONITOR_PDR_TO_ROOT`
`MIRA_DIAG_MONITOR_RSSI`
`MIRA_DIAG_MONITOR_ETX`
`MIRA_DIAG_MONITOR_ESTIMATED_CURRENT_CONSUMPTION`
`MIRA_DIAG_MONITOR_ROUTING_LOAD`
`MIRA_DIAG_MONITOR_NETWORK_TIME`
`MIRA_DIAG_MONITOR_RATE_AND_MODE`
`MIRA_DIAG_MONITOR_PDR_TO_PARENT`

Structs¶

mira_diag_monitoring_sender_cfg_t¶

Configuration for Mira monitoring service.

Name	Type	Description
`send_interval_s`	`uint16_t`	Time between monitoring message
`enabled_fields_bitmask`	`uint32_t`	Bit mask configuring which fields are added to the Mira monitoring service message

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_slot_execution_errors`	`uint32_t`	Receive slots where packets couldn't receive because of slot execution errors.
`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_monitor_neighbour_data_t¶

Struct containing info about a neighbouring node.

Name	Type	Description
`neighbour_address`	`mira_net_address_t`
`rating`	`uint8_t`
`etx`	`uint16_t`
`rssi`	`int16_t`
`pdr_to_neighbour`	`uint16_t`

mira_diag_monitor_info_t¶

Struct containing the monitoring data from a node.

Name	Type	Description
`node_address`	`mira_net_address_t`	IPv6 address of the reporting node
`received_fields_bitmask`	`uint32_t`	Bitmask, with bit set for each received field
`mac_stats`	`mira_diag_mac_statistics_t`	Struct containing the mac stats
`pdr_to_root`	`uint16_t`	Estimated end to end PDR of the reporting node
`rssi`	`int16_t`	RSSI to the parent of the reporting node
`etx`	`uint16_t`	ETX to the parent of the reporting node
`estimated_current_consumption`	`uint16_t`	Estimate moving average of the reporting nodes current consumption
`routing_load`	`uint8_t`	Moving average of the used routing capacity of the reporting node
`network_time`	`mira_net_time_t`	Mira network time at when the message was sent
`rate`	`uint8_t`	Mira Network rate of the node
`mode`	`mira_net_mode_t`	Mira Network mode
`pdr_to_parent`	`uint16_t`	PDR to the parent of the reporting node
`received_neighbours`	`uint8_t`	Number of neighbours populated in the neighbours array
`neighbours`	`mira_diag_monitor_neighbour_data_t[MIRA_DIAG_MONITOR_MAX_REPORTED_NEIGHBOURS]`	Top 5 neighbours of reporting node

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. 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 together 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_pdr_to_root¶

mira_status_t mira_diag_get_pdr_to_root(uint16_t *pdr);

Get the PDR from the node to the root.

Returns an estimate of the probability of a successful delivery for a packet sent to root.

The value is represented as a Q1.15 fixed point value (see MIRA_DIAG_PDR_FP), where 32768 represents 100% PDR and 0 represents 0% PDR.

See also: mira_net_get_parent_link_metric

Parameters¶

Name	Description
pdr	PDR to root

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the PDR to root.
MIRA_NET_ERROR_NOT_ASSOCIATED	Network not started or joined.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.
MIRA_ERROR_RESOURCE_UNAVAILABLE	PDR to root 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 together 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.

Gets the estimated total number of transmissions for a packet in the path from the current node to the root. This shows how much on-air time the packet is expected to have when being sent to root.

Note

It is only intended to be analyzed together 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.

mira_diag_get_routing_load¶

mira_status_t mira_diag_get_routing_load(uint8_t *routing_load);

Get the percentage routing load of the node.

Routing load indicates the radio utilization, and the remaining percentage is the available headroom for reception.

Parameters¶

Name	Description
routing_load	Pointer to where routing load should be stored.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully returned the routing load.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.
MIRA_ERROR_NOT_SUPPORTED	Metric is not supported.

mira_diag_enable_monitoring_sender¶

mira_status_t mira_diag_enable_monitoring_sender(mira_diag_monitoring_sender_cfg_t *cfg);

Enable Mira monitoring service sender, can only be enabled on mesh or leaf nodes.

This can also be called to reconfigure the sender while it is already running.

Parameters¶

Name	Description
cfg	Pointer to a struct containing the configuration.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully configured and started the sender.
MIRA_ERROR_INVALID_VALUE	cfg is NULL.
MIRA_ERROR_NOT_INITIALIZED	mira_net_init() has not been called before.
MIRA_ERROR_NOT_SUPPORTED	Device is running as root.
MIRA_ERROR_NO_MEMORY	Could not allocate UDP socket.
MIRA_ERROR_NOT_IMPLEMENTED	Not supported send field activated.

mira_diag_disable_monitoring_sender¶

mira_status_t mira_diag_disable_monitoring_sender(void);

Disable Mira monitoring service sender.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully disabled the monitoring service
MIRA_ERROR_NOT_SUPPORTED	Device is running as root

mira_diag_enable_monitor_receiver¶

mira_status_t mira_diag_enable_monitor_receiver(mira_diag_monitor_receiver_callback_t callback);

Enable Mira monitoring service receiver.

This should only be called on the root node.

The callback data is only valid during the call to the callback.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully enabled receiver.
MIRA_ERROR_NOT_INITIALIZED	mira_net_init() has not been called before.
MIRA_ERROR_ALREADY_INTIALIZED	The receiver is already running.
MIRA_ERROR_INVALID_VALUE	The callback is NULL.
MIRA_ERROR_NOT_SUPPORTED	Device is not running as root.
MIRA_ERROR_NO_MEMORY	Could not allocate UDP socket.

mira_diag_disable_monitoring_receiver¶

mira_status_t mira_diag_disable_monitoring_receiver(void);

Disable Mira monitoring service receiver.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully disabled receiver.
MIRA_ERROR_NOT_SUPPORTED	Device is not running as root