PE Edge
ThingsBoard PE Edge Documentation
Cloud Professional Edition Community Edition Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Try it now Pricing
Documentation > Integrations > CoAP
Getting Started
Installation Architecture API FAQ

On this page

CoAP Integration

Edge CoAP Integration is implemented in a similar way, as PE CoAP Integration. The only difference is in the way, how integration is created and provisioned. Please make sure that you have knowledge of PE CoAP Integration before proceed.

Overview

CoAP Integration allows to stream data from devices that use a CoAP protocol to connect to ThingsBoard Edge and converts payloads of these devices into the ThingsBoard Edge format.

Please review the integration diagram to learn more.

image

Prerequisites

In this tutorial, we will show you how configure CoAP integration with NO SECURE security mode selected.

To simulate CoAP device, please install coap-client - utility which is intended to simulate CoAP client that will connect to CoAP integration.

Let’s assume that we have a sensor which is sending current temperature and humidity readings. Our sensor device SN-001 publishes it’s temperature and humidity readings to CoAP Integration on coap://192.168.1.15 URL - 192.168.1.15 is the IP address of the ThingsBoard Edge in local network. In your specific case please use IP address of your edge instance.

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

  • Text - in this case payload is: SN-001,default,temperature,25.7,humidity,69
  • JSON - in this case payload is:
1
2
3
4
5
6
{
  "deviceName": "SN-001",
  "deviceType": "default",
  "temperature": 25.7,
  "humidity": 69
}
  • Binary - in this case payload is: \x53\x4e\x2d\x30\x30\x31\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39 (in HEX string). Here is the description of the bytes in this payload:
    • 0-5 bytes - \x53\x4e\x2d\x30\x30\x31 - device name. If we convert it to text - SN-001;
    • 6-12 bytes - \x64\x65\x66\x61\x75\x6c\x74 - device type. If we convert it to text - default;
    • 13-16 bytes - \x32\x35\x2e\x37 - temperature telemetry. If we convert it to text - 25.7;
    • 17-18 bytes - \x36\x39 - humidity telemetry. If we convert it to text - 69;

You can use payload type based on your device capabilities and business cases.

Create Converter templates

Converter and Integration templates are created on the Cloud, so please log in as Tenant administrator to cloud instance.

Before creating the Integration template, you need to create an Uplink converter templates in Converters templates page. Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard Edge. Click on the ‘plus’ and on ‘Create new converter’. To view the events, enable Debug. In the function decoder field, specify a script to parse and transform data.

While Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode can significantly increase the disk space used by the database since all the debug data is stored there. It is highly recommended turning the Debug mode off after debugging is complete.

Choose device payload type to for 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.

You can change the decoder function while creating the converter or after creating it. If the converter has already been created, then click on the ‘pencil’ icon to edit it. Copy the configuration example for the converter (or your own configuration) and insert it into the decoder function. Save changes by clicking on the ‘checkmark’ icon.

Create Integration template

Now that the Uplink converter template has been created, it is possible to create an integration.

  • Go to Integration templates section and click Add new integration button.
  • Name it CoAP Integration, select type CoAP, turn the Debug mode on and from drop-down menus add recently created Uplink converter. Set Base URL as ${{edgeIP}}. Please note down CoAP endpoint URL value - we will use it later in coap-client for testing CoAP Integration.

Assign Integration to Edge

Once converter and integration templates are created, we can assign Integration template to Edge. Because we are using placeholder ${{edgeIP}} in the integration configuration, we need to add attribute edgeIP to edge first. You need to provide IP address of your Edge instance as edgeIP attribute. Once attribute added, we are ready to assign integration and verify that it’s added.

  • Add edgeIP attribute to Edge and set value as your Edge IP 192.168.1.15. Please use YOUR IP address of your Edge instance!
  • Click Manage Integrations button of Edge entity
  • Assign Integration to the Edge
  • Login to your ThingsBoard PE Edge instance and open Integrations page - placeholder is going to be replaced by attribute value

Once CoAP Integration has been created, the CoAP server register appropriate resources, and then it waits for data from the devices. Let’s log in to ThingsBoard Edge and go to the Integrations page. Find your CoAP integration and click on it. There you can find the CoAP endpoint URL. Click on the icon to copy the url.

Choose device payload type to send uplink message (Replace $YOUR_COAP_ENDPOINT_URL with corresponding value):

The created device with data can be seen in the section Device groups -> All on the Edge:

Received data can be viewed in the Uplink converter. In the ‘In’ and ‘Out’ blocks of the Events tab:

Next steps