Introduction to Device Management Commands

Dec 20, 2023 · 5 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.

How to form DM commands

A DM command consists of several fields defined with variables.

Example of a DM command:
{"Ver": "2", "Val": ["AQA="], "I": 1, "Res": [1026], "Cmd": "set", "Nid": "BROADCAST", "T": [33507, 1]}

Version field

The Version field “Ver” defines which version of the JSON specification to use. Based on this, the Treon Gateway knows what kind of format to expect and work with. The correct version number can be found in the DM documentation.

{"Ver": "2" , "Val": ["AQA="], "I": 1, "Res": [1026], "Cmd": "set", "Nid": "BROADCAST", "T": [33507, 1]}

Value field

The “Value” field “Val” is a Base64 encoded byte array containing values. The values are used with the set command. (The value can also be present in a get command also but will have no impact.)

{"Ver": "2", "Val": ["AQA="], "I": 1, "Res": [1026], "Cmd": "set", "Nid": "BROADCAST", "T": [33507, 1]}

I field

The “I” field is an index number of the message. You can choose that number by yourself. It is used to distinguish different messages and replies. If you send two identical commands, you will get two identical replies, but the index number contained in the reply helps you distinguish them.

If you set the index value to “1” for the first message and “2” for the second message, then you can connect each individual reply to the original message sent.

Example:
{"Ver": "2", "Val": ["AQA="], "I": 1, "Res": [1026], "Cmd": "set", "Nid": "BROADCAST", "T": [33507, 1]}

Here the index number “1” is assigned to the message. All replies to this message will also have the index number “1”.

Resource field

The “Resource” field defines the resource that is used. One object id can contain multiple resources. The correct resource number can be found in the DM documentation.

Example:
{"Ver": "2", "Val": ["AQA="], "I": 1, "Res": [1026], "Cmd": "set", "Nid": "BROADCAST", "T": [33507, 1]}
In this example, the resource used is ‘1026’.

Command field

The “Cmd” defines the command that is used. It can be either set, get or execute.

Example:
{“Ver”: “2”, “Val”: [“AQA="], “I”: 1, “Res”: [1026], “Cmd”: “set”, “Nid”: “BROADCAST”, “T”: [33507, 1]}

In the example, the set command is used.

Nid field

The “Nid” field defines the id of the node within the mesh network that the command is sent to.

Instead of a specific node id, the ‘BROADCAST’ target can be used to send the command to every node in the mesh network instead of targeting a specific individual node.

Example:
{“Ver”: “2”, “Val”: [“AQA="], “I”: 1, “Res”: [1026], “Cmd”: “set”, “Nid”: “BROADCAST”, “T”: [33507, 1]}

In the example, the “BROADCAST” target is used to send the command to every node in the network.

T field

The “T” field defines the target object id and instance. The correct object id can be found in the DM documentation.

Example:
{“Ver”: “2”, “Val”: [“AQA="], “I”: 1, “Res”: [1026], “Cmd”: “set”, “Nid”: “BROADCAST”, “T”: [33507, 1]}

In the example, the object id number ‘33507’ and instance ‘1’ are being used.

Convert the value to Base64 format

The Value in the DM command needs to be in the Base64 format.

In the example above, we are enabling the Timed1 measurement. The DM documentation tells that the value length is 2 bytes and the value can be calculated from the table. In the binary format it is:
(MSB) 0000 0000 0000 0001 (LSB)

Converted to the Big Endian hex format that is: 0x0001

The value must now be converted further to the Little Endian hex format (which means the least significant bytes are stored first): 0x0100

Then the value needs to finally be converted to the Base64 format. On a Linux terminal, you can use the command echo "0100" | xxd -r -p | base64, which creates a binary dump and converts it to the Base64 format: AQA=

The reverse method for decoding is to use the command echo "AQA=" | base64 --decode | xxd -p, which decodes the Base64 format and creates a hexdump from that output: 0100

Command message

The backend sends device management (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>"
}

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!