Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
API > Device Connectivity APIs > CoAP Device API
Getting Started Documentation Installation Architecture
FAQ
On this page

CoAP Device API Reference

Getting started

CoAP basics

CoAP is a light-weight IoT protocol for constrained devices. You can find more information about CoAP here. CoAP protocol is UDP based, but similar to HTTP it uses request-response model. CoAP Observe Option allows subscription to resources and receiving notifications on resource change.

ThingsBoard server nodes act as a CoAP Server that supports both regular and observe requests.

Client libraries setup

You can find CoAP client libraries for different programming languages on the web. The examples in this article will be based on CoAP cli. In order to setup this tool on Linux or macOS, you can use the following command:

1

npm install coap-cli -g
Doc info icon

NOTE:
CoAP cli does not support query parameters. If you require to use query parameters, you should use coap client instead. To install the coap-client please execute:

  • Ubuntu 20.04: sudo apt install libcoap2-bin
  • Ubuntu 18.04: sudo apt install libcoap1-bin

CoAP Authentication and error codes

In this article, we will use access token device credentials and they will be referred to later as $ACCESS_TOKEN. The application needs to include $ACCESS_TOKEN as a path parameter into each CoAP request. Possible error codes and their reasons:

  • 4.00 Bad Request - Invalid URL, request parameters or body.
  • 4.01 Unauthorized - Invalid $ACCESS_TOKEN.
  • 4.04 Not Found - Resource not found.

The alternative authentication option is to use X.509 Certificates.

Key-value format

By default, ThingsBoard supports key-value content in JSON. Key is always a string, while value can be either string, boolean, double, long or JSON. For example:

1
2
3
4
5
6
7
8
9
10
11

{
 "stringKey":"value1", 
 "booleanKey":true, 
 "doubleKey":42.0, 
 "longKey":73, 
 "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

However, it is also possible to send data via Protocol Buffers. Please refer to the CoAP transport type configuration section in device profile article for more details.

Using custom binary format or some serialization framework is also possible. See protocol customization for more details.

Telemetry upload API

In order to publish telemetry data to ThingsBoard server node, send POST request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/telemetry

The simplest supported data formats are:

1

{"key1":"value1", "key2":"value2"}

or

1

[{"key1":"value1"}, {"key2":"value2"}]
Doc info icon

Please note
that in this case, the server-side timestamp will be assigned to uploaded data!

In case your device is able to get the client-side timestamp, you can use following format:

1

{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

Where 1451649600512 is a unix timestamp with milliseconds precision. For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’.


Below are examples of commands for publishing different types of telemetry data.

Don’t forget to replace demo.thingsboard.io with your host and $ACCESS_TOKEN with your device’s access token. In this example, the hostname references live demo server.

Example 1. Publish data as an object without timestamp (server-side timestamp will be used) using data from telemetry-data-as-object.json file.

1

cat telemetry-data-as-object.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

The content of the JSON file:

1
2
3
4
5
6
7
8
9
10
11

{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

Example 2. Publish data as an array of objects without timestamp (server-side timestamp will be used) using data from telemetry-data-as-array.json file.

1

cat telemetry-data-as-array.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

The content of the JSON file:

1

[{"key1":"value1"}, {"key2":true}]

Example 3. Publish data as an object with timestamp (telemetry timestamp will be used) using data from telemetry-data-with-ts.json file.

1

cat telemetry-data-with-ts.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

The content of the JSON file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "ts": 1451649600512,
  "values": {
    "stringKey": "value1",
    "booleanKey": true,
    "doubleKey": 42.0,
    "longKey": 73,
    "jsonKey": {
      "someNumber": 42,
      "someArray": [1, 2, 3],
      "someNestedObject": {
        "key": "value"
      }
    }
  }
}

Attributes API

ThingsBoard attributes API allows devices to

  • Upload client-side device attributes to the server.
  • Request client-side and shared device attributes from the server.
  • Subscribe to shared device attributes from the server.

Publish attribute update to the server

In order to publish client-side device attributes to ThingsBoard server node, send POST request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes

Publish client-side attributes update using data from new-attributes-values.json file.

The content of the “new-attributes-values.json” file:

1
2
3
4
5
6
7
8
9
10
11

{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

1

cat new-attributes-values.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes

Request attribute values from the server

In order to request client-side or shared device attributes to ThingsBoard server node, send GET request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
Doc info icon

NOTE:
This example shown with the coap-client instead of CoAP cli since CoAP cli does not support query parameters. Please refer to Client libraries setup.

1

coap-client -m get "coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

Result:

1

{"client":{"attribute1":"value1","attribute2":true}}
Doc info icon

Please note:
the intersection of client-side and shared device attribute keys is a bad practice! However, it is still possible to have same keys for client, shared or even server-side attributes.

Subscribe to attribute updates from the server

In order to subscribe to shared device attribute changes, send GET request with Observe option to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/attributes

Once shared attribute will be changed by one of the server-side components (REST API or Rule Chain) the client will receive the following update:

1

coap get -o coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes

Result:

1

{"client":{"attribute1":"value1","attribute2":true}}

JSON value support

We have added support of JSON data structures to telemetry and attributes API to simplify work with device configuration. JSON support allows you to both upload from the device, and push nested objects to the device. You can store one configuration JSON as a shared attribute and push it to the device. You can also process the JSON data in the rule engine and raise alarms, etc.

Therefore, this improvement minimizes the number of Database operations when ThingsBoard stores the data. For example, “temperature” and “humidity” would be stored as separate rows in SQL or NoSQL databases in order to efficiently aggregate this data for visualization. Since there is no need to aggregate JSON data, we can store all the content as one row instead of separate rows for each configuration item. In some of our environments, it is possible to decrease the number of database operations more than 10 times by aggregating multiple parameters within one JSON.

Learn more about JSON value support with the video.

RPC API

Server-side RPC

In order to subscribe to RPC commands from the server, send GET request with observe flag to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/rpc

Once subscribed, a client may receive rpc requests. An example of RPC request body is shown below:

1
2
3
4
5
6
7
8

{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

Where

  • id - request id, integer request identifier;
  • method - RPC method name, string;
  • params - RPC method params, custom json object.

and can reply to them using POST request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/{$id}

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/rpc/{$id}

Where

  • $id is an integer request identifier.


Let’s look at an example:

  • Use RPC debug terminal widget in your ThingsBoard instance;

  • Subscribe to RPC commands from the server using the command below. To do this, in the first terminal window send GET request with observe flag. Don’t forget to replace $THINGSBOARD_HOST_NAME with your host and $ACCESS_TOKEN with your device’s access token:

1

coap-client -m get coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc -s 100 -B 100
Doc info icon

The “s” option stands for subscribe and the value has to be specified in seconds.

The “B” options stands for break (the operation will be break after desired timeout) and the value has to be specified in seconds

  • Send an RPC request “connect” to the device using RPC debug terminal widget;

  • Save the “rpc-response.json” file to your PC;

  • In the second terminal window simulate sending a response from the device to the server:

1

coap-client -f rpc-response.json -m post coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/1
  • You should receive a response from the device:
1

{"result":"ok"}

Client-side RPC

In order to send RPC commands to the server, send POST request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/rpc

Both request and response body should be valid JSON documents. The content of the documents is specific to the rule node that will handle your request.


Let’s look at an example:

  • Add two nodes to the Rule Chain: “script” and “rpc call reply”;

  • In the script node enter the function:

1

return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};

  • Save the “rpc-client-request.json” file to your PC;

  • Now, send request to the server using the command below. Don’t forget to replace $THINGSBOARD_HOST_NAME with your host and $ACCESS_TOKEN with your device’s access token:

1

cat rpc-client-request.json | coap post coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
  • You should receive a response from the server:
1

{"time":"2016 11 21 12:54:44.287"}

Claiming devices

Please see the corresponding article to get more information about the Claiming devices feature.

In order to initiate claiming device, send POST request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/claim

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/claim

The supported data format is:

1

{"secretKey":"value", "durationMs":60000}
Doc info icon

Please note
that the above fields are optional. In case the secretKey is not specified, the empty string as a default value is used. In case the durationMs is not specified, the system parameter device.claim.duration is used (in the file /etc/thingsboard/conf/thingsboard.yml).

Device provisioning

Please see the corresponding article to get more information about the Device provisioning feature.

In order to initiate device provisioning, send POST request to the following URL:

1

coap://$THINGSBOARD_HOST_NAME/api/v1/provision

Where $THINGSBOARD_HOST_NAME - your localhost, or the platform address.

If you use live demo server, the command will look like this:

1

coap://demo.thingsboard.io/api/v1/provision

The supported data format is:

1
2
3
4
5

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

Firmware API

The CoAP client has to issue the GET request to

1

coap get coap://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION

Where

  • $THINGSBOARD_HOST_NAME - your localhost, or the platform address;
  • $ACCESS_TOKEN - device access token;
  • $TITLE - the firmware title;
  • $VERSION - the version of the target firmware.

If you use live demo server, the command will look like this:

1

coap get coap://demo.thingsboard.io/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION

Protocol customization

CoAP transport can be fully customized for specific use-case by changing the corresponding module.

Next steps