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

Plain CoAP (port 5683):

coap-client -v 6 -m POST -t "application/json" -e '{"temperature":25}' "coap://$THINGSBOARD_HOST: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 ca-root.pem from the Entities → Devices → [device] → Check connectivity → CoAP .

coap-client-openssl -v 6 -m POST -R ca-root.pem -t "application/json" -e '{"temperature":25}' "coaps://$THINGSBOARD_HOST/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://$THINGSBOARD_HOST/api/v1/telemetry"

To enable DTLS on the ThingsBoard server, set these environment variables:

COAP_DTLS_ENABLED=true
COAP_DTLS_CREDENTIALS_TYPE=PEM
COAP_DTLS_PEM_CERT=server.pem
COAP_DTLS_PEM_KEY=server_key.pem
COAP_DTLS_PEM_KEY_PASSWORD=secret

Additional DTLS settings:

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: