Node Module (ID 0)

The NodeModule is the central part of the BlueRange Mesh algorithm. It is a mandatory module. It is responsible for clustering and other mesh related tasks and functionalities that are part of BlueRange Mesh. It also has additional core functionality implemented.

The node keeps track of all MeshConnections and monitors connects and disconnects. It works in conjunction with the MeshConnection and ConnectionManager classes for this. The node is also responsible for broadcasting mesh discovery (JOIN_ME) packets. It also activates scanning if necessary and monitors the incoming discovery packets of other nodes. It creates new MeshConnections to other nodes if necessary. A state machine is used to toggle between different discovery states.

The node only permits one mesh handshake at a certain time. During the handshake, both mesh nodes exchange information about their clusters and decide which cluster is the biggest one. The packets used are specified under Clustering Messages. During the handshake, a backup of the current cluster state is made and used throughout the handshake. After the handshake, cluster changes that happened in the meantime are sent to these connections. Updates of the cluster size or structure are also sent to all MeshAccessConnections.

On reboot, the firmware sends a JSON to a device that is connected to the terminal output, providing more information about the reboot. The JSON has the following structure:

The reason can have the following values:

The reboot reason is also stored in the error log

The capability retrieval command helps a user (e.g. the Bluerange Gateway) to find out what some node in the mesh is capable of. Such a capability can be for example if it is a Regent lamp and if so, how many heads and sensors are connected to it. A node can return an arbitrary amount of capabilities, each in its own message. A single capability consists of the following data:

Each module in the firmware has a function with the following header: CapabilityEntry GetCapability(u32 index, bool firstCall). The function is called with consecutive indices, starting with 0 for every module. If the module has a capability for this index available, it should be returned accordingly. If none is available with the given index, the CapabilityEntryType::INVALID must be returned. No other valid capabilities may follow after the first invalid index. For some capabilities, some connected vendor controller has to be queried first. In such a case, the capability is not yet ready, but may become ready in the future. CapabilityEntryType::NOT_READY is returned in these cases. The function will be called again with the same index shortly. For some modules it is important to know if this was the first call of the current capability retrieval. If the first capability of the module would return CapabilityEntryType::NOT_READY, the module cannot distinguish between the first call solely based on the index. For such cases, the bool firstCall is passed as well.

Hard- and software capabilities should list the individual components the device is made of. This can be reported as e.g.:

The metadata capabilities refer to additional documents build into the BlueRange system device catalog. The catalog data itself is maintained in and consumed by higher-level software components outside of firmware code. The document referenced states details regarding the actuators and sensors of the device incl. their types, units and possible ranges. Also characteristics curves of the power consumed for evaluation in smart metering may be part of the data provided.

As an example, the entry { CapabilityEntryType::METADATA, "Smart Lights Ltd.", "NightLight Moon", "1.0" } references version 1.0 of the catalog metadata for the product NightLight Moon of Smart Lights Ltd..

In addition properties may be made available. This may be used to report device-specific values that make no sense looking up in the device catalog. An example use is the number of heads in a multi-part device, e.g. { CapabilityEntryType::PROPERTY, "Smart Lights Ltd.", "Lamp head count", "2" }. The model name field serves as a key, while the revision serves as a value. Property data is vendor-specific and may be used in catalog data to check its applicability beyond just the hard- and software capabilities.

See this section on how to retrieve the capabilities through the terminal.

To synchronize a time over the mesh, the time needs first to be set on the local node using the settime command. The time is stored internally as an unsigned 32-bit integer together with an additional variable that stores the extra number of crystal ticks for better accuracy. The number of offset minutes is used to pass additional time zone information, e.g. pass 120 to get a time zone offset of 2 hours.

settime [u32 unixTimestampSec] [i16 offsetMinutes]

Afterwards, the local time of the local node can be queried on the terminal using:

gettime

The output gives the local time and date of the node in a human-readable format. This is only an approximate calculation. It is just to verify if the time was set correctly. Internally, the nodes work with Unix time stamps.

To query the local time of a node in the network with e.g nodeId 1234, the following command can be used:

action 1234 node gettime

Sample response:

{"type":"get_time_result","nodeId":1234,"module":0,"syncState":2,"time":1654247506,"offset":120,"master":0}

You can see if the requested node is currently regarded as the time master, which means that it was used to sync the time to the network. If logging is enabled, the timestamp will also be logged out in a human readable format.

get_modules [nodeId]

Often it is necessary to get a list of modules that are available on a node. The list provided by the get_modules command includes all modules that are available (compiled into the firmware): their moduleId, their version and whether they are currently active.

rawsend [dataHex]

Mostly used for debugging purpose, the rawsend command can be used to send any binary message through the mesh (as long as it is valid). The data can be given either base64 encoded or as a hex string with colons.

The node offers functionality for sending custom data through the mesh using a lightweight wrapper for either big or small messages. This is documented at the RawData page.