Custom Payload Decoder Examples

In this example, we’ll be creating a custom payload decoder and a set of downlink commands for a Dragino LT22222L I/O Controller running in MOD1 (AT+MOD=1). We'll create commands to control both relays and poll an uplink.

Referring to the LT22222L’s manual confirms the payload (uplink) is sent over Port 2 by default. Bytes can converted on the MSB.

An example payload given in the manual is 04AB04AC13101300AAFF01. It's 11-bytes in length, has a Field Count of 14. It breaks down as follows.

Table 1

Channel	Start Byte	Length (Bytes)	HEX Value	Data Type	Value	Scaling	Result
Volt 1 (AV1)	0	2	04 AB	Unsigned Int.	1195	/ 1000	1.195V
Volt 2 (AV1)	2	2	04 AC	Unsigned Int.	1196	/ 1000	1.196V
Current 1 (AC1)	4	2	13 10	Unsigned Int.	4880	/ 1000	4.880mA
Current 2 (AC2)	6	2	13 00	Unsigned Int.	4864	/ 1000	4.864mA
Digital I/O Status	7	1	AA	Refer to Table 2 below.
Reserved	8	1	FF	Reserved	255	1	255
Current 2 (AC2)	9	1	01	Match Offset	01	1	1

Bytes 0-7 represent the 4 analogue inputs (2-Bytes for each input). This should convert to an Unsigned integer (MSB) and divided by 1000 for the result.

The binary bit state of Byte-8 represents the digital I/O status (LSB).

For example, AA = 10101010.

Table 2

Byte 8	Bit Number	Bit State	Channel Status
Relay 1	7	1	Closed
Relay 2	6	0	Open
Digital Input - 1	5	1	High
Digital Input - 2	4	0	Low
Digital Input - 3	3	1	High
Digital Output - 1	2	0	Low/On
Digital Output - 2	1	1	High/Off
Digital Output - 3	0	0	Low/On

Byte-9 is reserved and not in use. We'll skip this byte with the Reserved Data Type.

Byte-10 converts to decimal (DEC) and represents the operating mode of the LT22222L. (1 = AT+MOD=1). In this case, we'll use Match Offset for the Data Type. If that byte's value does not exactly match the value in the Offset field, the decoder method will be aborted. It’ll processed by the Next Decoder if one has been defined at the top of the page.

With all the above information found in the Dragino LT22222L I/O controller manual, we can create the following decoder.

Once finished creating the custom decoder, click the Save button at the bottom of the page.

To create some custom downlink commands for the new device, navigate to Admin >> Custom Devices and click the Downlink Commands link to the right of the page.

To figure out what downlink commands are required to control both relays and poll an uplink, refer to the Dragino LT22222L I/O Controller Manual. These commands are defined as follows.

Again, click the Save button at the bottom of the page when finished.

The Netvox RB11E combines a temperature sensor, light sensor, and a room occupancy sensor (PIR). The Hex data payload and needs to be converted decimal (MSB). When the RB11E detects motion, it immediately sends an uplink. An example payload is 010301240B1C007B010000. It's 11-bytes in length, sent over Port 6 by default, and has a Field Count of 9. It breaks down as follows.

Table 3

Channel	Start Byte	Length (Bytes)	HEX Value	Data Type	Value	Scaling	Result
Version	0	1	1	Match Offset	01	1	1
Device	1	1	3	Match Offset	03	1	3
Report	2	1	1	Match Offset	01	1	1
Battery	3	1	24	Unsigned Int.	36	/ 10	3.6 (V)
Temperature	4	2	0B 1C	Unsigned Int.	2844	/ 100	28.44 (C)
Illuminance	6	2	00 7B	Unsigned Int.	123	1	123 (Lux)
Occupancy	8	1	01	Unsigned Int.	1	1	1
Tamper	9	1	00	Unsigned Int.	0	1	0
Reserved	10	1	00	N/A	N/A	N/A	N/A

The first 3 bytes (01 03 01) represent the Netvox command version, device type (RB11E), and the report type (data report). These bytes can be used to identify the packet as an actual RB11E data packet designed for this decoder. By using Match Offset as the Data Type for the first 3-bytes in the decoder, the decimal values will be compared against the decimal value set in the Offset field. If there’s a mismatch, the decoder will abort, and the data will not be converted.

The Battery, Temperature, Illuminance, convert to an Unsigned Integer but have different Scaling factors and Precisions.

The Occupancy and Tamper switch status' are either 0x00 or 0x01 - open or closed. They should never be anything else so we can use a Low Limit and a High Limit.

The last byte is not in use and should be skipped with the Reserved Data Type.

The final custom payload decoder looks as follows.

Click the Save button after making any changes.

Netvox commands work a bit differently than other devices in that they combine a bunch of settings into one downlink command. The first command sets the following.

1. Transmit time
2. Alarm transmit time
3. Battery voltage change
4. Temperature change
5. Illuminance chance

Basically, uplinks will be sent based on the transmit time. At the alarm transmit time interval, the RB11E will wake up and check the battery,temperature, and illuminance levels for a change. If either parameter has changed by more than the threshold, an uplink will be triggered. We won’t be taking advantage of the alarm setting in this example so we will make the Transmit time and Alarm transmit time the same. We will create two commands to change the transmit time to both 5-minutes and 60-minutes.

The RB11E will wake up and immediately send an uplink when it detects movement with the occupancy byte sent to 0x01 (occupied). After that, it will wake up at intervals to check if the room is still occupied, if no motion is detected in x time, it will send another uplink with the occupancy byte set to 0x00 (unoccupied). You can program both the wake-up/check time to adjust the IR sensitivity(DisableTime) and the DetectionTime with a second downlink command. We will create two commands that set the DetectionTime to both 30-seconds and 5-minutes.

To create some custom downlink commands for the new device, navigate to Admin >> Custom Devices and click the Downlink Commands link to the right of the page.

Our commands look as per the example below. Downlink commands should be sent over Port 6

Click the Save button when complete.

The Milesight WS52x in a smart AC power socket and meter. You can control the power output with downlink commands as well as measure real-time power statistics. The data uplink packed includes the socket status, voltage, active current, active power, power factor, and the total power consumption. The raw hex data needs to be converted to decimal data on the LSB. Each parameter varies in length and is preceded with a unique Byte that identifies the Channel and another unique byte that identifies the Type. Refer to the Milesight WS523x user manual for a more detailed breakdown of the uplink payload. With this decoder, we will use the first channel/type to identify the data uplink payload and filter out any other uplink types.

An example data uplink payload is 08700105816307C99D0D03743A090683D4360000048038030000. It’s 26-bytes in length, sent over Port 85. All parameters convert to decimal on the LSB. The pay load breaks down as follows.

Table 4

Channel	Start Byte	Length (Bytes)	HEX Value	Data Type	Value	Scaling	Result
Channel/Type	0	2	08 70	Match Offset	28680	1	28680
Status	2	1	01	Unsigned Integer	1	1	1
Channel/Type	3	5	05 08	Reserved	N/A	N/A	N/A
Power Factor	5	1	63	Unsigned Int.	99	1	99 (%)
Channel/Type	6	2	07 C9	Reserved	N/A	N/A	N/A
Current	8	2	9D 0D	Unsigned Int.	3485	/ 1000	3.485 (A)
Channel/Type	10	2	03 74	Reserved	N/A	N/A	N/A
Voltage	12	2	3A 09	Unsigned Int.	2362	/ 0.1	236.2 (V)
Channel/Type	14	2	06 83	Reserved	N/A	N/A	N/A
Consumption	16	4	D4 36 00 00	Unsigned Integer	14036	/ 1000	14.0 (kW)
Channel/Type	20	2	04 80	Reserved	N/A	N/A	N/A
Active Power	22	4	38 03 00 00	Unsigned Integer	824	1	824 (W)

As mentioned, the first 2-bytes in the data uplink packet will always be the same (08 70). Match Offset converts the field to DEC 28680 (LSB) and compares the value against the Offset. If these fields do not match, the packet will be ignored and will be processed by the Next Decoder if one has been defined.

The rest of the Channel/Type bytes for each channel will be ignored since we use the Reserved Data Type.

All the other channels are converted to Unsigned Integers with varying Scale Factors and Precision.

The final custom decoder should look like the below example.

Click the Save button when complete.

To create some custom downlink commands for the new device, navigate to Admin >> Custom Devices and click the Downlink Commands link to the right of the page.

We will create commands for the following.

1. Turn Power On
2. Turn Power Off
3. Turn Button Lock On
4. Turn Button Lock Off
5. Turn Power Off in 1-Hour

Click the Save button when complete.