- Getting started
- Key-value format
- Telemetry upload API
- Attributes API
- JSON value support
- RPC API
- Claiming devices
- Device provisioning
- Firmware API
- Protocol customization
- Next steps
Getting started
MQTT basics
MQTT is a lightweight publish-subscribe messaging protocol,probably making it the most suitable for various IoT devices. You can find more information about MQTT here.
ThingsBoard server nodes act as an MQTT Broker that supports QoS levels 0 (at most once) and 1 (at least once) and a set of configurable topics.
Client libraries setup
You can find a large number of MQTT client libraries on the web. Examples in this article will be based on Mosquitto and MQTT.js. In order to set up one of those tools, you can use the instructions in our Hello World guide.
MQTT Connect
In this article, we will use access token device credentials in this article and they will be referred to later as $ACCESS_TOKEN. The application needs to send MQTT CONNECT message with username that contains $ACCESS_TOKEN.
Possible return codes, and their reasons during the connect sequence:
- 0x00 Connected - Successfully connected to ThingsBoard MQTT server.
- 0x04 Connection Refused, bad username or password - Username is empty.
- 0x05 Connection Refused, not authorized - Username contains invalid $ACCESS_TOKEN.
The alternative authentication option is to use X.509 Certificates or Basic MQTT Credentials - combination of client id, username and password.
Now you are ready to publish telemetry data on behalf of your device. We will use simple commands to publish data over MQTT in this example. Select your OS:
Install mqtt client for Ubuntu:
Install cURL for macOS:
Replace $ACCESS_TOKEN with corresponding value.
For example, $ACCESS_TOKEN is ABC123:
Successful output should look similar to this one:
|
Use the instructions listed below to download, install, setup and run mosquitto_pub in Windows:
To add the Mosquitto directory to the “Path” variable, follow these steps: Open the Terminal and replace $ACCESS_TOKEN with corresponding value.
For example, $ACCESS_TOKEN is ABC123:
Successful output should look similar to this one:
|
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 MQTT 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 PUBLISH message to the following topic:
1
v1/devices/me/telemetry
The simplest supported data formats are:
1
{"key1":"value1", "key2":"value2"}
or
1
[{"key1":"value1"}, {"key2":"value2"}]
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 the examples of commands for publishing different types of telemetry data.
Don’t forget to replace $ACCESS_TOKEN
with your device’s access token.
Example 1. Publish data as an object without timestamp (server-side timestamp will be used).
Execute the command:
|
|
Telemetry data:
1
{"temperature":42}
Example 2. Publish data as an object without timestamp (server-side timestamp will be used) using data from telemetry-data-as-object.json file.
Execute the command:
|
|
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 3. Publish data as an array of objects without timestamp (server-side timestamp will be used) using data from telemetry-data-as-array.json file.
Execute the command:
|
|
The content of the JSON file:
1
[{"key1":"value1"}, {"key2":true}]
Example 4. Publish data as an object with timestamp (telemetry timestamp will be used) using data from telemetry-data-with-ts.json file.
Execute the command:
|
|
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 PUBLISH message to the following topic:
1
v1/devices/me/attributes
Below are the examples of how to publish client-side device attributes.
Don’t forget to replace $ACCESS_TOKEN
with your device’s access token.
Example 1. Publish client-side attributes update.
Telemetry data:
1
{"attribute1": "value1", "attribute2": true}
Execute the command:
1
mosquitto_pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}"
Example 2. 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"}
}
}
Execute the command:
|
|
Request attribute values from the server
In order to request client-side or shared device attributes to ThingsBoard server node, send PUBLISH message to the following topic:
1
v1/devices/me/attributes/request/$request_id
where $request_id is your integer request identifier. Before sending PUBLISH message with the request, client needs to subscribe to
1
v1/devices/me/attributes/response/+
The following example is written in javascript and is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.
Save the “mqtt-js-attributes-request.js” file to your PC.
|
Execute the command. Don’t forget to replace $ACCESS_TOKEN
with your device’s access token.
1
2
export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js
Result:
1
{"client":{"attribute1":"value1","attribute2":true}}
Subscribe to attribute updates from the server
In order to subscribe to shared device attribute changes, send SUBSCRIBE message to the following topic:
1
v1/devices/me/attributes
When a shared attribute is changed by one of the server-side components (such as the REST API or the Rule Chain), the client will receive the following update:
1
{"key1":"value1"}
For the following example, don’t forget to replace $ACCESS_TOKEN
with your device’s access token.
Execute the command:
|
|
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 SUBSCRIBE message to the following topic:
1
v1/devices/me/rpc/request/+
Once subscribed, the client will receive individual commands as a PUBLISH message to the corresponding topic:
1
v1/devices/me/rpc/request/$request_id
where $request_id is an integer request identifier.
The client should publish the response to the following topic:
1
v1/devices/me/rpc/response/$request_id
The following example is written in javascript and is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.
Save the “mqtt-js-rpc-from-server.js” file to your PC.
|
Now, follow these steps:
- Use RPC debug terminal widget in your ThingsBoard instance;
- Execute the command to subscribe to RPC commands from the server using the command below. Don’t forget to replace
$ACCESS_TOKEN
with your device’s access token.
1
2
export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js
- Send an RPC request “connect” to the device using RPC debug terminal widget;
- You should receive a response from the device.
In case your MQTT device is a gateway, ThingsBoard will send a server-side RPC (notification) about changes on provisioned device entities.
Your MQTT gateway device will receive a service RPC about removal or renaming of device to properly resolve such events.
Client-side RPC
In order to send RPC commands to server, send PUBLISH message to the following topic:
1
v1/devices/me/rpc/request/$request_id
where $request_id is an integer request identifier. The response from server will be published to the following topic:
1
v1/devices/me/rpc/response/$request_id
The following example is written in javascript and is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.
Save the “mqtt-js-rpc-from-client.js” file to your PC.
|
Now, follow these steps:
- 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};
- Send request to the server. Don’t forget to replace
$ACCESS_TOKEN
with your device’s access token.
1
2
export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-client.js
- You should receive a response from the server.
Get session limits RPC
The getSessionLimits RPC method is designed to help device manufacturers and developers understand the limits that used by the MQTT transport. Understanding these limits ensures that devices operate within the defined parameters, preventing issues like message rejection or connection loss.
A typical RPC to retrieve session limits from the ThingsBoard server looks like this:
1
2
3
4
{
"method": "getSessionLimits",
"params": {}
}
Once RPC is processed server can send session limits back to the response topic using following format:
1
2
3
4
5
6
7
8
9
{
"maxPayloadSize": 65536,
"maxInflightMessages": 100,
"rateLimits": {
"messages": "200:1,6000:60,14000:3600",
"telemetryMessages": "100:1,3000:60,7000:3600",
"telemetryDataPoints": "200:1,6000:60,14000:3600"
}
}
Where
maxPayloadSize - the maximum allowable size for an MQTT message payload, expressed in bytes.
maxInflightMessages - the maximum number of MQTT messages that can be sent but remain unacknowledged (in-flight) at any given time.
rateLimits - a nested object that specifies the rate limits for different types.
messages - the overall message rate limit.
telemetryMessages - the maximum number of telemetry messages that can be sent.
telemetryDataPoints - the number of telemetry data points a device can send.
Below is an interpretation of the rate limit value “200:1,6000:60,14000:3600”:
“200:1” - 200 messages can be sent per second.
“6000:60” - 6000 messages can be sent per 60 seconds (1 minute).
“14000:3600” - 14000 messages can be sent over a period of 3600 seconds (1 hour).
If the device is a gateway, the response includes additional rate limits for devices that are connected through the gateway. The response structure for gateways looks like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"maxPayloadSize": 65536,
"maxInflightMessages": 100,
"rateLimits": {
"messages": "200:1,6000:60,14000:3600",
"telemetryMessages": "100:1,3000:60,7000:3600",
"telemetryDataPoints": "200:1,6000:60,14000:3600"
},
"gatewayRateLimits": {
"messages": "200:1,6000:60,14000:3600",
"telemetryMessages": "100:1,3000:60,7000:3600",
"telemetryDataPoints": "200:1,6000:60,14000:3600"
}
}
rateLimits - a nested object that specifies rate limits for the gateway.
gatewayRateLimits - a nested object that specifies rate limits for devices connected to the gateway.
Claiming devices
Please see the corresponding article to get more information about the Claiming devices feature.
In order to initiate claiming device, send PUBLISH message to the following topic:
1
v1/devices/me/claim
The supported data format is:
1
{"secretKey":"value", "durationMs":60000}
Device provisioning
Please see the corresponding article to get more information about the Device provisioning feature.
In order to initiate device provisioning, send Provisioning request to the following topic:
1
/provision
Also, you should set username or clientId to provision.
The supported data format is:
1
2
3
4
5
{
"deviceName": "DEVICE_NAME",
"provisionDeviceKey": "u7piawkboq8v32dmcmpp",
"provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}
Firmware API
When ThingsBoard initiates an MQTT device firmware update, it sets the fw_title, fw_version, fw_checksum, fw_checksum_algorithm shared attributes. To receive the shared attribute updates, the device has to subscribe to
1
v1/devices/me/attributes/response/+
Where
+ is the Wildcard character.
When the MQTT device receives updates for fw_title and fw_version shared attributes, it has to send PUBLISH message to
1
v2/fw/request/${requestId}/chunk/${chunkIndex}
Where
${requestId} - number corresponding to the number of firmware updates. The ${requestId} has to be different for each firmware update.
${chunkIndex} - number corresponding to the index of firmware chunks. The ${chunkID} are counted from 0. The device must increment the chunk index for each request until the received chunk size is zero.
And the MQTT payload should be the size of the firmware chunk in bytes.
For each new firmware update, you need to change the request ID and subscribe to
1
v2/fw/response/+/chunk/+
Where
+ is the Wildcard character.
Protocol customization
MQTT 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.
-
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.
-
Advanced features - Learn about advanced ThingsBoard features.