CoAP Integration

CoAP Integration connects ThingsBoard to constrained IoT devices that use the Constrained Application Protocol (CoAP) — a lightweight request/response protocol designed for low-power, low-bandwidth environments such as sensors, actuators, and embedded systems. ThingsBoard creates a dedicated CoAP endpoint for the integration. The platform:

• exposes a CoAP resource endpoint that devices can POST or PUT messages to,
• passes each received message through the Uplink Converter (JavaScript or TBEL),
• decodes the payload and maps it to ThingsBoard telemetry and attributes,
• auto-creates devices on the first uplink (when Allow create devices or assets is enabled).

When to use CoAP Integration:

• Devices use CoAP (RFC 7252) — typically constrained MCUs, NB-IoT modules, or LwM2M-adjacent hardware.
• Firmware cannot support HTTP or MQTT due to memory or power constraints.
• The network is UDP-based or lossy and CoAP’s lightweight overhead is required.
• You need to bridge an existing CoAP server with ThingsBoard without re-flashing devices.

Before creating the integration, ensure:

• You have access to ThingsBoard PE or ThingsBoard Cloud with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• You know the payload format your CoAP devices send.

In this tutorial, device SN-001 sends temperature and humidity readings to the CoAP Integration at coap://$YOUR_TB_HOST.

The integration accepts three payload types:

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

The decoder function receives the raw CoAP message body as a payload byte array. It must return an object with at least deviceName and deviceType. Optionally, it can include telemetry (time-series measurements) and attributes (device properties) as flat key-value maps.

In addition to any integration-level metadata, the metadata object passed to the decoder contains CoAP option fields extracted from the request:

For the full decoder function reference — all input parameters and output fields — see Uplink data converter.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.

In the Add data converter dialog:

3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter CoAP and select CoAP from the list.
5. Name — enter a converter name, for example CoAP Uplink Converter.
6. Main decoding configuration — paste the decoder function from the appropriate tab below, then continue with step 7.

Select the tab matching your payload type:

/** 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 string
var strArray = decodeToString(payload);
var payloadArray = strArray.replace(/\"/g, "").replace(/\s/g, "").replace(/\\n/g, "").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 **/

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

return result;

/** Decoder **/

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

// Result object with device attributes/telemetry data
var result = {
    deviceName: data.deviceName,
    deviceType: data.deviceType,
    attributes: {},
    telemetry: {
        temperature: data.temperature,
        humidity: data.humidity
    }
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

/** Decoder **/

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

// Result object with device attributes/telemetry data
var result = {
    deviceName: data.deviceName,
    deviceType: data.deviceType,
    attributes: {},
    telemetry: {
        temperature: data.temperature,
        humidity: data.humidity
    }
};

/** Helper functions **/

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

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

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

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

return result;

7. Optionally, click Test payload decoder to validate.
8. Click Add.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Select CoAP as the integration type.
   • Enable integration and Allow create devices or assets are enabled by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the CoAP Uplink Converter created in the previous step, or click Create new to define the decoder inline.
   • Click Next.
4. Connection:
   • Select a Security mode — defaults to NO SECURE.
   • The Base URL is pre-filled with your ThingsBoard host (e.g. coap://my.thingsboard). Optionally, enter a Path to append to the base URL.
   • Copy the auto-generated CoAP endpoint URL — you will use it to send uplink messages.
   Read more about each parameter in Connection Settings.
5. Click Add.

Set Integration type to CoAP, enter a name, and click Next Select existing, choose CoAP Uplink Converter, and click Next Security mode defaults to NO SECURE — copy the CoAP endpoint URL and click Add

Security Mode

Defines the transport security for the CoAP connection:

Both CON (Confirmable) and NON (Non-Confirmable) CoAP message types are supported in all modes. ThingsBoard acknowledges CON messages automatically.

For DTLS and MIXED modes, enable DTLS support in thingsboard.yml or set the following environment variables:

# Enable/disable DTLS 1.2 support
export COAP_DTLS_ENABLED=true
# Default CoAP DTLS bind port
export COAP_DTLS_BIND_PORT=5684
# 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

Base URL / DTLS Base URL

The base address of the ThingsBoard CoAP endpoint. Pre-filled with your deployment host.

Path

Optional. A URL path segment appended to the Base URL after the / separator. Leave empty to use the default routing. Each Base URL field has its own Path field.

Example: coap://my.thingsboard/my-path

CoAP Endpoint URL

Read-only, auto-generated from the Base URL, the optional Path, and the fixed routing segment /i/$INTEGRATION_ROUTING_KEY. The routing key (UUID) is assigned at creation time. Devices must POST or PUT to this URL. Click the copy icon next to the field to copy it to the clipboard.

Execute Remotely

When expanded, shows an Integration key and Integration secret — credentials that allow the integration to run as a separate process outside the ThingsBoard cluster (e.g., on a remote server or on-premises gateway). See Remote Integration for setup details.

Advanced settings

After the integration is created, send a test uplink and confirm that ThingsBoard received the message, decoded it correctly, and provisioned the device.

Once the integration is created, the CoAP server registers the endpoint and waits for incoming data. Send a test message using coap-client (part of libcoap) or any CoAP client that supports POST, replacing $YOUR_COAP_ENDPOINT_URL with the URL copied during setup:

• Text payload
• JSON payload
• Binary payload

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

Go to Integrations center ⇾ Integrations, open CoAP integration, and click the Events tab. Each successfully processed uplink appears as a row with status OK.

To inspect converter processing, go to Integrations center ⇾ Data converters, click CoAP Uplink Converter, and open its Events tab:

• In — what the integration received (payload body)
• Out — what the converter returned
• Error — error text, if any

Go to Entities ⇾ Devices. Device SN-001 is auto-created on the first uplink. Open the Latest Telemetry tab to confirm temperature = 25.7 and humidity = 69.

How to read Debug Events

1. Go to Integrations center ⇾ Integrations, open your integration, and click the Events tab. Filter by Uplink.
2. Click on an event to inspect:

• In — what the integration received: the raw CoAP payload body
• Out — what the converter returned: decoded device name, attributes, and telemetry
• Error — error text, if any

• Integrations Overview — how ThingsBoard connects to external platforms and how uplink/downlink flow works
• Uplink Data Converter — full decoder function reference: input parameters, output fields, and scripting patterns
• Remote Integration — run the integration outside the ThingsBoard server to reach CoAP endpoints in a private network
• TBEL scripting reference — built-in functions and operators for writing converter scripts
• Rule Engine — how uplink messages are processed after the converter