Star

Reference Documentation

Design docs, concept definitions, and references for APIs and CLIs.

MQTT Device API Reference

Getting started

MQTT basics

MQTT is a light-weight 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 a MQTT Broker that support QoS levels 0 (at most once) and 1 (at least once) and a set of predefined topics.

Client libraries setup

You can find huge amount of MQTT client libraries in 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. Application need to send MQTT CONNECT message with username that contains $ACCESS_TOKEN. Possible return codes and their reasons during connect sequence:

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 or long. Using custom binary format or some serialization framework is also possible. See protocol customization for more details. For example:

{"stringKey":"value1", "booleanKey":true, "doubleKey":42.0, "longKey":73}

Telemetry upload API

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, 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’

resources/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"
resources/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
resources/telemetry-data-as-object.json
{"key1":"value1", "key2":true, "key3": 3.0, "key4": 4}
resources/telemetry-data-as-array.json
[{"key1":"value1"}, {"key2":true}]
resources/telemetry-data-with-ts.json
{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

Attributes API

Thingsboard attributes API allows devices to

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:

v1/devices/me/attributes
resources/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"
resources/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
resources/new-attributes-values.json
{"attribute1":"value1", "attribute2":true, "attribute3":42.0, "attribute4":73}
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:

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

where $request_id is your integer request identifier. Before sending PUBLISH message with the request, client need to subscribe to

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.

resources/mqtt-js-attributes-request.sh
export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js
resources/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()
})

Please note, intersection of client-side and shared device attribute keys is a bad practise! 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 SUBSCRIBE message to the following topic:

v1/devices/me/attributes

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

{"key1":"value1"}
resources/mosquitto-attributes-subscribe.sh
# Subscribes to attribute updates
mosquitto_sub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"
resources/mqtt-js-attributes-subscribe.sh
# Subscribes to attribute updates
mqtt sub -v "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN'

RPC API

Server-side RPC

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

v1/devices/me/rpc/request/+

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

v1/devices/me/rpc/request/$request_id

where $request_id is an integer request identifier.

Client should publish the response to following topic:

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.

resources/mqtt-js-rpc-from-server.sh
export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js
resources/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

In order to send RPC commands to server, 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

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.

resources/mqtt-js-rpc-from-client.sh
export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-client.js
resources/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());
});

Protocol customization

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