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. Use it to bring telemetry from CoAP devices into ThingsBoard for monitoring and rule-based automation.

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.

A device sends a CoAP message (POST or PUT) to the ThingsBoard CoAP endpoint. The uplink converter decodes the payload into telemetry and attributes, and the ThingsBoard Core Service stores the data, creating the device automatically on first contact when Allow create devices or assets is enabled. CoAP Integration does not currently support downlink.

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

To set up the CoAP integration, first create an uplink data converter to process incoming messages, then create and configure the integration.

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 ⇾ 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 = {

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

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

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

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

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

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

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set integration type to CoAP.
   • Enter a Name for the integration, or keep the default CoAP integration.
   • Leave Enable integration and Allow create devices or assets on so the device is created automatically on first data.
   • 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.

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 ⇾ 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 ⇾ Data converters, click CoAP Uplink Converter, and open its Events tab:

• In — what the integration received (payload body)
• Out — what the converter returned
• Metadata — CoAP option fields captured from the request (e.g. Option:content-format, Option:uri) and the integration name
• Error — error text, if any

Go to Devices & assets ⇾ 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 ⇾ 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