Caution! Article for developers

Information on this page is intended particularly for users with advanced technical knowledge.

Device Management with DM Commands - Full Guide

Dec 13, 2023 · 22 minutes to read

Treon Industrial Node Treon Industrial Node 6

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.

Fig.: Device objects in Treon products

 

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>
}
LabelTypeDescription
VerstringJSON specification version used in the message. Major-number of this document.
Type (optional)stringMessage type. Set to “dm”.
Cmdstring“set”/“get”/“execute”
Iuint (0-255)message index
Tarray of uint[object id,object instance]
Resarray of uint / 2-dimensional arraysee description below
Valarray of stringsbase64 encoded bytearray containing values for set command. Content is defined by resource id.
Nidstringnode id of targeted node or BROADCAST
Gidstringpre-allocated group id of targeted nodes

 

Target fields are defined as:

LabelTypeDescription
object iduint16
object instanceuint16HW specific instance

 

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>
}
LabelTypeDescription
Suintstatus code, values greater than 0 indicate error code
Tarray of uint[object id,object instance]
Iuintindex value is the same as respective command
TypestringMessage type. Set to “dm”
Nidstringnode serial number
ResarrayArray of failed resources
Earray of uintlist of error codes for failed resources

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:

ValueDescription
1Unknown target
2Unknown resource
3Function not supported. Targeted resource does not support the command.

 

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>
}
LabelTypeDescription
Suintstatus code, values > 0 indicate error code
Tarray of uint[object id,object instance]
Iuintindex value is the same as respective command
TypestringMessage type. Set to “dm”
Nidstringnode serial number
ResarraySee definition in ‘Set’-command message.
Valarray of stringbase64 encoded bytearray containing values for set command. Content is defined by resource id.
Earray of uinterror codes for failed resources

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:

ValueDescription
1Unknown target
2Unknown resource
3Function not supported. Targeted resource does not support the command.

 

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.

ReleaseID:3ID:4I D:5ID:9ID:33580ID:33581ID:33582ID:33583ID:33584ID:33585ID:33586
5.90,1,2,3,4,18,19-1,2,3,5-0,1,2,3------
5.100,1,2,3,4,18,19-1,2,3,5-0,1,2,3,4,5,61,2,3,5-----
5.110,1,2,3,4,18,19-1,2,3,5-0,1,2,3,4,5,61,2,3,51,2,3,5,128----
6.00,1,2,3,4,18,19-1,2,3,5-0,1,2,3,4,5,61,2,3,51,2,3,5,1280,1,2,3,4,5---
7.0.10,1,2,3,4,18,19-1,2,3,5-0,1,2,3,4,5,6,71,2,3,51,2,3,5,1280,1,2,3,4,50--
7.1.10,1,2,3,4,18,19-1,2,3,5-0,1,2,3,4,5,6,71,2,3,51,2,3,5,1280,1,2,3,4,5010,110,1

 

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.

ResourceIDValue FieldOperationDescription
Manufacturer0stringGetManufacturer name
Model1stringGetA model identifier
Serial number2stringGetDevice serial number
FW version3stringGetCurrent firmware version
Reboot4stringExecuteForce device reboot
HW version18stringGetDevice HW version
SW version19stringGetIOT gateway application SW version

 

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

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

ResourceIDValue FieldOperationDescription
Package URI1stringSetTreon Aito Release for Gateway package download URI
Update2stringExecuteUpdates the downloaded software
State3stringGetTreon Aito Release for Gateway update status
Update result5stringGetTreon Aito Release for Gateway update status

 

Update state:

ValueDescription
0Idle (before downloading or after successful update)
1Downloading
2Downloaded
3Updating

 

Update result:

ValueDescription
0Initial value. Once the updating process is initiated (download/update)
1Treon Aito Release for Gateway updated successfully
2Not enough memory for the new Treon Aito Release for Gateway package
3Out of RAM during downloading process
4Connection lost during downloading process
5Integrity check failure for new downloaded package
6Unsupported package type
7Invalid URI
8Treon Aito Release for Gateway update failed
9Unsupported protocol

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.

Error codeNameDescription
16CMD_FAILEDPackage download failed or exec update failed
17CMD_FAILED_UPDATE_ACTIVETrying to set uri while updating
18CMD_FAILED_SSL_ERRORVerification of SSL-certificates failed
19CMD_CONNECTION_ERRORConnection failed
20CMD_FAILED_INCORRECT_STATEState is incorrect to perform given operation

 

Wirepas object (ID: 33580)

Resource for controlling Wirepas mesh devices.

ResourceIDTypeOperationDescription
Node state0uint16Set,Get0 - mesh device off, 1 - mesh device on
Network Id1uint32Set,GetRange:
Network Channel2uint16Set,GetRange:
FW version3bytearray (string)GetSink Wirepas firmware version
AppConfig4bytearraySet,GetApplication configuration shared from sink to mesh network
Diagnostic Interval5uint16Set,GetWirepas diagnostic message interval. Valid values: 0,30,60,120,300,600,1800
Keys6bytearraySet,GetWirepas network keys
WpDiag7uint8Set,GetWirepas diagnostics parser (json). 0 off, 1 on. Gateway has to be rebooted after sending this command to apply it (device object 3).

 

Object instance is used to target the sink:

Obj InstanceDescription
0Sink 0
1reserved for future use
2reserved for future use
3reserved for future use

 

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:

ByteDescription
0AppConfig sequence number. Value 0 automatically increases the current value by 1.
1-80Application configuration data as bytearray.

 

Keys resource

Value: bytearray:

ByteDescription
0Algorithm ID. Used to identify key encryption scheme
1Key ID identities the used key. Set to 0 if not used
2-17Wirepas authentication key
18-34Wirepas cipher key
Alg IDDescription
0No encryption.

 

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.

BytesDefault valueDescription
0-30xFFFFFFFF (Broadcast)Wirepas destination address
4-110x1122334455667788Target parameter
12-131Delay before sending complete message (seconds)
14-151000Delay between each fragment (milliseconds)
16-1720Delay before node triggers update (seconds)
18-1930Delay waiting for responses (seconds)
20-215Delay after sending start, before first fragment(seconds)

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.

BytesDescription
0Status value
1Progress 0-100 (if status is UPDATING) (uint 8)
2-nRepeating 4 bytes of nodeid of each node that has responded to start (if status is UPDATING)

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.

BytesDescription
0Update result
1-nRepeating 4 bytes of nodeid of each node that has been updated successfully (If status is IDLE and update result is successful)

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.

Error codeNameDescription
16CMD_FAILEDPackage download failed or exec update failed
17CMD_FAILED_UPDATE_ACTIVETrying to set uri while updating
18CMD_FAILED_SSL_ERRORVerification of SSL-certificates failed
19CMD_CONNECTION_ERRORConnection failed
20CMD_FAILED_INCORRECT_STATEState is incorrect to perform given operation
21CMD_FAILED_INCORRECT_PARAMSArgs given with exec update are faulty

 

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.

BytesDefault valueDescription
00OTAP sequence (default 0 increases current in network by 1)
13Update target. Bitmask where bit 0=sink, bit 1=nodes. If set update target
2-30Expected node count (can be used to speed up process)
4-5180Scan timeout before and after update (seconds)
6-7180Timeout waiting for scratchpad to spread (seconds)
8-9240MSAP update delay before node takes new scratchpad into use (seconds, 10-32767)

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:

ValueDescription
128Failed to load scratchpad
129Invalid OTAP image
130Sink failed to process scratchpad
131Sink not found
132No nodes found
133Network in unstable state
134No nodes with otap enabled

 

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.

BytesDescription
0Status value
1Progress 0-100 (if status is UPDATING)
3-nRepeating 4 bytes of wirepas address of each node that has responded during initial scan (if status is UPDATING)

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.

BytesDescription
0Update result
1-nRepeating 4 bytes of Wirepas address of each node that has been updated successfully (If status is IDLE and update result is successful)

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.

BytesDescription
0Sink scratchpad sequence
1-4Node address
5Node scratchpad sequence

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

 

Bluetooth device object (ID: 33583)

Object for changing iotgw bluetooth configuration.

ResourceIDValue FieldOperationDescription
Mac addr0bytesGetReturns gateways MAC address.
Reporting interval1unsigned integerGet,SetHow often gateway should send cached bluetooth messages
Mac regex2stringGet,SetString to be interpret with python3 regex to match bluetooth mac addresses
Rssi level3integerGet,SetLowest rssi level accepted
Mac whitelist4stringGet,SetMac whitelist
Only latest5booleanGet,SetCache only latest message from bluetooth

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

 

Treon Aito Release for Gateway configuration object (ID: 33586,0)

Object for configuring Treon Aito Release for Gateway firmware inside the Treon Gateway.
This item requires “Ver”: “2.1” in the DM message.

ResourceIDValue FieldOperationDescription
maintenance connection0uint8Get,setGet/set status of Treon Gateways reverse SSH service for the maintenance connection. 0 off 1 on
manual time1bytesGet,setGet/set state of manual time.
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:

BytesDescription
00 if automatic time is used, 1 if manual time is used
1-9Time as epoch seconds u64, little endian. If automatic this will be ignored/not read but needs to still exist and can be e.g. all zeros.
Errors
CodeDescription
20Setting state of reverse ssh failed for some unknown reason
21Manual time payload format is incorrect

 

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.

ResourceIDTypeOperationDescription
Manufacturer0stringGetManufacturer name
Model1stringGetA model identifier
Serial number2stringGetDevice serial number
Treon Aito Release for Industrial Node version3stringGetCurrent Treon Aito Release for Industrial Node firmware version
Reboot4stringExecuteForce device reboot
HW version18stringGetDevice hardware version

 

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='
Time (mins)base64 encoded
10CgA=
30‘HgA=’
60‘PAA=’
120‘eAA=’

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)

Fig.: DM_Server and Treon Gateway

 

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.

Fig.: DM_Server and Treon Gateway

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!

   


Was this article helpful? Let us know.
Next
Previous