Telemetry2U Technical Bulletins

Bulletin T2U TB09

Custom Payload Decoder Examples

Target audience:
Individuals or companies wanting add their own devices to T2U
Applies to:
All registered users with Node Administration access.
Release date:
June 22, 2022

Prerequisites

  1. A Telemetry2U account running on a free trial or a paid subscription. Refer to the T2U Quick Guide to help get up and running.
  2. Node Maintenance access on your Telemetry2U account. If you don’t have Node Maintenance, you’ll first need to contact your company administrator and request that they grant access.
  3. You've read the doccumentation on creating custom devices in the Telemetry2U Documentation.

Summary

This guide is intended to provide some working examples and a general breakdown of some custom payload decoders for various LoRaWAN devices. Once a custom payload decoder has been created, it will be available for selection as a Device Configuration on the Admin >> Node Maintenance section.

For each device, we will also create a few custom downlink commands. Once complete, these commands will be available to send via Admin >> Send Node Commands section. You will also be able to configure Dashboard buttons with the same commands.

Read more about configuring dashboards in Section 6.4.4 of the T2U Documentation.

.

To create a new ciston decoder navigate to Admin >> Custom Devices and click the Create New link in the top left corner of the new page.

Below are some example Custom Devices we have created on T2U.

Custom Decoder for a Dragino LT22222L I/O Controller.

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 Feild 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.
Reserverd 8 1 FF Resereved 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 interger (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 Reserverd 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.

Note:

Using Match Offset ensures the correct decoder is used for the payload type. Use the Next Decoder option to cycle through multiple decoders until the Offset matches. In the case of the LT22222L that has 5 operating modes, we could create 5 separate decoders and use the 11th byte determine which one should be used.

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

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

Dragino LT22222L Downlink Commands

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

Custom Decoder for a Netvox RB11E PIR

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.

Note:

In the above case, the packet will be run through the Next Decoder if one is selected.

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.

Netvox RB11E Custom Decoder

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.

Note:

Check on the Netvox RB11E Manual for more information.

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

Netvox RB11E Downlink Commands

Click the Save button when complete.

Custom Decoder for a Milesight WS523 Smart AC Socket

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.

Note:

For the socket status, (Byte-2) we defined a Low Limit and a High Limit. The WS52x sends 0x00 when the socket is off and 0x10 when the socket is on. We only want to see 0 or 1 on Telemetry2U.

The final custom decoder should look like the below example.

Milesight WS523 Custom Decoder

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
Note:

For any commands that have variables, the variables must be entered in LSB as defined at the top of the page. i.e. 3600 = 0x10 0x0E (100E).

Milesight WS523 Downlink Commands

Click the Save button when complete.