Getting Connected

CoAP is a lightweight, UDP-based protocol designed for constrained IoT devices. ThingsBoard acts as a CoAP server supporting both regular request-response and the CoAP Observe option for push-style subscriptions.

Examples in this section use coap-client (from the libcoap package), which supports query parameters and DTLS. Install it on Ubuntu:

sudo apt install libcoap3-bin

On older Ubuntu releases where libcoap3-bin isn’t available, install libcoap2-bin instead:

sudo apt install libcoap2-bin

For DTLS examples, coap-client-openssl is required — a build of coap-client with OpenSSL support. See the Californium cf-client or build from source.

CoAP supports two credential types. Configure them per device under Manage credentials — see Devices.

Include the device access token as a path segment in the URL. Copy it from Entities ⇾ Devices ⇾ [device] ⇾ Copy Access Token, and replace $ACCESS_TOKEN in the commands below with it.

Plain CoAP (port 5683):

coap-client -v 6 -m POST -t "application/json" -e '{"temperature":25}' "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/telemetry"

CoAP over DTLS — One-way TLS (port 5684):

The client verifies the server certificate using a CA root certificate.

Download tb-cloud-root-ca.pem from the Entities ⇾ Devices ⇾ [device] ⇾ Check connectivity ⇾ CoAP.

coap-client-openssl -v 6 -m POST -R tb-cloud-root-ca.pem -t "application/json" -e '{"temperature":25}' "coaps://coap.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry"

Mutual DTLS authentication — both client and server verify each other’s certificates. No token is included in the URL.

1. Generate a self-signed EC private key and certificate:

   openssl ecparam -out key.pem -name secp256r1 -genkey
   openssl req -new -key key.pem -x509 -nodes -days 365 -out cert.pem

2. Go to Entities ⇾ Devices ⇾ [device] ⇾ Manage credentials, select X.509 Certificate, and paste the contents of cert.pem.

3. Connect using the certificate and key:

   coap-client-openssl -v 6 -c cert.pem -j key.pem -m POST -t "application/json" -e '{"temperature":25}' "coaps://coap.thingsboard.cloud/api/v1/telemetry"

ThingsBoard Cloud already has DTLS configured. Connect on port 5684 using coaps:// — no additional server-side setup is needed.

A connecting CoAPS client must support:

• DTLS 1.2 (DTLS 1.3 is not supported)
• An ECDHE key exchange with certificate-based authentication — PSK and Raw Public Key are not supported by the CoAP transport
• One of the AEAD cipher suites below, matching the server certificate key type
• A supported curve and a SHA-256 signature algorithm

Server certificate with an EC key:

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
• TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8
• TLS_ECDHE_ECDSA_WITH_AES_128_CCM
• TLS_ECDHE_ECDSA_WITH_AES_256_CCM

Server certificate with an RSA key:

• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Supported curves: secp256r1, secp384r1, X25519, X448

Signature algorithms: SHA256withECDSA, SHA256withRSA

When you set the transport type to CoAP in a device profile, additional settings become available under Transport configuration. These settings apply to all devices using the profile.

When using the Default device type, choose the serialization format for CoAP messages:

NB-IoT devices typically operate in low-power modes where they are not always reachable. The power saving mode setting tells ThingsBoard how long the device is available after it wakes up, so the platform can queue and deliver commands (RPC, shared attribute updates) within the reachability window.

PSM parameters:

eDRX parameters: