ThingsBoard MQTT Device API

Introduction

ThingsBoard API consists of two main parts: Device API and Server-side API.

interface "MQTT Device API" as MQTTAPI interface "<s>CoAP Device API</s>" as CoAPAPI interface "<s>HTTP Device API</s>" as HTTPAPI

interface "Websocket API" as WebsocketAPI interface "REST API" as RestAPI

node "nThingsBoard IoT platformn" as TBSrv { }

node "nDevicen" as TBDev { } note bottom of TBDev Switch one in MQTT API, CoAP API and HTTP API end note

node "Server-side Application" as TBApp {: node "nWeb UIn" as WebUI { } node "nMobile Applicationn" as TBMobileApp { }

}

TBSrv -down- MQTTAPI TBSrv -down- CoAPAPI TBSrv -down- HTTPAPI TBSrv -down- RestAPI TBSrv -down- WebsocketAPI

TBDev .up.> MQTTAPI TBDev .up.> CoAPAPI : Device API TBDev .up.> HTTPAPI

TBApp -up-> RestAPI TBApp -up-> WebsocketAPI : Server-side API

Server-side API is available as REST API and Websocket API:
- REST API:
  
  Administration REST API - The server-side core APIs.
  
  Attributes query API - The server-side APIs provided by Telemetry Service.
  
  Time-series query API - The server-side APIs provided by Telemetry Service.
  
  RPC API - The server-side APIs provided by RPC Service.
  
  REST Client
- Websocket API:
  
  Websocket API duplicates REST API functionality and provides the ability to subscribe to device data changes.
Device API is grouped by supported communication protocols:
- MQTT Device API
- CoAP Device API ( Not supported! )
- HTTP Device API ( Not supported! )

Getting started

See MQTT Device API Reference.

MQTT basics

MQTT is a lightweight publish-subscribe messaging protocol which probably makes 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 predefined 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 setup one of those tools, you can use instructions in our Hello World guide.

MQTT Connect

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 connect sequence:

0x00 Connected - Successfully connected to ThingsBoard MQTT server.
0x04 Connection Refused, bad user name or password - Username is empty.
0x05 Connection Refused, not authorized - Username contains invalid $ACCESS_TOKEN.

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:

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

Telemetry upload API

title Telemetry upload

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"key1":"value1", "key2":"value2"} or nPayload: [{"key1":"value1"}, {"key2":"value2"}] or nPayload: {"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

In order to publish telemetry data to ThingsBoard server node, send PUBLISH message to the following topic:

v1/devices/me/telemetry

The simplest supported data formats are:

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

or

[{"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:

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

In the example above, we assume that “1451649600512” is a unix timestamp with milliseconds precision. For example, the value "1451649600512" corresponds to "Fri, 01 Jan 2016 12:00:00.512 GMT"

Example

mosquitto-telemetry.sh

# Publish data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-object.json"
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-array.json"
# Publish data as an object with timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"

mqtt-js-telemetry.sh

# Publish data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data-as-object.json | mqtt pub -v -h "127.0.0.1" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
cat telemetry-data-as-array.json | mqtt pub -v -h "127.0.0.1" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s
# Publish data as an object with timestamp (server-side timestamp will be used)
cat telemetry-data-with-ts.json | mqtt pub -v -h "127.0.0.1" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s

telemetry-data-as-object.json

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

telemetry-data-as-array.json

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

telemetry-data-with-ts.json

{
   "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

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

Request attribute values from the server

title Request attribute values from the server

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Subscribe to client-side and shared attribute response from the server == TBDev -> TBSrv: subscribe to attribute response (MQTT, SUBSCRIBE) nTopic: v1/devices/me/attributes/response/+

== Request client-side and shared attributes from the server == TBDev -> TBSrv: request attribute values from the server (MQTT, PUBLISH) nTopic: v1/devices/me/attributes/request/$request_id nPayload: {"clientKeys":"attribute1,attribute2", "sharedKeys":"shared1,shared2"}

TBDev <-- TBSrv: receive response (MQTT, PUBLISH) nTopic: v1/devices/me/attributes/response/$request_id nPayload: {"client":{"attribute1":"value1","attribute2":"value2"},n"shared":{"shared1":"value1","shared1":"value2"}}

Before sending PUBLISH message with the attributes request, client need to subscribe to:

v1/devices/me/attributes/response/+

Once subscribed, the client may request client-side or shared device attributes to ThingsBoard server node, send PUBLISH message to the following topic:

v1/devices/me/attributes/request/$request_id

where $request_id is your integer request identifier.

The client should receive the response to the following topic:

v1/devices/me/attributes/response/$request_id

Example

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.

Client library	Shell file	JavaScript file	Result (JSON file)
MQTT.js	mqtt-js-attributes-request.sh	mqtt-js-attributes-request.js	attributes-response.json

mqtt-js-attributes-request.sh

export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js

mqtt-js-attributes-request.js

var mqtt = require('mqtt')
var client  = mqtt.connect('mqtt://127.0.0.1',{
   username: process.env.TOKEN
})

client.on('connect', function () {
   console.log('connected')
   client.subscribe('v1/devices/me/attributes/response/+')
   client.publish('v1/devices/me/attributes/request/1', '{"clientKeys":"attribute1,attribute2", "sharedKeys":"shared1,shared2"}')
})

client.on('message', function (topic, message) {
   console.log('response.topic: ' + topic)
   console.log('response.body: ' + message.toString())
   client.end()
})

attributes-response.json

{"key1":"value1"}

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.

Publish attribute update to the server

title Publish attribute update to the server

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

TBDev -> TBSrv: publish client-side attributes update to the server (MQTT, PUBLISH) nTopic: v1/devices/me/attributes nPayload: {"attribute1":"value1","attribute2":true}

In order to publish client-side device attributes to ThingsBoard server node, send PUBLISH message to the following topic:

v1/devices/me/attributes

Example

mosquitto-attributes-publish.sh

# Publish client-side attributes update
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"

mqtt-js-attributes-publish.sh

# Publish client-side attributes update
cat new-attributes-values.json | mqtt pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN' -s

new-attributes-values.json

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

Subscribe to attribute updates from the server

title Subscribe to attribute updates from the server

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Subscribe to attribute updates from the server == TBDev -> TBSrv: subscribe to attribute response (MQTT, SUBSCRIBE) nTopic: v1/devices/me/attributes

== Receive the attribute update from the server == TBDev <- TBSrv: receive attribute update from the server (MQTT, PUBLISH) nTopic: v1/devices/me/attributes nPayload: {"attribute1":"value1","attribute2":"value2"}

In order to subscribe to shared device attribute changes, send SUBSCRIBE message to the following topic:

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:

{"key1":"value1"}

Example

Client library	Shell file
Mosquitto	mosquitto-attributes-subscribe.sh
MQTT.js	mqtt-js-attributes-subscribe.sh

mosquitto-attributes-subscribe.sh

# Subscribes to attribute updates
mosquitto_sub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"

mqtt-js-attributes-subscribe.sh

# Subscribes to attribute updates
mqtt sub -v "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN'

PRC API

Server-side RPC

title Server-side RPC

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Subscribe to sever-side RPC request from the server == TBDev -> TBSrv: subscribe to sever-side RPC request (MQTT, SUBSCRIBE) nTopic: v1/devices/me/rpc/request/+

== Receive two-way sever-side RPC request from the server == TBDev <- TBSrv: receive server-side RPC request from the server (MQTT, PUBLISH) nTopic: v1/devices/me/rpc/request/$request_id nPayload: {"method":"remoteOTA","params":"http://192.168.xx.xxx/abc.bin"}

TBDev --> TBSrv: send response (MQTT, PUBLISH) nTopic: v1/devices/me/rpc/response/$request_id nPayload: {"method":"remoteOTA","results":{"result":"success"}}

== Receive one-way sever-side RPC request from the server == TBDev <- TBSrv: receive server-side RPC request from the server (MQTT, PUBLISH) nTopic: v1/devices/me/rpc/request/$request_id nPayload: {"method":"setSpValue","params":14.5}

In order to subscribe to RPC commands from the server, send SUBSCRIBE message to the following topic:

v1/devices/me/rpc/request/+

Once subscribed, the client will receive individual commands as a PUBLISH message to the corresponding topic:

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:

v1/devices/me/rpc/response/$request_id

Example

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.

Client library	Shell file	JavaScript file
MQTT.js	mqtt-js-rpc-from-server.sh	mqtt-js-rpc-from-server.js

mqtt-js-rpc-from-server.sh

export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js

mqtt-js-rpc-from-server.js

var mqtt = require('mqtt');
var client  = mqtt.connect('mqtt://127.0.0.1',{
   username: process.env.TOKEN
});

client.on('connect', function () {
   console.log('connected');
   client.subscribe('v1/devices/me/rpc/request/+')
});

client.on('message', function (topic, message) {
   console.log('request.topic: ' + topic);
   console.log('request.body: ' + message.toString());
   var requestId = topic.slice('v1/devices/me/rpc/request/'.length);
   //client acts as an echo service
   client.publish('v1/devices/me/rpc/response/' + requestId, message);
});

Client-side RPC

title Client-side RPC

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Subscribe to client-side RPC response from the server == TBDev -> TBSrv: subscribe to client-side RPC response (MQTT, SUBSCRIBE) nTopic: v1/devices/me/rpc/response/+

== Publish client-side RPC request == TBDev -> TBSrv: publish client-side RPC request (MQTT, PUBLISH) nTopic: v1/devices/me/rpc/request/$request_id nPayload: {"method":"getTime","params":{}}

TBDev <-- TBSrv: receive response (MQTT, PUBLISH) nTopic: v1/devices/me/rpc/response/$request_id n{"method":"getTime","results":{"utcDateime":"2020-06-18T09:16:59Z"}}

In order to subscribe to client-side RPC response from the server, send SUBSCRIBE message to the following topic:

v1/devices/me/rpc/response/+

Once subscribed, the client may send PUBLISH message to the following topic:

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:

v1/devices/me/rpc/response/$request_id

Example

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.

Client library	Shell file	JavaScript file
MQTT.js	mqtt-js-rpc-from-client.sh	mqtt-js-rpc-from-client.js

mqtt-js-rpc-from-client.sh

export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-client.js

mqtt-js-rpc-from-client.js

var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://127.0.0.1', {
   username: process.env.TOKEN
});

client.on('connect', function () {
   console.log('connected');
   client.subscribe('v1/devices/me/rpc/response/+');
   var requestId = 1;
   var request = {
      "method": "getTime",
      "params": {}
   };
   client.publish('v1/devices/me/rpc/request/' + requestId, JSON.stringify(request));
});

client.on('message', function (topic, message) {
   console.log('response.topic: ' + topic);
   console.log('response.body: ' + message.toString());
});

Claiming API

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

title Claiming API

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

TBDev -> TBSrv: Initiate claiming device (MQTT, PUBLISH) nTopic: v1/devices/me/claim nPayload: {"secretKey":"value", "durationMs":60000}

In order to initiate claiming device, send PUBLISH message to the following topic:

v1/devices/me/claim

The supported data format is:

{"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 ).

Firmware API

title Firmware API - A(1)

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Send to current firmware status to the server == TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"current_fw_title":"TA652FC-W-TB","current_fw_version":"1.6.6"}

== Subscribe to shared attribute response from the server == TBDev -> TBSrv: subscribe to attribute response (MQTT, SUBSCRIBE) nTopic: v1/devices/me/attributes/response/+

== Request shared attributes from the server == TBDev -> TBSrv: request attribute values from the server (MQTT, PUBLISH) nTopic: v1/devices/me/attributes/request/$request_id nPayload: {"sharedKeys":"fw_title,fw_version,fw_size,nfw_checksum,fw_checksum_algorithm"}

TBDev <-- TBSrv: receive response (MQTT, PUBLISH) nTopic: v1/devices/me/attributes/response/$request_id nPayload: {"shared":{"fw_title":"TA652FC-W-TB",n"fw_version":"1.6.8","fw_size":1315392,n"fw_checksum_algorithm":"MD5",n"fw_checksum":"9cd4197f260254ac7b6e761b89c7cb66"}}

title Firmware API - A(2)

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Subscribe to attribute updates from the server == TBDev -> TBSrv: subscribe to attribute response (MQTT, SUBSCRIBE) nTopic: v1/devices/me/attributes

== Receive the attribute update from the server == TBDev <- TBSrv: receive attribute update from the server (MQTT, PUBLISH) nTopic: v1/devices/me/attributes nPayload: {"fw_title":"TA652FC-W-TB","fw_version":"1.6.8",n"fw_tag":"TA652FC-W-TB 1.6.8","fw_size":1315392,n"fw_checksum_algorithm":"MD5",n"fw_checksum":"9cd4197f260254ac7b6e761b89c7cb66"}

title Firmware API - B

participant "Device" as TBDev order 10 participant "ThingsBoard Server" as TBSrv order 20

== Send to current firmware status (DOWNLOADING) to the server == TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"current_fw_title":"TA652FC-W-TB",n"current_fw_version":"1.6.6","fw_state":"DOWNLOADING"}

== Subscribe to firmware chunk response from the server == TBDev -> TBSrv: subscribe to firmware chunk response (MQTT, SUBSCRIBE) nTopic: v2/fw/response/+/chunk/+

== Request firmware chunk from the server == TBDev -> TBSrv: request firmware chunk from the server (MQTT, PUBLISH) nTopic: v2/fw/request/${requestId}/chunk/${chunkIndex} nPayload: 8192

TBDev <-- TBSrv: receive response (MQTT, PUBLISH) nTopic: v2/fw/response/${requestId}/chunk/${chunkIndex} nPayload: firmware binary data

TBDev <--> TBSrv: ...

== Send to current firmware status to the server == TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"current_fw_title":"TA652FC-W-TB",n"current_fw_version":"1.6.6","fw_state":"DOWNLOADED"} TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"current_fw_title":"TA652FC-W-TB",n"current_fw_version":"1.6.6","fw_state":"VERIFIED"} TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"current_fw_title":"TA652FC-W-TB",n"current_fw_version":"1.6.6","fw_state":"UPDATING"} TBDev -> TBSrv: Telemetry upload (MQTT, PUBLISH) nTopic: v1/devices/me/telemetry nPayload: {"current_fw_title":"TA652FC-W-TB",n"current_fw_version":"1.6.6","fw_state":"UPDATED"}

Replace 8192 with your chunk size.

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:

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:

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:

v2/fw/response/+/chunk/+

Where

+ is the Wildcard character.

Device MQTT Topic

Function Topic	Subscribe	Tx	Rx
Telemetry		① v1/devices/me/telemetry

Request attributes	① v1/devices/me/attributes/response/+	② v1/devices/me/attributes/request/${requestId}	③ v1/devices/me/attributes/response/${requestId}
Publish attributes		① v1/devices/me/attributes
Subscribe attributes update	① v1/devices/me/attributes		② v1/devices/me/attributes

Server-Side RPC	① v1/devices/me/rpc/request/+	③ v1/devices/me/rpc/response/${requestId}	② v1/devices/me/rpc/request/${requestId}
Client-Side RPC	① v1/devices/me/rpc/response/+	② v1/devices/me/rpc/request/${requestId}	③ v1/devices/me/rpc/response/${requestId}

Claiming device		① v1/devices/me/claim

Firmware updates*	① v2/fw/response/+/chunk/+	② v2/fw/request/${requestId}/chunk/${chunkIndex}	③ v2/fw/response/${requestId}/chunk/${chunkIndex}

Note

①②③ The order in which topics are performed.
Firmware updates needs the support of Telemetry, Request attributes and Subscribe attributes update.

Files

thingsboard-mqtt-device-api.rst

Latest commit

History

thingsboard-mqtt-device-api.rst

File metadata and controls

ThingsBoard MQTT Device API

Introduction

Getting started

MQTT basics

Client libraries setup

MQTT Connect

Key-value format

Telemetry upload API

Example

mosquitto-telemetry.sh

mqtt-js-telemetry.sh

telemetry-data-as-object.json

telemetry-data-as-array.json

telemetry-data-with-ts.json

Attributes API

Request attribute values from the server

Example

mqtt-js-attributes-request.sh

mqtt-js-attributes-request.js

attributes-response.json

Publish attribute update to the server

Example

mosquitto-attributes-publish.sh

mqtt-js-attributes-publish.sh

new-attributes-values.json

Subscribe to attribute updates from the server

Example

mosquitto-attributes-subscribe.sh

mqtt-js-attributes-subscribe.sh

PRC API

Server-side RPC

Example

mqtt-js-rpc-from-server.sh

mqtt-js-rpc-from-server.js

Client-side RPC

Example

mqtt-js-rpc-from-client.sh

mqtt-js-rpc-from-client.js

Claiming API

Firmware API

Device MQTT Topic