Stand with Ukraine flag
Try it now Pricing
PE Edge
Getting Started
Devices Library Installation Architecture API FAQ
On this page

UDP Integration

Doc info icon

Edge UDP Integration is implemented similarly to the UDP Integration. The only difference is how the integration is created and deployed. Before proceeding, refer to the UDP Integration documentation.

Overview

UDP Integration allows data to be streamed to ThingsBoard Edge from devices that use a UDP transport protocol, and converts payloads from these devices to the ThingsBoard Edge format.

Doc info icon

UDP Integration can only be started as a Remote Integration. It can be started on the same machine, where the TB Edge instance is running, or you can start it on another machine that has access to the TB Edge instance over the network.

To learn more, review the integration diagram:

image

Prerequisites

In this tutorial, we will use:

  • ThingsBoard Edge Professional Edition;
  • UDP Integration: The integration that runs externally and is connected to the ThingsBoard Edge instance.
  • echo command: To display a line of text, and redirect its output to the netcat (nc) utility.
  • netcat (nc) utility: To establish TCP connections, receive data from there, and transmit it.

Let’s assume that we have a sensor which is sending current temperature and humidity readings. Our sensor device SN-001 publishes the temperature and humidity readings to UDP Integration on port 11560 to the machine where UDP Integration is running.

For demonstration purposes, we assume that our device is smart enough to send data in 3 different payload types:

  • Text: The payload is
    1
    
    SN-001,default,temperature,25.7,humidity,69
    
  • JSON: The payload is
1
2
3
4
5
6
7
8
[
  {
    "deviceName": "SN-001",
    "deviceType": "default",
    "temperature": 25.7,
    "humidity": 69
  }
]
  • Binary: The binary payload is (in HEX string):
    1
    
    \x53\x4e\x2d\x30\x30\x31\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39
    

    Here is the description of the bytes in this payload:

    • 0-5 bytes: \x53\x4e\x2d\x30\x30\x3 - The device name. If we convert it to the text, it is SN-001.
    • 6-12 bytes: \x64\x65\x66\x61\x75\x6c\x74 - The device type. If we convert it to the text, it is default.
    • 13-16 bytes: \x32\x35\x2e\x37 - The temperature telemetry. If we convert it to the text, it is 25.7.
    • 17-18 bytes: \x36\x39 - The humidity telemetry. If we convert it to text, it is 69.
  • Hex: The payload is a hexadecimal string:
    1
    
    534e2d30303164656661756c7432352e373639
    

    Here is the description of the bytes in this payload:

    • 0-5 bytes: 534e2d303031 - The device name. If we convert it to the text, it is SN-001;
    • 6-12 byte: 64656661756c74 - The device type. If we convert it to the text, it is default;
    • 13-16 byte: 32352e37 - The temperature telemetry. If we convert it to the text, it is 25.7;
    • 17-18 byte: 3639 - The humidity telemetry. If we convert it to the text, it is 69;

Based on your device capabilities and business cases, you can choose the payload type:

Doc info icon

On the machine, running remote UDP Integration, port 11560 must be opened for incoming connections—the nc utility must be able to connect to he UDP socket. If you are running it locally, it should be fine without any additional changes.

Create Converter templates

To create Converter and Integration templates, log in to the Cloud instance as Tenant administrator.

Before creating the Integration template, create an Uplink and Downlink converter templates in Converters templates section.

The uplink data converter is needed to convert the incoming data from the device into the format required for display on ThingsBoard Edge.

  • Log in to the Cloud and go to the Edge management > Converter templates section. To create a Converter template, click the “Add data converter” button (the + icon) and select the “Create new converter” option.
  • In the “Add data converter” pop-up window:
    • Name: Enter the name of the data converter.
    • Type: Select the “Uplink” converter type from the drop-down menu.
    • To view the events, enable Debug mode.
    • function Decoder: Enter a script to parse and transform data.
    • Click the “Add” button.
Doc info icon

While Debug mode is very useful for development and troubleshooting, keeping it enabled in production can significantly increase database storage requirements, since all debug data is stored there.

We strongly recommend disabling Debug mode once debugging activities are complete.

Select the device payload type to use for a decoder configuration:

Now copy & paste the following script to the Decoder function section:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/** Decoder **/

// decode payload to string
var strArray = decodeToString(payload);
var payloadArray = strArray.replace(/\"/g, "").replace(/\s/g, "").replace(/\\n/g, "").split(',');

var telemetryPayload = {};
for (var i = 2; i < payloadArray.length; i = i + 2) {
    var telemetryKey = payloadArray[i];
    var telemetryValue = parseFloat(payloadArray[i + 1]);
    telemetryPayload[telemetryKey] = telemetryValue;
}

// Result object with device attributes/telemetry data
var result = {
    deviceName: payloadArray[0],
    deviceType: payloadArray[1],
    telemetry: telemetryPayload,
    attributes: {}
  };

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

return result;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

Now copy & paste the following script to the Decoder function section:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload);

// Result object with device/asset attributes/telemetry data

var deviceName = data.deviceName;
var deviceType = data.deviceType;
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {},
   telemetry: {
       temperature: data.temperature,
       humidity: data.humidity
   }
};

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

return result;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

Now copy & paste the following script to the Decoder function section:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(payload);

// decode payload to JSON
// var data = decodeToJson(payload);

var deviceName = payloadStr.substring(0,6);
var deviceType = payloadStr.substring(6,13);

// Result object with device/asset attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {},
   telemetry: {
       temperature: parseFloat(payloadStr.substring(13,17)),
       humidity: parseFloat(payloadStr.substring(17,19))
   }
};

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

return result;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

Now copy & paste the following script to the Decoder function section:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload).reports[0].value;

// Result object with device telemetry data
var result = {
    deviceName: hexToString(data.substring(0, 12)),
    deviceType: hexToString(data.substring(12, 26)),
    telemetry: {
        temperature: parseFloat(hexToString(data.substring(26, 34))),
        humidity: parseFloat(hexToString(data.substring(34, 38))),
    }
};

/** Helper functions **/

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

// Hexadecimal string to string
function hexToString(hex) {
    var str = '';
    for (var i = 0; i < hex.length; i += 2) {
        var notNullValue = parseInt(hex.substr(i, 2), 16);
        if (notNullValue) {
            str += String.fromCharCode(notNullValue);
        }
    }
    return str;
}

function decodeToJson(payload) {
    // convert payload to string.
    var str = decodeToString(payload);

    // parse string to JSON
    var data = JSON.parse(str);
    return data;
}

return result;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

You can change the function Decoder while creating the converter or after creating it:

  • If the converter has already been created, click it to open the “Data converter details” window.
  • Click the “Edit” buton (the ‘pencil’ icon) to edit the data converter.
  • Copy the configuration example or create your own converter configuration and paste it into the “function Decoder” field.
  • To save the changes, click the “Save” button (the ‘checkmark’ icon).

Also create the Downlink Converter Template in the Converter Templates section:

  • On the Edge management > Converter templates section page, click the “Add data converter” button (the + icon) to create another Converter template, and select the “Create new converter” option.
  • In the “Add data converter” pop-up window:
    • Name: Enter the name of the data converter.
    • Type: Select the “Downlink” converter type from the drop-down menu.
    • To view the events, enable Debug mode.
    • function Decoder: Enter a script to parse and transform data.
    • Click the “Add” button.

You can customize a downlink according to your configuration. Let’s consider an example where we send an attribute update message. An example of a downlink converter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",

    // downlink data
    data: JSON.stringify(msg),

    // Optional metadata object presented in key/value format
    metadata: {
    }
};

return result;

Create Integration template

Now that the Uplink and Downlink converter templates have been created, it is possible to create the Integration:

  • Go to the Edge management > Integration templates section, click the “Add new integration” button (the + icon) and select the “Create new integration” option.
  • In the “Add integration” pop-up window and fill out the “Basic settings” block:
    • Integration type: Select the “UDP” integration type from the drop-down menu.
    • Name: Enter the name of the integration.
  • In the “Uplink data converter” block:
    • Select the “Select existing” tab.
    • Uplink data converter: Select the uplink data converter from the drop-down menu.
  • In the “Downlink data converter” block:
    • Select the “Select existing” tab.
    • Downlink data converter: Select the uplink data converter from the drop-down menu.
  • In the “Connection” block:
    • Enter the Port and Size of the buffer for inbound socket (in KB) in the corresponding fields. By default, the UDP Integration will use the port 11560, but can be changed to any available port.
    • Enter the Cache Size and Cache time to live in minutes in the corresponding fields.
    • Enable broadcast - integration will accept broadcast address packets: Flag to indicate that integration accepts UDP packets sent to broadcast address.
    • Integration key and Integration secret: Copy the values to use later in the configuration.
    • Handler Configuration: Select the device payload type from the drop-down menu.
Doc info icon

The Execute remotely option is selected by default and cannot be changed, the UDP Integration can only be the remote type.

Select the device payload type for Handler Configuration:

Please select Handler Type as TEXT.

image

To parse the payload properly, please make sure that next values are set:

  • Charset Name - incoming bytes will be converted to string using provided charset; Leave it by default for this demo - UTF-8;

Click “Add” to finish adding integration.

image

Please select Handler Type as JSON.

image

Click “Add” to finish adding integration.

image

Please select Handler Type as BINARY.

image

Click “Add” to finish adding integration.

image

Please select Handler Type as HEX.

image

Click “Add” to finish adding integration.

image

To save the Integration, click the Add button.

We can send a downlink message to the device from the Rule chain using the rule node. To send downlink via integration, modify the Edge Root Rule chain.

Doc info icon

Please note!
If you use earlier versions of Edge, you cannot create or edit a Rule Chain on the Edge itself. It must be configured as a template in the Cloud (Server), and then assigned to the Edge instance.

Starting with Edge version 4.0, you can create and edit a Rule Chain on the Edge.

For example, you can add an integration downlink node and set the ‘Attributes Updated’ link to it. When the device attribute changes, the downlink message is sent to the integration.

Assign Integration to Edge

Once the converter and integration templates are created, we can assign the integration template to Edge.

  • Go to the Edge management > Instances section and click the Manage edge integrations button.
  • On the Integration page, click the "Assign to edge" button. In the "Assign the Integration to the Edge" pop-up window, select the integration from the drop-down menu and click the "Assign" button.
  • Login to your ThingsBoard Edge instance and go to the Integrations center > Integrations section. Confirm the UDP integration on the Edge.

Installing and running external UDP Integration

Please refer to the Remote Integration guide and install the UDP Integration service locally or on a separate machine.

Please use the Integration key and Integration secret from the above section for the UDP Integration configuration.

Once the ThingsBoard UDP Integration has been created, the UDP server starts, and then it waits for data from the devices.

Select the device payload type to send the uplink message:

To view the created device with data in the Device groups > All section on the Edge:

The received data can be viewed in the Uplink converter. In the ‘In’ and ‘Out’ blocks of the “Events” tab:

Now let’s check the downlink functionality.

Now we need to send another message to the UDP integration to see the downlink response. Please use the same command as before, but replace the parameter q1 with q120. With these changes, the nc utility will wait 120 seconds for the downlink message. In addition, please remove the w1 parameter.

After you’ll send uplink command, you have 120 seconds to add firmware shared attribute:

To make sure that the downlink message sent to the integration, you can check the “Events” tab of integration:

An example of a sent message and a response from ThingsBoard Edge in the terminal:

Next steps