CoAP Integration

• Prerequisites
• Create converter and integration templates
• Assign Integration to Edge
• Send uplink message
• Next steps

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

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.

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://10.7.3.0 URL - 10.7.3.0 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:

  1
  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, the payload looks like this (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\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 and integration templates

Converter and integration templates are created only on the ThingsBoard Professional Edition. So please use ThingsBoard Cloud or install your own platform instance to log in as Tenant administrator.

Follow the steps below to add the MQTT integration:

• Go to “Edge management” section -> “Integration templates” page and click “plus” button to add new integration. Select type ‘MQTT’. Name it “Edge MQTT integration”. Then, click “Next”.

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.

• The next step is to create an Uplink data converter.

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.

For this example, use the code below.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

Choose device payload type to for decoder configuration:

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

// decode payload to string
var strArray = decodeToString(payload);
var payloadArray = strArray.replaceAll("\"", "").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 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/** 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 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

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
/** 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 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

After adding the uplink converter, click “Next”.

• Finally, we go to the “Connection” step:

  • Enter IP address of your Edge instance (host) and CoAP binding port in format: ‘host:port’ as ‘Base URL’. Or, you can use placeholder ${{ATTRIBUTE_KEY}} to substitute integration field with attribute value from specific Edge entity. In this example, we will use the placeholder ${{edgeIp}} for ‘Base URL’;
  • Click “Add” button to create the 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 and the CoAP binding port as edgeIP attribute. In my case, it is: ‘10.7.3.0:15683’. Once attribute added, we are ready to assign integration and verify that it’s added.

• Go to the "Edge management" section -> "Instances" page, click on your edge instance to open "Edge details" window, and navigate to the "Attributes" tab. Click "plus" icon to add new server attribute to Edge;
• Name it 'edgeIp' and use Edge IP address and CoAP bind port in following format: 'host:port'. After, click "Add" button;
• Added the server attribute ''edgeIP'' to the edge;
• Now, click "Manage edge integrations" icon of Edge entity;
• Click the "+" icon at the top right of the corner. Specify your integration and click "Assign" button to assign it to the Edge;
• Login to your ThingsBoard Edge instance and open "Integrations center" section -> "Integrations" page. You should see your integration. Click on it;
• In the "Integration details" window placeholder ${{edgeIP}} will be replaced with the value of the attribute.

Send uplink message

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:

Text payload

JSON payload

Binary payload

Use the command below to send a message. Don’t forget to replace $YOUR_COAP_ENDPOINT_URL with corresponding value. 1 echo -e 'SN-001,default,temperature,25.7,humidity,69' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t text/plain -f- Now, go to the “Integrations center” -> “Integrations” and navigate to the “Events” tab in your MQTT integration on the ThingsBoard Edge. If you have done everything correctly, you will find an uplink message with the status ‘OK’. When you sent the message, a new device was created. The created device with data can be seen in the “Entities” section -> “Devices” page: Also, received data can be viewed in the uplink converter. In the ‘In’ and ‘Out’ blocks of the “Events” tab:

Use the command below to send a message. Don’t forget to replace $YOUR_COAP_ENDPOINT_URL with corresponding value. 1 echo -e -n '{"deviceName": "SN-001", "deviceType": "default", "temperature": 25.7, "humidity": 69}' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t application/json -f- Now, go to the “Integrations center” -> “Integrations” and navigate to the “Events” tab in your MQTT integration on the ThingsBoard Edge. If you have done everything correctly, you will find an uplink message with the status ‘OK’. When you sent the message, a new device was created. The created device with data can be seen in the “Entities” section -> “Devices” page: Also, received data can be viewed in the uplink converter. In the ‘In’ and ‘Out’ blocks of the “Events” tab:

Use the command below to send a message. Don’t forget to replace $YOUR_COAP_ENDPOINT_URL with corresponding value. 1 echo -e -n '\x53\x4e\x2d\x30\x30\x31\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t application/octet-stream -f- Now, go to the “Integrations center” -> “Integrations” and navigate to the “Events” tab in your MQTT integration on the ThingsBoard Edge. If you have done everything correctly, you will find an uplink message with the status ‘OK’. When you sent the message, a new device was created. The created device with data can be seen in the “Entities” section -> “Devices” page: Also, received data can be viewed in the uplink converter. In the ‘In’ and ‘Out’ blocks of the “Events” tab:

Next steps

• Getting started guide - Provide quick overview of main ThingsBoard Edge features. Designed to be completed in 15-30 minutes:

• Installation guides - Learn how to setup ThingsBoard Edge on various available operating systems and connect to ThingsBoard Server.

• Edge Rule Engine:

  • Rule Chain Templates - Learn how to use ThingsBoard Edge Rule Chain Templates.

  • Provision Rule Chains from cloud to edge - Learn how to provision edge rule chains from cloud to edge.

• Security:
  • gRPC over SSL/TLS - Learn how to configure gRPC over SSL/TLS for communication between edge and cloud.

• Features:

  • Edge Status - Learn about Edge Status page on ThingsBoard Edge.

  • Cloud Events - Learn about Cloud Events page on ThingsBoard Edge.

• Use cases:

  • Manage alarms and RPC requests on edge devices - This guide will show how to generate local alarms on the edge and send RPC requests to devices connected to edge:

  • Data filtering and traffic reduce - This guide will show how to send to cloud from edge only filterd amount of device data:

• Roadmap - ThingsBoard Edge roadmap.