Device Management with DM Commands

Feb 3, 2023 · 21 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 and to change their configuration.

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.
• Gateways: relay messages between internet and mesh networks. Gateways also contain device management targets.

Logically, 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/Gateway JSON

Command Message

The backend sends device management 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 reqsource 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.

Gateway

Object Support

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

If the device management command is targeted to a node in the mesh network by setting Nid, the support depends on the software version of the node that is addressed. The Treon Gateway will only pass the command 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)

Connectivity Monitoring Object (ID:4)

Network bearers:

Firmware Update Object (ID:5)

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

Update state:

Update result:

Error codes

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

Software Management Object (ID:9)

This object is used to manage single software packages in the Treon Gateway.

Firmware Update Status:

If executing the Install Resource failed, the state remains at 3.
If executing the Install Resource was successful, the state changes from 3 to 4.

Object instances:

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:

Node FW Object (ID: 33581)

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

This object follows specification of Firmware 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 firmware image is first downloaded to the gateway, which will then deliver the software to the target nodes.

This object follows specification of Firmware 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 Firmware 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.

Sensor Nodes

Device management objects for specific sensor nodes objects are defined in a separate documentation. Sensor nodes may implement also the common device object. Software 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.

Examples

Gateway Targets

Get resources

Read resources model (1), serial number (2) and fw 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

Command:

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

Initiates Treon Gateway reboot sequence. No reply.

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 Gateway Firmware 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 images at https server which does mutual authentication using device and server certificates.

Result of the update should be checked finally by reading FW image version (Object: 3, Resource : 3)

Treon Industrial Node Firmware Update

Depending on the node, there may be one or multiple separate image file that can be updated. If the sensor contains application MCU, its firmware can be updated with Node FW 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. Update server needs to question the 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 upadte. 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 paramater 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 swith 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 Customer Support

If you have further questions, please contact Treon Customer Support.