MQTT Device API Reference

• Client libraries setup
• Authentication methods
• Publish a test telemetry message
• Key-value format
• Telemetry upload API
• Attributes API
  • Publish attribute update to the server
  • Request attribute values from the server
  • Subscribe to attribute updates from the server
• JSON value support
• RPC API
  • Server-side RPC
  • Client-side RPC
  • Get session limits RPC
• Claiming devices
• Device provisioning
• Firmware API
• Protocol customization
• Next steps

MQTT is a lightweight publish/subscribe messaging protocol,probably making it the most suitable for various IoT devices.

ThingsBoard server nodes acts as an MQTT broker and supports:
 • QoS 0 (at most once)
 • QoS 1 (at least once)
 • Configurable MQTT topics via Device profiles

Learn more about MQTT at mqtt.org.

Client libraries setup

Many MQTT client libraries are available for different platforms and languages.

The examples in this guide use:
 • Mosquitto (command-line tools)
 • MQTT.js (JavaScript)

Use the instructions below to install the following command-line utilities:
 • mosquitto_pub
 • mosquitto_sub

Select your operating system to continue with the installation steps:

MQTTLinux or macOS

MQTTWindows

Install mqtt client for Ubuntu: 1 sudo apt-get install mosquitto-clients Install cURL for macOS: 1 brew install mosquitto-clients

Use the instructions listed below to download, install, setup and run mosquitto_pub in Windows: Download and Install Eclipse Mosquitto. Visit Mosquitto’s official download page and choose the appropriate Windows installer (32-bit or 64-bit depending on your system). Once downloaded, run the installer and follow the instructions. This will install Mosquitto on your Windows machine. By default, Mosquitto is installed in ‘C:\Program Files\mosquitto’; Update the System's “Path” variable. The executables ‘mosquitto_pub.exe’ and ‘mosquitto_sub.exe’ are located in the directory where you installed the Mosquitto. You need to add this directory to your system’s “Path” environment variable so that Windows can find these executables regardless of the current directory. To add the Mosquitto directory to the “Path” variable, follow these steps: Press the Win + X, then select “System”. Then click on the “System” page; Navigate to the “About” section, then click “Advanced system settings”; In the “System Properties” pop-up window, click “Environment Variables” button on the “Advanced” tab; In the “Environment Variables” pop-up window, select the “Path”, then click on the “Edit” button; In the “Edit environment variable” pop-up window click on the “New” button and add the path to the directory containing 'mosquitto_pub.exe' and 'mosquitto_sub.exe' ('C:\Program Files\mosquitto' by default). Click “OK” button; Click “OK” button to save changes in the environment variables; Finally, click “OK” button to apply all changes in the system properties.

Authentication methods

ThingsBoard supports multiple authentication mechanisms to secure MQTT connections.

Supported methods:

• Access token. Uses a unique device access token as the MQTT username in the CONNECT packet.
  This method provides a simple and secure way to authenticate devices without requiring certificates or additional credentials.
• X.509 certificates. Uses digital certificates to authenticate devices and establish secure communication based on public key infrastructure (PKI).
• Basic MQTT credentials Uses authentication data—a combination of the optional client ID, username, and password—sent in the MQTT CONNECT packet.

Topic names and payload formats for MQTT communication are configured via the Device profile. For more details, see here.

Note
This guide uses access token–based authentication.

Publish a test telemetry message

Use the following command to publish test telemetry data.

⚠️ Don't forget to replace:
 • $THINGSBOARD_HOST_NAME with your ThingsBoard hostname or IP address.
 • $ACCESS_TOKEN with your device's access token.

1
mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -p "1883" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m {"temperature":25}

Example
In this example, $THINGSBOARD_HOST_NAME refers to your local ThingsBoard installation, and $ACCESS_TOKEN is set to ABC123.

1
mosquitto_pub -d -q 1 -h "localhost" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

A successful telemetry publish produces output similar to the following:

1
2
3
4
5
Client mosqpub|xxx sending CONNECT
Client mosqpub|xxx received CONNACK
Client mosqpub|xxx sending PUBLISH (d0, q1, r0, m1, 'v1/devices/me/telemetry', ... (16 bytes))
Client mosqpub|xxx received PUBACK (Mid: 1)
Client mosqpub|xxx sending DISCONNECT

Possible MQTT connection responses

During the connection process, the MQTT broker may return the following response codes:

• 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.

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"}]

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 the examples of commands for publishing different types of telemetry data.

⚠️ Don't forget to replace
 • $THINGSBOARD_HOST_NAME with your ThingsBoard hostname or IP address.
 • $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:

1
mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m "{"temperature":42}"

1
mqtt pub -v -q 1 -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -m "{"temperature":42}"

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:

1
mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-object.json"

1
cat telemetry-data-as-object.json | mqtt pub -v -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m ""

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:

1
mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-array.json"

1
cat telemetry-data-as-array.json | mqtt pub -v -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m ""

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:

1
mosquitto_pub -d -q 1 -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"

1
cat telemetry-data-with-ts.json | mqtt pub -v -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m ""

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

Examples
Below are the examples of how to publish client-side device attributes.

⚠️ Don't forget to replace
 • $THINGSBOARD_HOST_NAME with your ThingsBoard hostname or IP address.
 • $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 "$THINGSBOARD_HOST_NAME" -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:

1
mosquitto_pub -d -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"

1
cat new-attributes-values.json | mqtt pub -d -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN' -s -m ""

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/+

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.

1. Save the mqtt-js-attributes-request.js file to your PC.

⚠️ In this example, the hostname refers to a local ThingsBoard installation.
If your ThingsBoard instance is deployed on a different host, make sure to replace localhost with the appropriate hostname or IP address.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var mqtt = require('mqtt')
var client  = mqtt.connect('mqtt://localhost',{
    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()
})

2. Execute the command.

⚠️ 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}}

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

⚠️ Don't forget to replace
 • $THINGSBOARD_HOST_NAME with your ThingsBoard hostname or IP address.
 • $ACCESS_TOKEN with your device's access token.

Execute the command:

1
mosquitto_sub -d -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"

1
mqtt sub -v -h "$THINGSBOARD_HOST_NAME" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN'

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

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.

1. Save the mqtt-js-rpc-from-server.js file to your PC.

⚠️ In this example, the hostname refers to a local ThingsBoard installation.
If your ThingsBoard instance is deployed on a different host, make sure to replace localhost with the appropriate hostname or IP address.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://localhost', {
    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);
});

2. 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.

⚠️ 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

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.

1. Save the mqtt-js-rpc-from-client.js file to your PC.

⚠️ In this example, the hostname refers to a local ThingsBoard installation.
If your ThingsBoard instance is deployed on a different host, make sure to replace localhost with the appropriate hostname or IP address.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://localhost', {
    username: process.env.TOKEN
});

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/rpc/response/+');
    var requestId = 1;
    var request = {
        "method": "getCurrentTime",
        "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());
});

2. Now, follow these steps:

• In the Root Rule Chain add two nodes: 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.

⚠️ 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 allows device manufacturers and developers to retrieve the MQTT transport limits enforced by ThingsBoard server.

Understanding these limits helps ensure that devices operate within supported parameters and prevents issues such as message rejection, throttling, or connection loss.

Request format
To request session limits, the device sends the following RPC request:

1
2
3
4
{
  "method": "getSessionLimits",
  "params": {}
}

Response format
After processing the request, ThingsBoard returns the session limits in the RPC response using the 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"
  }
}

Response fields description

• 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 defining rate limits for different message categories:
  • 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.

Rate Limit Format Explanation
A rate limit value such as:

1
200:1,6000:60,14000:3600

• 200:1 — up to 200 messages per second
• 6000:60 — up to 6,000 messages per 60 seconds (1 minute)
• 14000:3600 — up to 14,000 messages per 3,600 seconds (1 hour)

These limits are enforced simultaneously.

Gateway-specific session limits
If the device is a gateway, the response includes additional limits that apply to devices connected through the gateway.

Gateway response format

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

Gateway rate limits description

• rateLimits - rate limits that apply to the gateway device itself.
• gatewayRateLimits - rate limits that apply to individual devices connected through the gateway.

These limits help control load and ensure stable operation when multiple devices communicate through a single gateway connection.

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}

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 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.

• Advanced features - Learn about advanced ThingsBoard features.

• Contribution and Development - Learn about contribution and development in ThingsBoard.