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

On this page

CoAP Integration

ThingsBoard PE Feature

Only Professional Edition supports Platform Integrations feature.
Use ThingsBoard Cloud or install your own platform instance.

Overview

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

Please review the integration diagram to learn more.

image

CoAP Integration Configuration

CoAP Integration allows us to choose a security mode:

  • NO SECURE(default mode)
  • DTLS
  • MIXED

image

In addition, CoAP integration will provide us automatically generated CoAP endpoint URL for data transmitting based on the Base URL path and next path prefixes:

  • /i - Integration resource in the CoAP server
  • /$INTEGRATION_ROUTING_KEY - autogenerated integration routing key

You can also update the CoAP endpoint URL by setting additional path prefixes in front of base URL:

image

Each of the additional path prefixes will be added to the CoAP server as CoAP resources, where:

  • api - parent resource
  • v2 - child resource of api resource and parent resource of integration resource i

Prerequisites

In this tutorial, we will show you how CoAP integration works as part of tb-core service with NO SECURE security mode selected. In order to do this we will use:

  • ThingsBoard Professional Edition instance — thingsboard.cloud;
  • 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://int.thingsboard.cloud URL.

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.

Before setting up an CoAP integration, you need to create an Uplink Converter that is a script for parsing and transforming the data received by CoAP integration to format that ThingsBoard uses.

To create an Uplink Converter go to Data Converters section and Click Add new data converter —> Create new converter. Name it “CoAP Uplink Converter” and select type Uplink. Use debug mode for now.

NOTE: Although the Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode may tremendously increase the disk space, used by the database, because all the debugging data is stored there. It is highly recommended to turn the Debug mode off when done debugging.

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.

CoAP Integration Setup

Go to Integrations 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.

please note down CoAP endpoint URL value - we will use it later in coap-client for testing CoAP Integration.

image

Click Add to save the Integration.

Once CoAP Integration has been created, the CoAP server register appropriate resources, and then it waits for data from the devices.

Choose device payload type to send uplink message

Once the command will send you can go to Device Groups -> All you should find an SN-001 device provisioned by the Integration. Click on the device, go to the Latest Telemetry tab to see the “temperature” key and its value (25.7) there and also the “humidity” key and its value (69) there as well.

image

Next steps