ThingsBoard MQTT API reference¶

Introduction¶

See ThingsBoard API reference.

ThingsBoard API consists of two main parts: device API and 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.
  
  Timeseries 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 API¶

See MQTT Device API Reference.

Getting started¶

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. 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,
   "jsonKey": {
      "someNumber": 42,
      "someArray": [1,2,3],
      "someNestedObject": {"key": "value"}
   }
}

JSON value support¶

TODO: …

Protocol customization¶

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

Device MQTT Topic¶

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/$request_id	③ v1/devices/me/attributes/response/$request_id
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/$request_id	② v1/devices/me/rpc/request/$request_id
Client-Side RPC	① v1/devices/me/rpc/response/+	② v1/devices/me/rpc/request/$request_id	③ v1/devices/me/rpc/response/$request_id

Claiming device		① v1/devices/me/claim

Note: ①②③ The order in which topics are performed.