- Client libraries setup
- Authentication methods
- Key-value format
- Telemetry upload API
- Attributes API
- JSON value support
- RPC API
- Claiming devices
- Device provisioning
- Firmware API
- Protocol customization
- Next steps
CoAP is a lightweight, UDP-based protocol designed for constrained IoT devices.
Although it follows a request–response model similar to HTTP, CoAP is optimized for low-power and low-bandwidth networks.
You can find more information about CoAP here.
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
Many CoAP client libraries are available for different platforms and languages.
The examples in this guide are based on CoAP cli, a command-line CoAP client.
Install CoAP CLI (Linux/macOS)
1
npm install coap-cli -g
Note: CoAP CLI does not support query parameters. If your use case requires query parameters, use coap-client instead.
Install coap-client
- Ubuntu 20.04+
1
sudo apt install libcoap2-bin
- for Ubuntu 18.04
1
sudo apt install libcoap1-bin
Authentication methods
ThingsBoard supports two authentication mechanisms to secure COAP connections.
Supported methods:
- Access token. Uses a unique device access token included as a path parameter in each CoAP request.
- X.509 certificates. Uses digital certificates to authenticate devices and establish secure communication based on public key infrastructure (PKI).
The examples in this guide use access token–based authentication.
Possible error codes and their reasons:
- 4.00 Bad Request - Invalid URL, parameters, or payload
- 4.01 Unauthorized - Invalid access token
- 4.04 Not Found - Requested resource does not exist
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.
First, select the authentication method:
Send POST request to the following URL:
|
Send POST request to the following URL:
|
The simplest supported data formats are:
1
{"key1":"value1", "key2":"value2"}
or
1
[{"key1":"value1"}, {"key2":"value2"}]
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’.
Examples
Below are examples of commands for publishing different types of telemetry data.
⚠️ Don't forget to replace
•$THINGSBOARD_EDGE_HOST_NAMEwith your ThingsBoard Edge hostname or IP address.
•$ACCESS_TOKENwith your device's access token.
Example 1.
Publish data as an object without timestamp (server-side timestamp will be used) using data from telemetry-data-as-object.json file.
|
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.
|
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.
|
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.
First, select the authentication method:
Send POST request to the following URL:
Publish client-side attributes update using data from new-attributes-values.json file. The content of the “new-attributes-values.json” file: Execute the command: |
Send POST request to the following URL:
Publish client-side attributes update using data from new-attributes-values.json file. The content of the “new-attributes-values.json” file: Execute the command: |
Request attribute values from the server
In order to request client-side or shared device attributes to ThingsBoard server node, send GET request.
First, select the authentication method:
Send GET request to the following URL:
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. Execute the command: |
Send GET request to the following URL:
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. Execute the command: |
Result:
1
{"client":{"attribute1":"value1","attribute2":true}}
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.
First, select the authentication method:
Send GET request with Observe option to the following URL:
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: Execute the command: |
Send GET request with Observe option to the following URL:
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: Execute the command: |
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.
First, select the authentication method:
Send GET request with observe flag to the following URL:
Once subscribed, a client may receive RPC requests. An example of RPC request body is shown below:
To reply to an RPC request, send a POST request to the following URL
Example
The “ The “
You should receive a response from the device: |
Send GET request with observe flag to the following URL:
Once subscribed, a client may receive RPC requests. An example of RPC request body is shown below:
To reply to an RPC request, send a POST request to the following URL
Example
The “ The “
|
Client-side RPC
In order to send RPC commands to the server, send POST request.
First, select the authentication method:
Send POST request to the following URL:
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.
|
Send POST request to the following URL:
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.
|
Claiming devices
The Device Claiming feature allows end users to securely associate a device with their account after the device has been deployed and connected to ThingsBoard. For a detailed explanation of the device claiming workflow and supported scenarios, refer to the Claiming devices documentation.
In order to initiate claiming device, send POST request.
First, select the authentication method:
Send POST request to the following URL:
|
Send POST request to the following URL:
|
The supported data format is:
1
{"secretKey":"value", "durationMs":60000}
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
Device provisioning allows devices to be registered dynamically without manual creation in the ThingsBoard UI. For a detailed explanation of the provisioning process and supported scenarios, refer to the Device provisioning documentation.
Provisioning request
To initiate device provisioning, send POST request to the following URL:
1
coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/provision
Where $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
Request Payload
The provisioning request must use the following JSON format:
1
2
3
4
5
{
"deviceName": "DEVICE_NAME",
"provisionDeviceKey": "u7piawkboq8v32dmcmpp",
"provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}
Payload fields
- deviceName — the name of the device to be provisioned.
- provisionDeviceKey — the provisioning key configured in ThingsBoard.
- provisionDeviceSecret — the provisioning secret associated with the provisioning key.
If the provided credentials are valid, ThingsBoard automatically creates the device (if it does not already exist) and returns the device credentials, allowing the device to start communicating with the platform.
Firmware API
Select the authentication method:
The CoAP client has to issue the GET request to Where
|
The CoAP client has to issue the GET request to Where
|
Protocol customization
CoAP transport can be fully customized for specific use-case by changing the corresponding module.
Next steps
-
Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.
-
Data visualization - These guides contain instructions on how to configure complex ThingsBoard dashboards.
-
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
-
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
-
Advanced features - Learn about advanced ThingsBoard features.
-
Contribution and Development - Learn about contribution and development in ThingsBoard.