DM Quick Guide - How to form DM Commands

Feb 3, 2023 · 4 minutes to read

How to Form DM Commands

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 that the Treon Gateway knows what kind of format to expect. 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. A reply contains the same index number which was on the command itself.

If you modify the index value for example to 1 for the first message and 2 for the second message, then you can connect the reply to the original message.

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 the example, resource ‘1026’ is used.

Command Field

The “Cmd” defines the command that is used. It can be 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 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 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

In the example above, we are enabling the Timed1 measurements. The DM document 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)

In the Big Endian hex format that is:
0x0001

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

Then the value needs to be converted to the Base64 format. On linux terminal you can use ‘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 ‘echo “AQA=” | base64 –decode | xxd -p’ which decodes the Base64 format and creates a hexdump from that output.

Treon Customer Support

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