Device Management with DM Commands - Full Guide

Oct 23, 2024 · 24 minutes to read

Introduction

Treon products, from the Treon Gateway to Treon Industrial Nodes, within a mesh network can be addressed via device management (DM) commands.

These DM commands can be used to acquire information from the products, to change their configuration and to update them.

Device management system

The device management system has three main components:

• Backend: sends DM commands and analyses the responses.
• Targets: objects to be managed. Objects may contain several resources that are managed.
• Treon Gateways: relay messages between internet and mesh networks. Treon Gateways also contain device management targets.

Logically, the managed system is comprised of instances of various objects. Each object has a specific set of resources that can be either read, written or executed.

Interfaces

Backend/Treon Gateway JSON

Command Message

The backend sends DM commands as JSON serialized messages over MQTT.

{
    "Ver": <version>,
    "Type": "dm",
    "Cmd": <command>,
    "I": <index>,
    "T": <target>,
    "Res": <resource array>
    "Val": <value array>,
    "Nid" : <node id>,
    "Gid" : <group id>
}

Target fields are defined as:

Resource array may by either:

• array of resource ids_ [resource_id1, resource_id2,…,resource_idn]
• array of resource_id,resource instance pairs: [[resource_id1, instance1], [resource_id1, instance2],…,[resource_idn, instance1]]

In the first version of the array, resource instance is default (0). The initial implementation supports only this mode.

Ver provides a way for receiver to judge if it can parse the JSON message. MAJOR number change indicates backwards compatibility break e.g. renamed labels.

Type define message type to be ‘device management’ (dm). This is useful for cases which do not provide proper message classification e.g. via MQTT topics.

Cmd defines if the values will be written or read from the node or if the resource need to be executed (e.g. reset)

I field is used to pair acknowledge messages with commands. The sender of the command may select an index number between 0-255.

T and Res fields define which values are read or written. Only a single object type and instance may be selected, but several resources within the object instance can be handled with the same command.
For example; accelerometer object contains several resources, like G-range setting and sample rate.

Val contains values for set or execute commands. This field is not valid for ‘get’ command message. Values are presented as base64 encoded bytearray. Each defined resource must have respective element in val-array. If resource uses multi-byte integers those are presented as little endian values. Required values are defined by the resource.

Example: accelerometer object has resource ‘Max ODR’ which requires an integer value between 0-65535. Value 5000Hz byte presentation is 19[MSB],136[LSB]. This results value byte array [136,19] which is base64 encoded as ‘iBM=’

Nid (sensor node id) or Gid (group id) are used to set the target devices for the command. Nid will be used if it is present in the JSON. If both target device identifiers are missing the command is targeting the receiving unit i.e. the gateway. Nid can be set to ‘BROADCAST’ which results the command to be sent all connected nodes. Group id requires that nodes are pre-configured to belong to the group.

If the command is sent to a group or broadcasted it will result several reply messages from each receiving node.

Response message

Targeted nodes send back a response message containing the status of the request and possible results and error values.

Set-command response

This is valid also as execute command.

{
    "S": <status>,
    "T": <target>,
    "I": <index>,
    "Type":"dm",
    "Nid" : <node id>,
    "Res": <resource array>,
    "E": <array of error codes>
}

The response will always come from a specific node address even if a BROADCAST or group id is used to address nodes. The Res and E fields will be present only if status code indicates an error.

Error codes:

Get-command response

{
    "S": <status>,
    "T": <target>
    "I": <index>,
    "Type":"dm",
    "Nid" : <node id>,
    "Res": <resource array>,
    "Val": <array of string>,
    "E": <array of uint>
}

The Val field array contains the response value for a respective resources in the Res array. The content is a base64 encoded byte array. Multi byte numbers are presented as little endian. The content is resource id specific.

The data for failed resources is set to empty string. The E field will be set for those resources if the error data is available.

Error codes:

DM objects

All managed resources are contained within DM objects. Some of the objects are Treon-specified, but OMA specified objects are used whenever feasible.

Treon Gateway

Object support

This table lists the support for different Treon Aito Release for Gateway versions. The columns list object ids and the rows show resource support for a firmware release.

If the DM command is targeted to a node in the mesh network by setting Nid, the support depends on the Treon Aito Release for Industrial Node firmware version of the node that is addressed. The Treon Gateway will only pass the command on to the node.

Device object (ID: 3)

Reference: OMA URN: urn:oma:lwm2m:oma:3:1.1. This is not fully LWM2M compatible as some of the mandatory resources are not implemented (Error code & Supported Binding and Modes). These values are encoded as UTF and must be decoded accordingly.

Treon Aito Release for Gateway update object (ID:5)

The Treon Aito Release for Gateway firmware can be updated by using this object.

Update state:

Update result:

State of the process can be reset to idle by sending set package download URI command with empty string as payload.

E.G. {"Ver": "2", "Cmd": "set", "T" : [5,0],"Res":[1],"Val":[""],"I":22}

Error codes

These are additional error codes returned with the E:[<Error code>] field.

Wirepas object (ID: 33580)

Resource for controlling Wirepas mesh devices.

Object instance is used to target the sink:

AppConfig resource

Application Configuration data is set to sink. This data is sent to each mesh network node as they join the network or if the AppConfig data changes.

Value: bytearray:

Keys resource

Value: bytearray:

Treon Aito Release for Industrial Node object (ID: 33581)

This object is for installing Treon Aito Release for Industrial Node firmware for nodes in the mesh network. The object controls the update process from the Treon Gateway. The Treon Aito Release for Industrial Node image is first downloaded to the Treon Gateway, which will then deliver the firmware to the target Treon Industrial Nodes.

This object follows specification of Treon Aito Release for Industrial Node Update Object (ID:5) with the following exceptions:

Update Execution:
The update execution requires following byte array of parameters. Any parameter value set to 0 will use default values.

An update in progress can be cancelled by sending the update execution command with a parameter of single byte set to 0xDA.

Update status

The update status is a byte array of variable length depending on the current state. The status values are the same, but additional info on nodes and progress will be appended.

The sensor node serial number is presented as a little endian unsigned 32 bit number, e.g serial# bb3ff36a is presented with bytes 0x6a,0xf3,0x3f,0xbb ‬

Update result

In addition to the result, this is also a byte array that contains the successfully updated nodes after the update has been finished.

Please note:

• State resource must be read prior to reading update result.
• Sensors serial numbers are available only if update is completed. Otherwise only Update result field is returned.

Error codes

These are additional error codes returned with the E:[<Error code>] field.

Wirepas Firmware Object (ID: 33582)

Object for installing Wirepas firmware for nodes and sink in the mesh network. The object controls the update process from the Treon Gateway.

The Wirepas firmware image is first downloaded to the Treon Gateway, which will then deliver the software to the target nodes.

This object follows specification of Treon Aito Release for Gateway Update Object (ID:5) with following exceptions.

Update Execution:
The update execution requires following byte array of parameters. Any parameter value set to 0 will use default values.

OTAP Status:
Additional resource with id 128 is used for querying otap status of the network.

In addition to Treon Aito Release for Gateway Update Object’s (ID:5), the following result codes are added:

Update Status

Update status is a byte array of variable length depending on current state. The status values are still same, but additional information on the nodes and the progress will be appended.

Please Note:
The addresses are the Wirepas addresses and not the node serial numbers!

Update Result

In addition to the result, this is also a byte array that contains the successfully updated nodes after update has been done.

Please note:

• Node addresses are available only if the update is completed. Otherwise only the Update result field is returned.
• The addresses are the Wirepas addresses and not the node serial numbers!

OTAP Status

The OTAP sequence number can be queried from the network by executing resource 128. After execution, the OTAP status will be queried from the network for one minute. During this time, any attempt to execute the query again will fail.

Statuses can be read by using get on resource 128.

Node address and scratchpad sequence will repeat for the amount of nodes.

Bluetooth device object (ID: 33583)

Object for changing iotgw bluetooth configuration.

After successfully setting the configuration, the Treon Gateway has to be rebooted. This can be done with device object.

Connected devices object (ID: 33584)

Object for requesting information about connected devices.

Note: this is a CBOR object, please refer to this guide on how to use it.

Node wirepas parameter settings object (ID: 33585)

Object for setting node wirepas parameters using wirepas remoteapi.
Note: This can result in irreversible changes to the nodes, make sure you know what parameters you are changing.

Note: this is a CBOR object, please refer to this guide on how to use it.

Object instances are created for each sink (if available):

Maintenance and Time options (ID: 33586,0)

This object is available only with newer version of the gateway parser. To use the newer version, the Ver-field of the command should be 2.1.

Object for configuring software inside gateway.

Notes about WpLogic-parser output format:

• The value returned is the on in use. This means that setting the value will not reflect in the get-command.
• To apply the new value, you will need to reboot the gateway with e.g. object id 3, resource 4
• Allowed values are:
  • legacy: Sends scalar and burst message formats
  • fragment: Sends scalar and frag message formats
  • vector: Sends scalar and vector message formats

Manual time

With this object and resource it’s possible to

• Read if the Treon Gateway is using manual time and it’s time (of when the message was sent).
• Set to use automatic/manual time and the time.

When using operation Get or Set operation the returned value is bytes with format:

Errors

Wirepas FW Object v2 (wirepas otapv2) (ID: 33587,0)

This object is available only with newer version of the gateway parser. To use the newer version, the Ver-field of the command should be 2.1.

Object for installing wirepas firmware for nodes and sink in the mesh network. The object controls the update process from the gateway. Firmware image is first downloaded to the gateway which will then deliver the software to target nodes.

Cbor content specified by [5]

Errors returned

The commands might return one of below errors in E-field:

OTAP Status

Otap sequence number can be queried from the network by executing resource 128. After execution the otap status will be queried from the network for one minute. During this time any attempt to execute the query again will fail.

Statuses can be read by using get on resource 128.

Sensor nodes

DM objects for specific sensor nodes objects are defined in a separate documentation. <!— where? —> Sensor nodes may implement also the common device object. Treon Aito Release for Industrial Nodes firmware management for sensor nodes is implemented via the Software Management Object provided by the Treon Gateway.

Device Object (ID: 3)

Same as device object for the Treon Gateway. These values are encoded as Hexadecimal numbers and must be decoded accordingly.

Examples

Treon Gateway Targets

Get resources

Read resources model (1), serial number (2) and Treon Aito Release firmware version (3) from device object (3).

Command:

{"Ver": "2", "Cmd": "get", "T" : [3,0],"Res":[1,2,3],"I":57}

Response:

{"S": 0,"T": [3, 0],"Res": [1, 2, 3],
   Val": ["VHJlb24gR1cA", "OTM0Yzc2ZGQ=", "NS4xLjEuMjAxOTA2MjAxMTM1NDI="],
   "I": 57,"Type": "dm"}

S equals 0 indicates successful get operations.
T indicates target for ‘get’-command: object id=3, object instance = 0
Res indicates resource ids that were read.
Val contains read values in the same order as they appear in Res. Value for resource id 3 is NS4xLjEuMjAxOTA2MjAxMTM1NDI=. This is base 64 encoded string. Decoding it produces 5.1.1.20190620113542 which is the FW version of the gateway device object.

Get resources with error

Command:

{"Ver": "2", "Cmd": "get", "T" : [3,0],"Res":[1,9,2,4],"I":83}

Response:

{"S": 1,"T": [3, 0],"Res": [1, 9, 2, 4],"
  Val": ["VHJlb24gR1cA", "", "OTM0Yzc2ZGQ=", ""],
  "E": [2, 3], "I": 83,"Type": "dm"}

S equals 1 indicates that some get operations failed.
T indicates target for ‘get’-command: object id=3, object instance = 0
Res indicates resource ids that were read. There is no resource id 9 for device object and resource instance 4 (reboot) does not support get-command.
Val contains read values in the same order as they appear in Res. Second and fourth value is empty string because that get command failed.
E contains the error codes for failed get command in the same order as get happened. Get resource id 9 error is 2 (unknown resource) and get resource id 4 error is 3 (function not supported).

Treon Gateway reboot

The command for forcing a reboot of the Treon Gateway after 1 minute is:

{"Ver": "2", "Cmd": "execute", "T" : [3,0],"Res":[4],"Val": ["AA=="],"I":22}

This initiates Treon Gateway reboot sequence.

Response:

{"I":22,"S":0,"Type":"dm","T":[3,0]}

Sensor node targets

Set measurement time interval for Treon Industrial Node

Command:

{"Ver": "2", "Cmd": "set", "T": [33507, 1],"Res": [2],"Val": ["CgA="], 
"I": 1, "Nid": "e054e288"}

T defines measurement control object.
Res defines measurement time adjustment.
Val defines the set value. For this instance the value is minutes expressed as uint16 integer. Setting measurement interval to 10 minutes. 10 (dec) = 0x000a (hex). Little endian presentation of 0x000a is ‘0a 00’. Base64 encoding this produces ‘CgA=’ I can be used to pair the command and response.
Nid selects the targeted node with serial number

Val field values can be easily produced with python:

E.g. Val for 48 minute measurement interval

>>>import struct
>>>import base64
>>>base64.b64encode(struct.pack('<H',48))
'MAA='

Response:

{"S": 0,"T": [33507, 1],"I": 121, "Type": "dm",  "nid": "e054e288"}

S equals 0 indicates success

On-demand measure

Command:

{"Ver": "2", "Cmd": "set","T": [33507, 1],"Res": [769],
"Val": ["AA=="], "I": 1,"Nid": "e054e288" }

Starts measurement. Val field is used for future parameters but it must contain 1 byte (here 0).

Response:

{ "S": 0, "T": [33507, 1], "I": 1,"nid": "e054e288","Type": "dm"}

S indicates success (0). After this message a normal measurement event is started

Treon Aito Release for Gateway Update

The update is performed by setting an update URI which will initiate the download. After the download has completed, the actual update can be performed. The Treon Gateway has a so called A/B partition update, meaning that during the last part of the update the gateway will reboot and is not able to respond.

Supported access protocols are http and https. Treon hosts the images on an https server which does mutual authentication using device and server certificates.

The result of the update should be checked finally by reading the Treon Aito Release for Gateway image version (Object: 3, Resource : 3)

Treon Aito Release for Industrial Node Update

Depending on the Treon Industrial Node, there may be one or multiple separate image file that can be updated. If the sensor contains application MCU, its Treon Aito Release for Industrial Node can be updated with Treon Aito Release for Industrial Node Object (33581). The update file will contain targeting information so that the node may detect if the update is valid for it.

Due to the nature of a mesh network, it is possible that some nodes will miss the update. For example, if a node has not been connected during the update. The update server needs to question the Treon Aito Release for Industrial Node firmware version (Object: 3, Resource : 3) from nodes to detect the update status of the whole network.

Wirepas Firmware Update

Wirepas firmware is updated using the method included in the Wirepas mesh stack. The new firmware image is uploaded to the sink stack scratchpad from where it propagates to all mesh nodes connected to it. The firmware image contains id, which enables receiving nodes either approve or dismiss the image.

Note Because Wirepas mesh in the only communication method between gateway sink and mesh sensors it is important that all sensors are updated. This concerns especially updating stack versions which are not compatible with each other e.g. WP4.x and WP5.x.

Update process phases:

1. Download firmware OTAP file to Treon Gateway.
2. Request OTAP status of the network.
3. When all the mesh nodes are available start update.
4. Monitor update status.
5. When update is finished read the final result.

Phase 2. is optional. It can be used to verify the all mesh nodes (sensors) are connected and ready to receive the firmware update. Knowledge of the expected nodes must be in the backend. The Wirepas stack and the gateway do not know which nodes should be reporting the OTAP status.

Wirepas Update Parameters

OTAP Sequence

OTAP sequence acts like a version number used by a receiver to decide if it should use the update. When set to 0, the Updater will automatically select the next valid OTAP sequence number.

Update Target

When updating between incompatible firmware versions this value should be set to 3 (both sink and nodes). Otherwise the sink cannot hear the responses when it tries to collect update result for phase 5.

Range: 1-3

Expected Node Count

If number of nodes is known setting this value will reduce the scanning time. Scan will finish as soon as the expected number of nodes have reported.

Range:0-65536

Scan Timeout

If expected number of nodes is not set, gateway will scan the mesh network as set by this parameter and collect the list of mesh nodes. This list will be compared to the list scanned as the last step of update process.

Range:0-65536 s

Scratchpad Spread Timeout

Time waited after ‘Execute Update’ command before giving command to mesh nodes to apply the new firmware update. Value of this parameter depends on the size and the loading of the mesh network. If timeout is too short it is possible that some mesh nodes have not received the new firmware image before nodes start to switch to the firmware.

Range:0-65536 s

MSAP Update Delay

Wirepas stack value that delays the firmware update after the node has received the command to apply the new firmware image.

In addition the stack will add a random 0-20 s delay to given value.

Range: 10 - 32767 s

Treon Support

You still have questions? Our dedicated team of experts is happy to help you! Please contact Treon Support directly by e-mail.

Did you know? Treon offers Premium Support and Maintenance Packages for our customers. Get even more out of Treon and boost your sales - inquire now about features and prices!