Node

action [nodeId] node discovery [on / off]

It might be necessary to switch the node’s state machine into a different discovery state. This can be done through the mesh and can be used by a MeshGateway to turn off discovery once all enrolled nodes are connected. This allows the node to use a very low power consumption if scanning does not have to be active for other tasks.

Once the node loses a connection to one of its partners, it will automatically switch discovery on again.

Examples

The response acknowledges the receipt of the command.

action [nodeId] node set_preferred_connections [ignored / penalty] {up to eight preferred nodeIDs}

Sets the given nodeIDs as preferred connection partners while meshing. Other partners will be either completely ignored or their cluster score gets a heavy penalty. Executing this command without any nodeID disables this feature. After saving the preferred connections, the node reboots after a delay of 10 seconds. The "ignored / penalty" parameter determines the behaviour regarding the unpreferred connection partners, meaning any nodeID that is NOT in the thereafter following list. NOTE: For a connection to happen, both connection partners have to set each other as a preferred connection partner. This means that if you want to set the preferred connections of a mesh, you should best start at the leafs of the mesh.

WARNING!!! Using this command with the "ignored" parameter must be used with caution as using invalid or unreachable nodeIDs results in a state where the mesh can not be created. If this happened to you, you have two options: 1. flash the beacon. This erases the set preferred connections. 2. Connect to the beacon via a mesh access connection and execute the command again with correct parameters.

Examples

The response acknowledges the receipt of the command.

Following low-level data structure transports sensor measurement values across the mesh.

The packet header consumes 12 bytes, which allows for 8 bytes of payload in a single packet and should be enough for most sensor values. For bigger payloads, it will be split.

The output on a sink will be:

The following message is used for transporting write or read requests through the mesh.

No json representation is necessary for the moment as the meshgateway will not react on act messages.

status

It is very conveniant to get easily readable information about a node. The status command displays the currently active connections and their state. It also display device information and the clustering state.

The following will be printed on the local terminal after the command was entered:

When working with UART (Terminal and Uart must be enabled), FruityMesh supports a convenient blocking terminal mode with echo back functionality. For communication with another device such as a MeshGateway, an interrupt based input method and json output is used. To toggle between these two modes, there are two commands.

startterm

Using startterm will use a blocking mode where all functionality is halted and user input is received in a busy loop until a line feed '\r' is received. The command will then be processed and other functionality will be resumed. The input will be echoed back on the terminal and backspace is supported as well for most terminal programs. If the command cannot be recognized, a warning will be echoed.

stopterm

The stopterm command will switch the node into an interrupt based input mode where terminal input does not affect the functionality until a line feed '\r' is received. All output messages will be in json format.

Sending raw data can be used to send any arbitrary data, for example (but not limited to) zip files. The data which should be sent is split into various chunks which are then sent through the mesh. The data which should be sent is called the "payload".

Every raw data transaction (except raw_data_light, which will be explained later) starts with a raw_data_start message. This message includes the amount of chunks in the transaction and the protocol of the payload. Once the receiver receives this message, he answers with a raw_data_start_received message, which indicates to the sender that the receiver is ready for the transaction of the chunks.

When the sender receives this message, he starts sending all the raw_data_chunks. Besides part of the payload, every raw_data_chunk includes a chunkID which is a uniquely (regarding the current transaction) ascending number, starting at 1 for the raw_data_chunks. The chunkID 0 is reserved for the raw_data_start which always implicitly has the chunkID 0. Using this chunkID, and the information of the amount of chunks form the raw_data_start message, the receiver is able to determine whether or not a received chunk is the last chunk in the transaction. Once he receives the last chunk he reports back to the sender using a single raw_data_report. This message includes up to three missing chunkIDs. If all chunks were received, the list of missing chunks is empty, which tells the sender that the transaction was successful. If however, the list of missing chunks is not empty, the sender must send the chunks with the corresponding chunkIDs again. The last chunkID of the previous raw_data_report message acts as a last chunk, regarding the sending of additional raw_data_reports. This sending of raw_data_chunks and raw_data_reports is repeated until raw_data_report has an empty list of missing chunkIDs.

All devices involved in the communication (meaning both sender and receiver as well as the mesh) are able to cancel the communication by sending a raw_data_error message to the sender as well as the receiver. If the sender or the receiver is the device that hung up the transmission, it is allowed to not send the error to itself. The raw_data_error message includes an error code, indicating the reason for the cancellation. It is possible to receive a raw_data_error message without an open transmission. This can happen for example, if the sender cancels the transmission using a raw_data_error, but this error is dropped during the transmission. The receiver then might send another raw_data_error indicating a timeout while the sender already canceled the communication. Such messages without an open transmission may be discarded.

As any other message in the mesh, every message in the raw send protocol could be dropped. This section describes how an implementation must behave in such scenarios. It also tells the obligations of the sender and the receiver.

raw_data_start [receiverId] [destinationModuleId] [numChunks] [protocolId] {requestHandle = 0}

This command starts a raw data transmission. The payload shall be sent using raw_data_chunk messages.

If received by a JSON capable device, the raw_data_start will be printed out like this:

raw_data_start_received [receiverId] [destinationModuleId] {requestHandle = 0}

Once a raw_data_start is received, the receiver shall send the sender a raw_data_start_received message.

If received by a JSON capable device, the raw_data_start will be printed out like this:

raw_data_chunk [receiverId] [destinationModuleId] [chunkId] [payloadHex] {requestHandle = 0}

Once a raw transmission was started, the appropriate number of chunks should follow in the correct order. Once the last chunk is received by the receiver it is possible to reassemble and parse the whole message. The moduleId is present in all chunks so that they can be assigned to the correct stream and to avoid clashes between different modules. A module can send intermittent data streams if is uses different request handles.

If received by a JSON capable device, the raw_data_start will be printed out like this:

raw_data_report [receiverId] [destinationModuleId] [MissingChunkIds] {requestHandle = 0}

Once the last chunk is received, the receiver sends this message to the sender, indicating either a successful transmission (empty missing chunk IDs) or informs the sender about missing chunk IDs.

If received by a JSON capable device, the raw_data_start will be printed out like this:

Or in cases where the transmission was successful:

raw_data_error [receiverId] [destinationModuleId] [errorCode] [destination] {requestHandle = 0}

This command indicates that some error occurred and the transmission must be closed. Will be sent to the receiver as well as the sender.

If received by a JSON capable device, the raw_data_error will be printed out like this:

raw_data_light [receiverId] [destinationModuleId] [protocolId] [payload] {requestHandle = 0}

Sends a single, responseless chunk of arbitrary data to the receiver. There is no guarantee that the message is transmitted. The sender thus should make sure to have some resending logic.

If received by a JSON capable device, the raw_data_start will be printed out like this: