Debug Module (ID 7)

Purpose

The DebugModule with ModuleId 7 contains a collection of commands to debug network problems and test other functionality.

Functionality

The Debug module does not perform a lot of functionality itself. It triggers actions from other moduels for debug purposes. It provides a flooding mode.

Terminal Commands

Resetting Nodes

We have moved the reset functionality to our Node.

Request Discover Buffer

To debug problems with discovery, it is useful to fetch the contents of the JOIN_ME buffer from all nodes in a mesh.

//Receiving nodes will send back their buffer contents
action [nodeId] debug get_buffer

Ping

To determine the latency, a ping can be sent to nodes. Nodes can only be pinged one at a time. Timing issues may occur if multiple nodes are pinged simultaneously. The optional ping mode can be set to unreliable (write_cmd) or reliable (write_req).

//Sends a ping to a node and logs the time
action [nodeId] debug ping [count] [mode = r / u]

//Sends one ping message to nodeId 2 using write_cmd (unreliable)
action 2 debug ping 1 u

PingPong

A ping packet can bounce multiple times between two nodes to get a better average of the latency.

//Bounces a ping back and forth multiple times
action [nodeId] debug pingpong [count] [mode]

//Bounces a packet back and forth 10 times between the current node and node 45
action 45 debug pingpong 10 u

Leaf Ping

The leaf ping will sends a ping command through the mesh starting from the current node. All leaf nodes will respond and the ping times will be logged on the terminal.

//Start the leaf ping
lping [count] [mode = r / u]

Flooding

The DebugModule has a flooding mode where it generates messages every once in a while. This is helpful for generating a certain load on the network. Supported modes are:

Off (0): No flooding and no listening
Unreliable (2): Floods with WRITE_CMD packets
Listen (3): Listens for floods from given node and counts them
SplitData (4): Sends big messages that are split into multiple packets

//Activates a flooding mode to generate packets
action [nodeID] debug flood [destinationNodeId] [mode] [packetsPer10Sec] {timeoutSec = 10}

//Tell node 1 to flood node 2 with 1 packet each second
action 1 debug flood 2 2 10

//Instruct node 2 to count packets from node 1
action 2 debug flood 1 3 0

Counter Mode

It is possible to use the DebugModule to generate periodic messages with an increasing value. This is useful for testing reliability in a mesh network and to see how many messages are dropped. The interval in which the messages are sent is configurable.

//Activates the counter mode
action [nodeID] debug counter [destinationNodeId] [packetsPer10Sec] maxCounterValue

//Tell node 1 to send counter packets to node 2 until the counter value 100 is reached
action 1 debug counter 2 10 100

//Tell node 1 to stop sending counter packets
action 1 debug counter 0 0 0

Reading the Memory of a Node

It is possible to read any part of memory of a node that is available over the mesh network. It goes without saying, that this command is very powerful and a big security issue. It is therefore not (and must not be) included in release builds. The length is limited to 32 bytes and multiple reads should be done if more memory is to be requested. By defining ACTIVATE_UNSECURE_DEBUG_FUNCTIONALITY, it can be activated in any featureset for testing, e.g. by sending a modified version of the same firmware as an update.

//Query any node to return its memory at a given address
action [nodeID] debug readmem [address] [length]

//Read the first 10 bytes of memory starting at flash address 0x00000000
action 1 debug readmem 0 10

Saving & Retrieving Records

It is possible to store, retrieve or delete a record by using the terminal on the local node. This will invoke the RecordStorage class.

//Save record with given ID and data
saverec [recordId] [hexString | base64String]

//E.g. saves or updates a record with ID 1234 and data AA:BB:CC
saverec 1234 AA:BB:CC

//Get record with given ID
getrec [recordId]

//Delete record with given ID
delrec [recordId]

Print Active Advertising Jobs

Prints the registered advertising jobs of the advertising controller.

advjobs

Printing a Log of all received Advertisement Messages

This command is helpful to log all received advertisement messages and print their payload in a readable way. Most important information is printed for all known messages. Also, the raw data is printed as well. A number of filters can be used to scan for a number of identifiers in the message and also filter for a certain message type.

scanlog {deviceIdentifier=*} {messageType=0}

Examples

//Prints all received advertisement messages
scanlog
scanlog *

//Prints JOIN_ME messages received from any node
scanlog * 1

//Prints MeshAccess Broadcast messages from the node with the serialNumber BBBBB
scanlog BBBBB 3

//Prints all messages where the BLE Address of the sender is AA:BB:CC:DD:EE:FF
scanlog AA:BB:CC:DD:EE:FF

//Stops printing received messages
scanlog off

Boost scanning for some time

Useful in combination with scanlog, this will register a scanjob with a given timeout (by default 60 seconds) in which the node will scan as much as possible. A maximum of 10 minutes is supported. Executing it multiple times will register multiple scan jobs.

scanboost {boostTimeSec=60}

Heap

Prints statistics about the current heap usage.

heap

Flash Memory Map

Prints a map of used flash memory blocks (1024 kb). 0 stands for empty and 1 for containing data.

memorymap

Read Memory

Sometimes it is useful to read back some of the memory contents of a node while being connected.

readblock ["flash" | "uicr" | "ficr" | "ram"] [blockId] [numBlocks]

//Read the first block of memory of the flash
readblock flash 0 1

There are more commands that are not documented here. You can find them by looking at the TerminalCommandHandler in the source code. These commands may be removed or changed at any time.