Status Reporter Module (ID 3)

Purpose

The StatusReporterModule with ModuleId 3 reports the node status in a configured interval. It provides methods for directly requesting different kinds of device info and status data.

Functionality

The StatusReporterModule can periodically send out different kinds of informational messages. It also feeds the watchdog when keep alive messages are received. It is responsible for sending out logged error codes and measuring the necessary data for its messages such as the battery power.

Terminal Commands

Device Information

Generic information about a node that never changes or only changes through enrollment or firmware updates can be requested via the get_device_info command.

//Request the full device info from some nodes
action [nodeId] status get_device_info

Status Information

Information that is bound to change from time to time can be requested using the get_status command.

//Request the status
action [nodeId] status get_status

Connection Information

Information about the mesh connections of a node can be requested with the get_connections or get_nearby commands.

//Retrieve the connections from all nodes in the network
action [nodeId] status get_connections
//Retrieve nearby nodes with the same network id
action [nodeId] status get_nearby

Information about all connections with a lot of detail can be requested with the get_connections_verbose command. In scenarios with limited queue sizes, only single connections can be requested via an optional index parameter, as returned by the GetConnections method of the ConnectionManager.

//Retrieve detailed connection information from the node with nodeId.
action [nodeId] status get_connections_verbose

//Same, but only for the connection with the given index.
action [nodeId] status get_connections_verbose {index}

Live Reports

Live reports are a way to send information about errors, connections, disconnections and other important events to the user through the mesh. Each live report has a unique ID according to its importance. Liver reports are activated by setting the livereports level to a value greater than 0. The different levels are:

  • Off (0)

  • Error (50)

  • Warn (100)

  • Info (150)

  • Debug (200)

Live reports can be generated in the firmware using the SendLiveReport method. Two extra parameters can be given that can contain additional information for the specific report/error. The meaning of the extras is documented at the LiveReportType definition. LiveReports will of course only be received if the node is currently part of the mesh. If this is not the case, than it might be better to use the error log.

//Set the livereport level
action [nodeId] status livereports [liveReportLevel]

//Activate livereports for all errors on all nodes
action 0 status livereports 50

Live reports are printed on the terminal of a sink node and can be used to debug a problem in a running system:

{"type":"live_report","nodeId":123,"module":3,"code":1,"extra":2,"extra2":3}

Error Log

The error log stores metrics and errors that help monitoring the mesh. This information can be periodically queried e.g. by a gateway. More information is available on the dedicated error log page.

action [nodeId] status get_errors

The queried nodes will respond with their complete error log that they have stored in RAM. The error log is cleared on reboot as it is only stored in RAM and is also cleared after it was queried. The error log is printed on a sink node (or any other if json logging is active) as multiple json objects.

Exemplary response on a sink node
{"type":"error_log_entry","nodeId":2,"module":3,"errType":2,"code":22,"extra":59,"time":10000,"typeStr":"CUSTOM","codeStr":"COUNT_JOIN_ME_RECEIVED"}
{"type":"error_log_entry","nodeId":2,"module":3,"errType":2,"code":86,"extra":10030,"time":10030,"typeStr":"CUSTOM","codeStr":"INFO_UPTIME_ABSOLUTE"}
{"type":"error_log_entry","nodeId":2,"module":3,"errType":2,"code":20,"extra":6,"time":10030,"typeStr":"CUSTOM","codeStr":"INFO_ERRORS_REQUESTED"}

Component periodic timestamp sending

The StatusReporterModule includes functionality for periodically sending the nodes current timestamp. It has temporary and persistent time reporting functionality.

Temporary time reporting can be enabled and disabled via component_act. When enabled, it is automatically disabled after a few minutes to avoid unnecessary battery usage.

//Enables Periodic sending
component_act [nodeId] 3 2 0xABCD 0x1234 01 [requestHandle]

//Disabled Periodic sending
component_act [nodeId] 3 2 0xABCD 0x1234 00 [requestHandle]

Persistent time reporting is enabled with the terminal command:

action [nodeId] status set_time_reporting [intervalDs]

intervalDs .. Time reporting interval in deci seconds. An interval of 0 means no time reporting.

The immediate confirmation message should look like this:

{"type":"time_reporting_state","intervalDs":10,"nodeId":2,"module":3,"code":0}

Upon activation, the time is reported with multiple component_sense messages that roughly look like this example:

{"nodeId":33011,"type":"component_sense","module":3,"requestHandle":13,"actionType":0,"component":43981,"register":4660,"payload":"AgAAAA=="}

The payload of the answer is the base 64 timestamp of the target node.

Messages

Device Info (v2)

Request

Bytes Type Name Description

8

connPacketModule

header

messageType: MODULE_TRIGGER_ACTION(51), actionType: GET_DEVICE_INFO_V2(10)

Response

The device info contains information about the device that is not changing often, e.g. only after a firmware update or an enrollment.

Bytes Type Name Description

8

connPacketModule

header

messageType: MODULE_ACTION_RESPONSE(52), actionType: DEVICE_INFO_V2(10)

2

u16

manufacturerId

ID according to Bluetooth SIG Assigned numbers company identifiers

4

u32

serialNumberIndex

Index of the serial number, can be converted with alphabet

8

u64

chipId

A unique ID of the nRF chip

7

gapAddress

1 byte address type, 6 byte BLE address

2

u16

networkid

The network id

4

u32

nodeVersion

Version of the node (10000000 * MAJOR + 10000 * MINOR + PATCH)

1

i8

dbmRx

Receive power in dBm (signed)

1

i8

dbmTx

Transmit power in dBm (signed)

1

u8

deviceType

cf. Device Types

1

i8

calibratedTx

Calibrated TX power at 1m distance (signed)

2

u16

chipGroupId

Group ID for the chip (e.g. NRF52)

2

u16

featuresetGroupId

Group ID for the firmware featureset (used for firmware update). Matching groups are allowed to receive the firmware.

2

u16

bootloaderVersion

Version of the bootloader

Status

Request

Bytes Type Description

8

connPacketModule

messageType: MODULE_TRIGGER_ACTION(51), actionType: GET_STATUS(1)

Response

The device status contains information that is changing from time to time.

Bytes Type Description

8

connPacketModule

messageType: MODULE_ACTION_RESPONSE(52), actionType: STATUS(1)

2

clusterSize

Size of the cluster that the node is connected to (current mesh size)

2

inConnectionPartner

NodeId of the node that is connected to the one and only peripheral connection with this node.

1

inConnectionRssi

RSSI of the incoming connection

2 bit

freeIn

Number of free mesh connections as peripheral

6 bit

freeOut

Number of free mesh connections as central

1

batteryInfo

Battery voltage

1

connectionLossCounter

Counter of how many mesh connections were dropped

1 bit

initializedByGateway

If the gateway has initialized this beacon and sent the SET_INITIALIZED command, this bit will be 1 until a reboot is encountered

7 bit

reserved

Connections

Query all nodeIDs that a node is connected to including the connection rssi. The first entry is the incoming connection, the others are outgoing.

Request

Bytes Type Description

8

connPacketModule

messageType: MODULE_TRIGGER_ACTION(51), actionType: GET_ALL_CONNECTIONS(3)

Response

Bytes Type Description

8

connPacketModule

messageType: MODULE_ACTION_RESPONSE(52), actionType: ALL_CONNECTIONS(3)

3*x

connections

Array of all partnerEntries
PartnerEntry
Bytes Type Description

2

partnerId

nodeId of the connected node

1

rssi

RSSI as a signed integer

Nearby Nodes

Returns all nodes (limited to some maximum count) that are surrounding the node with the same networkId.

Request

Bytes Type Description

8

connPacketModule

messageType: MODULE_TRIGGER_ACTION(51), actionType: GET_NEARBY_NODES(4)

Response

Bytes Type Description

8

connPacketModule

messageType: MODULE_ACTION_RESPONSE(52), actionType: NEARBY_NODES(4)

3*x

nearbyNodes

Array of NearbyNodeEntries
NearbyNodeEntry
Bytes Type Description

2

nodeId

The nodeId of the nearby node

1

rssi

The RSSI as a signed integer

Live Reports

The statusReporterModule can send live reports that notify the user over various state changes and error conditions. A live report is generated for a node and then broadcast over the mesh. This allows live debugging of mesh errors, e.g. if two nodes are not connecting to each other. Live reports are also received over MeshAccessConnection, which means an error can be detected after connecting to the disconnected part of the mesh using a MeshAccessConnection.

enum LiveReportTypes {
    LIVE_REPORT_TYPES_ERROR = 0,
    LIVE_REPORT_TYPES_WARN = 50,
    //========
    LIVE_REPORT_TYPES_INFO = 100,
    LIVE_REPORT_TYPE_GAP_CONNECTED_INCOMING, //extra is connHandle, extra2 is 4 bytes of gap addr
    LIVE_REPORT_TYPE_GAP_TRYING_AS_MASTER, //extra is partnerId, extra2 is 4 bytes of gap addr
    LIVE_REPORT_TYPE_GAP_CONNECTED_OUTGOING, //extra is connHandle, extra2 is 4 byte of gap addr
    LIVE_REPORT_TYPE_GAP_DISCONNECTED, //extra is partnerid, extra2 is hci code

    LIVE_REPORT_TYPE_HANDSHAKE_FAIL,
    LIVE_REPORT_TYPE_MESH_CONNECTED, //extra is partnerid, extra2 is asWinner
    LIVE_REPORT_TYPE_MESH_DISCONNECTED, //extra is partnerid, extra2 is appDisconnectReason

    //========
    LIVE_REPORT_TYPES_DEBUG = 150,
    LIVE_REPORT_TYPE_DECISION_RESULT //extra is decision type, extra2 is preferedPartner
};

Event

Bytes Type Description

8

connPacketModule

messageType: MODULE_GENERAL(53), actionType: LIVE_REPORT(1)

1

reportType

Of type LiveReportType

4

extra

Additional data regarding the event, depending on reportType

4

extra2

Additional data regarding the event, depending on reportType

Keep Alive

The SET_KEEP_ALIVE message is used to validate the hopsToSink field on nodes in the mesh network. This feature is part of sink routing.

Bytes Type Description

8

connPacketModule

messageType: MODULE_TRIGGER_ACTION(51), actionType: SET_KEEP_ALIVE(9)

1 bit

fromSink

If the sender of the message is a sink

7 bits

reserved

Reserved