CoAP Integration

CoAP Integration streams data from CoAP-enabled devices into ThingsBoard Edge and converts device payloads into ThingsBoard telemetry.

This guide covers the NO SECURE security mode. To simulate a CoAP device, install the coap-client utility:

sudo apt update
sudo apt install libcoap2-bin

Verify the installation:

coap-client --version

The examples use a sensor SN-001 that publishes temperature and humidity to the CoAP integration at coap://10.7.3.0 (the Edge IP address on the local network). Replace this with the actual IP of your Edge instance.

The device supports three payload formats:

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

Integration and Converter templates are created in the Cloud (ThingsBoard PE server) and then assigned to Edge instances.

1. In the Cloud, go to Edge management > Integration templates and click +. Select CoAP as the integration type, enter a name, enable Debug mode, and click Next.

2. Create the Uplink converter. The decoder function parses the device payload into ThingsBoard telemetry. Select the tab matching your device’s payload format:

   • Text payload
   • JSON payload
   • Binary payload

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

3. On the Connection step, enter the IP address and CoAP binding port of your Edge instance as the Base URL in host:port format.

   To reuse this template across multiple Edge instances with different addresses, use the placeholder ${{edgeIp}} instead of a hardcoded value. The placeholder is replaced at assignment time by the edgeIp attribute value set on each Edge instance.

   Click Add to save the integration template.

Step 1: Go to Edge management > Integration templates and click + to add a new integration. Step 1: Select CoAP as the Integration type, enter the name, enable Debug mode, then click Next. Step 2: Select "Create new", enter a converter name, paste the script, and click Next. Step 2: Select "Create new", enter a converter name, paste the script, and click Next. Step 2: Select "Create new", enter a converter name, paste the script, and click Next. Step 3: Enter the Edge IP:port or the ${{edgeIp}} placeholder as the Base URL. Click Add.

Since the ${{edgeIp}} placeholder is used in the integration configuration, add the edgeIp server attribute to the Edge instance before assigning the integration. Set its value to the Edge IP address and CoAP binding port (e.g. 10.7.3.0:15683).

1. Go to Edge management > Instances, click the Edge instance to open its details, and select the Attributes tab. Click + to add a new server attribute.

2. Enter edgeIp as the attribute name and the Edge IP address with CoAP port as the value (e.g. 10.7.3.0:15683). Click Add.

3. Confirm the edgeIp server attribute is listed on the Edge.

Step 1: Open the Edge instance, go to the Attributes tab, and click + to add a server attribute. Step 2: Enter "edgeIp" as the name and your Edge IP:CoAP-port as the value. Step 3: The edgeIp attribute is now set on the Edge.

1. Click the Manage edge integrations button on the Edge instance.

2. Click +, select the CoAP integration from the list, and click Assign.

3. Log in to your ThingsBoard Edge instance. Go to Integration center > Integrations and click the CoAP integration to open its details.

4. In the integration details, the ${{edgeIp}} placeholder is replaced with the Edge attribute value.

Step 1: Click the "Manage edge integrations" button on the Edge instance. Step 2: Click +, select the CoAP integration, and click Assign. Step 3: The CoAP integration is now available on the Edge. Step 4: The ${{edgeIp}} placeholder is replaced with the actual IP:port value.

Once the CoAP integration is assigned, the Edge CoAP server registers its resources and waits for device data.

On the Edge, go to Integration center > Integrations, click the CoAP integration, and copy the CoAP endpoint URL. Use it in the commands below.

• Text payload
• JSON payload
• Binary payload

1. Send the uplink message. Replace $YOUR_COAP_ENDPOINT_URL with the copied endpoint URL:

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

2. On the Edge, go to Integration center > Integrations, open the CoAP integration, and select the Events tab. The uplink message should appear with status OK.

3. A new device is created automatically. Go to Entities > Devices, open SN-001, and select the Latest telemetry tab to see the received data.

4. To see how the converter processed the message, go to Integration center > Data converters, open the Uplink converter, and select the Events tab.

Step 1: Terminal output after sending the text payload. Step 2: The uplink message appears in the Events tab with status OK. Step 3: The device is created automatically and telemetry is visible. Step 4: Open the Uplink converter and go to the Events tab. Step 4: Click the three dots in the In column to see the raw incoming payload. Step 4: Click the three dots in the Out column to see the processed output.