CoAP Integration

CoAP Integration opens a CoAP server on the Edge. CoAP devices post their data to it, and the uplink converter turns the payload into ThingsBoard telemetry.

Prerequisites

A ThingsBoard server with tenant administrator access. The templates are created there.
A ThingsBoard Edge instance connected to the server.
The coap-client utility from libcoap 3 to simulate a device. On Ubuntu 22.04 and later, the package installs it as coap-client-notls:
Terminal window
```
sudo apt update
sudo apt install libcoap3-bin
sudo ln -s /usr/bin/coap-client-notls /usr/local/bin/coap-client
```

This guide uses the NO SECURE security mode. The example sensor SN-001 posts temperature and humidity to the Edge at 10.7.3.0, port 15683. Replace this with the IP address of your Edge and its CoAP port (COAP_BIND_PORT: 5683 by default, 15683 if you moved the Edge ports because Edge runs on the same machine as the server).

The device can send its data in one of three payload formats. Pick the one that matches your device:

SN-001,default,temperature,25.7,humidity,69

{
  "deviceName": "SN-001",
  "deviceType": "default",
  "temperature": 25.7,
  "humidity": 69
}

\x53\x4e\x2d\x30\x30\x31\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39

Bytes	Hex	Value
0-5	`\x53\x4e\x2d\x30\x30\x31`	Device name `SN-001`
6-12	`\x64\x65\x66\x61\x75\x6c\x74`	Device type `default`
13-16	`\x32\x35\x2e\x37`	Temperature `25.7`
17-18	`\x36\x39`	Humidity `69`

Create converter template

The CoAP integration has no downlink, so only an uplink converter is needed. It is created on the server.

On the server, go to Edge management > Templates and open the Converter tab. Click Add data converter and select Create new converter.
Set Converter type to Uplink, select CoAP as the Integration type, and enter the name CoAP uplink converter.

In Main decoding configuration, select TBEL, paste the script for your payload format, and click Add.

/** 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;

/** Decoder **/

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

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;

/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(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;

Create integration template

On the server, go to Edge management > Templates, open the Integration tab, and click Add integration.
On the Basic settings step, select CoAP as the Integration type. Keep the name CoAP integration or enter your own. Click Next.
On the Uplink data converter step, select Select existing, choose CoAP uplink converter, and click Next. The CoAP wizard has no downlink step.
On the Connection step, keep Security mode at NO SECURE and set Base URL to coap://${{edgeIp}}. Click Add.

Base URL points to the CoAP transport of the Edge (COAP_BIND_PORT): the integration does not open its own port, it adds its resource to the Edge CoAP server. Use the coap:// scheme, for example coap://10.7.3.0:15683. The integration endpoint is <Base URL>/i/<integration key>. The ${{edgeIp}} placeholder lets you assign one template to several Edges: each Edge replaces it with the value of its own edgeIp server attribute. See Configuration placeholders.

Assign the integration to the Edge

Add the edgeIp attribute first. Without it, the assignment dialog warns Edge has missing attribute(s) and the Edge receives the literal placeholder.

On the server, go to Edge management > Edges and click the Edge. On the Attributes tab, with the Server attributes scope selected, click +. Enter edgeIp as the key and the Edge IP address with the CoAP port, for example 10.7.3.0:15683, as the value. Click Add.
On the Details tab, click Manage integrations, then Assign to edge (+). Select CoAP integration and click Assign.
Log in to the Edge and go to Integrations > Integrations. Open the integration. Base URL shows coap://10.7.3.0:15683 instead of the placeholder, and CoAP endpoint URL shows the full endpoint.

Once the integration is assigned, it registers its endpoint on the CoAP server of the Edge and waits for device data.

Send an uplink message

On the Edge, go to Integrations > Integrations, open the CoAP integration, and copy the CoAP endpoint URL.

Send a test message for your payload format. Replace $YOUR_COAP_ENDPOINT_URL with the copied URL:

echo -e 'SN-001,default,temperature,25.7,humidity,69' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t text/plain -f-

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-

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-

Open the Events tab of the integration. An Uplink event with status OK appears.
The device SN-001 is created automatically. On the Edge, go to Devices & assets > Devices, open it, and select the Latest telemetry tab. The temperature and humidity keys show the received values.
To see how the converter processed the message, go to Integrations > Data converters, open CoAP uplink converter, and select the Events tab. The In column shows the raw payload, the Out column the decoded result.

Was this helpful?