CoAP Integration

CoAP Integration lets devices that use the Constrained Application Protocol (CoAP) send data to ThingsBoard through a dedicated CoAP endpoint. CoAP is a lightweight UDP-based request/response protocol for low-power, low-bandwidth hardware. An uplink data converter transforms each incoming request into device or asset data, including telemetry and attributes. The integration is uplink-only: it does not send downlink messages to devices.

Use CoAP Integration when:

• Devices use CoAP (RFC 7252): constrained MCUs, NB-IoT modules, or similar hardware.
• Firmware lacks the memory or power budget for HTTP or MQTT.
• The network is lossy or UDP-only.
• The device firmware sends a payload format you cannot change.

1. Receive data. A device sends a CoAP POST or PUT request to the integration endpoint — port 5683 for plain CoAP, 5684 for DTLS. Confirmable (CON) and non-confirmable (NON) requests are both accepted.
2. Decode the payload. The uplink converter identifies the device or asset and extracts attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard can create an entity that does not exist yet.
4. Respond. ThingsBoard answers 2.01 Created on success or 4.00 Bad Request if processing fails. The response carries no data: CoAP Integration does not support downlink.

• Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• Devices that can reach the ThingsBoard CoAP port over UDP.
• A sample of the payload your device sends.
• A CoAP client for testing, for example coap-client from libcoap. On Debian and Ubuntu, the libcoap3-bin package installs it as coap-client-notls (plain CoAP) and coap-client-gnutls or coap-client-openssl (with DTLS support).

Create the uplink converter, assign it to a new CoAP integration, and send a test request.

The uplink converter receives the CoAP request body as a byte array, resolves the target device, and returns its telemetry and attributes. CoAP Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select CoAP.

4. Name — enter a name, for example CoAP Uplink Converter.

5. Main decoding configuration — the editor is pre-filled with the default decoder template for JSON payloads. For JSON, you can keep it. For text or binary payloads, replace it with the template for your payload type below: the default template rejects them with Payload is not a JSON object. Use it as a starting point and, if needed, adapt the field names to your device. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • Text payload
   • JSON payload
   • Binary payload
   • TBEL (Recommended)
   • JavaScript

   /** Decoder **/
   
   // decode payload to string
   var strArray = decodeToString(payload);
   var payloadArray = strArray.replaceAll("\"", "").split(',');
   
   // Result object with device attributes/telemetry data
   var result = {
       deviceName: payloadArray[0],
       deviceType: payloadArray[1],
       attributes: {
           serialNumber: payloadArray[2]
       },
       telemetry: {
           temperature: parseFloat(payloadArray[3])
   

   ▼Expand

   The payload is a comma-separated string with a fixed field order: deviceName,deviceType,serialNumber,temperature.

   To adapt:

   • Another delimiter — replace split(','), for example with split(';').
   • Another field order — change the payloadArray indexes.
   • More values — add them to telemetry, for example batteryLevel: parseFloat(payloadArray[4]).
   • Attributes or telemetry — move a field between the attributes and telemetry maps.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Sample Payloads

This guide uses device Thermostat-01, which reports its serial number and temperature in one of three formats:

Thermostat-01,thermostat,SN-12345,25.5

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "serialNumber": "SN-12345",
  "temperature": 25.5
}

\x54\x68\x65\x72\x6d\x6f\x73\x74\x61\x74\x2d\x30\x31\x74\x68\x65\x72\x6d\x6f\x73\x74\x61\x74\x53\x4e\x2d\x31\x32\x33\x34\x35\x32\x35\x2e\x35

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

CoAP options added to metadata when present in the request:

The Content-Format also sets how debug events display the payload: JSON (codes 50, 110, 11543), text (0, 41, 46, 11542), or binary (any other code, or none).

Built-in helpers:

For field renaming, nested values, and other patterns, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. The dialog opens with pre-filled Metadata rows, Payload content type set to JSON, and a sample payload. To test the JSON template, replace the sample payload with:

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "serialNumber": "SN-12345",
  "temperature": 25.5
}

Click Test. The Output panel shows:

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "attributes": {
    "serialNumber": "SN-12345"
  },
  "telemetry": {
    "temperature": 25.5
  }
}

Check that deviceName is set, attributes holds serialNumber, and telemetry holds temperature. The output above comes from the JSON example. The default template also adds the time: "telemetry": {"ts": <current time>, "values": {"temperature": 25.5}}. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select CoAP.
   • Name — keep the default CoAP integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose CoAP Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Connection:
   • Keep Security mode set to NO SECURE. To encrypt traffic, see Enable DTLS.
   • Copy the CoAP endpoint URL. You need it to send uplinks.
   • Leave the other parameters at their defaults. See Connection Settings for details.
5. Click Add.

Send a request to the endpoint, then confirm that ThingsBoard decoded it and created the device.

Send the test message with coap-client (part of libcoap) or any CoAP client that supports POST requests.

Replace $YOUR_COAP_ENDPOINT_URL with the CoAP endpoint URL and run the command for your payload type:

echo -n 'Thermostat-01,thermostat,SN-12345,25.5' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t text/plain -f-

echo -e -n '{"deviceName": "Thermostat-01", "deviceType": "thermostat", "serialNumber": "SN-12345", "temperature": 25.5}' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t application/json -f-

echo -e -n '\x54\x68\x65\x72\x6d\x6f\x73\x74\x61\x74\x2d\x30\x31\x74\x68\x65\x72\x6d\x6f\x73\x74\x61\x74\x53\x4e\x2d\x31\x32\x33\x34\x35\x32\x35\x2e\x35' | coap-client -m post $YOUR_COAP_ENDPOINT_URL -t application/octet-stream -f-

No output means success: the endpoint answered 2.01 Created with an empty body.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK.
• Converter events — open CoAP Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the received payload, Out shows the decoded result, and Metadata shows the CoAP options (Option:content-format, Option:uri) and the integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created Thermostat-01. Open it and confirm temperature = 25.5 on the Latest telemetry tab and serialNumber = SN-12345 on the Attributes tab (Client attributes).

DTLS encrypts CoAP traffic. To use the DTLS or MIXED security mode, the ThingsBoard CoAP server must have DTLS enabled. Otherwise, the integration fails to save with CoAP server doesn't have DTLS Endpoint enabled!.

Enable DTLS in thingsboard.yml or set these environment variables, then restart ThingsBoard:

# Enable/disable DTLS 1.2 support
export COAP_DTLS_ENABLED=true
# Default CoAP DTLS bind port
export COAP_DTLS_BIND_PORT=5684
# Server credentials type: KEYSTORE (Java key store) or PEM (the default)
export COAP_DTLS_CREDENTIALS_TYPE=KEYSTORE
# Path to the key store that holds the SSL certificate
export COAP_DTLS_KEY_STORE=coapserver.jks
# Password used to access the key store
export COAP_DTLS_KEY_STORE_PASSWORD=server_ks_password
# Password used to access the key
export COAP_DTLS_KEY_PASSWORD=server_key_password
# Key alias
export COAP_DTLS_KEY_ALIAS=serveralias
# Skip certificate validity check for client certificates
export TB_COAP_X509_DTLS_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT=false

Then open the integration, click Toggle edit mode (pencil icon), set Security mode to DTLS or MIXED, check the DTLS Base URL, and click Apply changes. Devices send to the coaps:// endpoint on port 5684. In DTLS mode, plain CoAP requests to port 5683 are rejected with 4.00 Bad Request. In MIXED mode, the plain endpoint stays active on port 5683.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• CoAP API — connect devices directly to ThingsBoard over CoAP, without an integration.
• TBEL — built-in functions and syntax for converter scripts.
• Rule Engine — how messages are processed after decoding.