Caution! Article for developers

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

Device Management with DM Commands

Feb 3, 2023 · 21 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 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.

Fig.: Device objects in Treon products

 

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>
}
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 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>
}
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.

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.

ReleaseID:3ID:4ID:5ID:9ID:33580ID:33581ID:33582ID:33583
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

 

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)

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

 

Connectivity Monitoring Object (ID:4)

ResourceIDTypeOperationDescription
Network Bearer0uint16GetNetwork bearer used to connect the backend
Signal Strength2uintGetSignal strength of the current network bearer
IP address4stringGetAssigned IP address of the interface
APN7stringGetAccess point name. Empty if connectivity is something else than cellular

Network bearers:

ValueDescription
0GSM cellular network
1TD-SCDMA cellular network
2WCDMA cellular network
3CDMA2000 cellular network
4WiMAX cellular network
5LTE-TDD cellular network
6LTE-FDD cellular network
7NB-IoT
21WLAN network
41Ethernet

 

Firmware Update Object (ID:5)

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

ResourceIDValue FieldOperationDescription
Package URI1stringSetFirmware package download URI
Update2stringExecuteUpdates the downloaded software
State3stringGetFirmware update status
Update result5stringGetFirmware 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)
1Firmware updated successfully
2Not enough memory for the new firmware package
3Out of RAM during downloading process
4Connection lost during downloading process
5Integrity check failure for new downloaded package
6Unsupported package type
7Invalid URI
8Firmware update failed
9Unsupported protocol

 

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

 

Software Management Object (ID:9)

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

ResourceIDTypeOperationDescription
Package URI3stringSetURI for fetching FW image
Install4N/AExecuteStart installation of downloaded FW image
Update state7uint16GetFW update status

 

Firmware Update Status:

ValueDescription
0Initial state, before downloading
1The downloading process has started and is on-going
2The package has been completely downloaded
3The package has been correctly downloaded and is ready to be installed
4INSTALLED

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:

ValueDescription
0Main OS

 

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

 

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.

 

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.

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 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.

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 Firmware 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.

 

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.

ResourceIDTypeOperationDescription
Manufacturer0stringGetManufacturer name
Model1stringGetA model identifier
Serial number2stringGetDevice serial number
FW version3stringGetCurrent firmware version
Reboot4stringExecuteForce device reboot
HW version18stringGetDevice HW version

 

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='
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 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)

Fig.: DM_Server and Treon Gateway

 

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.

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. 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

Clean the surface

 

 

Treon Customer Support

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

   


Was this article helpful? Let us know.
Previous