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

CoAP Integration

Doc info icon

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

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

To learn more, please review the integration diagram.

image

Prerequisites

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

To simulate CoAP device, please install coap-client. This utility 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 its 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 the 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

Only the ThingsBoard Professional Edition creates converters and integration templates. So please use ThingsBoard Cloud or install your own platform instance to log in as a Tenant administrator.

To add the MQTT integration, follow the steps below:

  • Go to the Edge management > Integration templates section and click the “plus” button to add a new integration. Select the type ‘MQTT’. Name it “Edge MQTT integration”. Then click “Next”.
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.

image

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

Now copy & paste the following script to the TBEL 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
/** 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;

image

If you want to use JavaScript to develop functions, please use the text payload script for JS.

Now copy & paste the following script to the TBEL 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
/** 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;

image

If you want to use JavaScript to develop functions, please use the JSON payload script for JS.

Now copy & paste the following script to the TBEL 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
/** 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;

image

If you want to use JavaScript to develop functions, please use the binary payload script for JS.

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.

image

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 > Instances section, click your edge instance to open the Edge details window, and navigate to the "Attributes" tab. Click the "plus" icon to add new server attribute to Edge.
  • Name it (i.g. "edgeIp") and use the Edge IP address and CoAP bind port in the following format: 'host:port'. Then, click the "Add" button.
  • View the added the server attribute "edgeIP" to the edge.
  • Now, click "Manage edge integrations" button of the Edge entity.
  • Click the "+" button in the top right of the corner. Specify your integration and click the "Assign" button to assign it to the Edge.
  • Login to your ThingsBoard Edge instance and go to the Integrations center > Integrations section. You should see your integration. To open the "Integration details" window, click on it.
  • In the "Integration details"" window, the ${{edgeIP}} placeholder will be replaced with the value of the attribute.

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:

Next steps