MQTT Gateway API Reference

Introduction
Prerequisites
Device Connect API
Device Disconnect API
Attributes API
Telemetry upload API
RPC API
- Server-side RPC
Claiming devices API
Protocol customization
Troubleshooting
Next steps

Introduction

A Gateway in ThingsBoard is a special type of device that acts as a bridge between external devices and the platform. It maintains a single MQTT connection to ThingsBoard while proxying data for many physical devices behind it.

The Gateway itself is also a normal ThingsBoard device. It can use the standard MQTT Device API to:

Report its own telemetry and attributes.
Receive configuration updates.
Execute RPC commands.

The API describes the Gateway-specific MQTT topics and payload formats. Also, the API is used by the open-source ThingsBoard IoT Gateway.

Prerequisites

In order to try examples from this documentation, you need to install an MQTT client tool. You can use the following instructions to install mosquitto_pub and mosquitto_sub command-line tools.

Device Connect API

Use this API to inform ThingsBoard that a device behind the Gateway is now connected and ready to exchange data.

Topic:

v1/gateway/connect

Payload:

{"device": "Device A", "type": "Sensor A"}

device - required. The device name in ThingsBoard.
type – optional. Name of the device profile. If omitted, the default device profile is used.

Behavior:

If a device with the given name does not exist, ThingsBoard creates it automatically.
If the device profile name is provided and the profile does not exist, ThingsBoard creates it automatically.
Once connected, ThingsBoard routes the following events for this device through the Gateway:
- Updates to shared attributes.
- RPC commands.

Examples

Don’t forget to replace demo.thingsboard.io with your host and $ACCESS_TOKEN with your gateway’s access token. In this example, the hostname references live demo server.

Example 1. Connect a device.

In order to inform ThingsBoard that device is connected to the Gateway, one needs to publish following message:

mosquitto_pub -h "demo.thingsboard.io" -t "v1/gateway/connect" -u "$ACCESS_TOKEN" -m '{"device": "Device A"}'

Example 2. Connect a device with a specific device profile.

In order to inform ThingsBoard that device is connected to the Gateway with a specific device profile, one needs to publish following message:

mosquitto_pub -h "demo.thingsboard.io" -t "v1/gateway/connect" -u "$ACCESS_TOKEN" -m '{"device": "Device A", "type": "Sensor A"}'

Device Disconnect API

Use this API to inform ThingsBoard that a device behind the Gateway is no longer active.

Topic:

v1/gateway/disconnect

Payload:

{"device": "Device A"}

Behavior:

If the device with the given name does not exist, ThingsBoard ignores the message.
After processing this message, ThingsBoard stops sending attribute and RPC updates for that device to the Gateway.

Example

Don’t forget to replace demo.thingsboard.io with your host and $ACCESS_TOKEN with your gateway’s access token. In this example, the hostname references live demo server. Also, make sure that the device is connected before disconnecting it.

In order to inform ThingsBoard that device is disconnected from the Gateway, one needs to publish following message:

mosquitto_pub -h "demo.thingsboard.io" -t "v1/gateway/disconnect" -u "$ACCESS_TOKEN" -m '{"device": "Device A"}'

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 ThingsBoard platform.
Subscribe to shared device attributes from the ThingsBoard platform.

Publish attribute to the ThingsBoard platform

Use this topic to publish client-side device attributes to the ThingsBoard platform. All attributes in the payload are stored as client-side attributes for the corresponding devices.

Topic:

v1/gateway/attributes

Payload:

{
  "Device A": {
    "attribute1": "value1",
    "attribute2": 42
  },
  "Device B": {
    "attribute1": "value1",
    "attribute2": 42
  }
}

Behavior:

If the device with the given name does not exist, ThingsBoard creates it automatically with default profile name.
If the attribute does not exist, it is created.
If the attribute already exists, its value is updated.

Example

Don’t forget to replace demo.thingsboard.io with your host and $ACCESS_TOKEN with your gateway’s access token. In this example, the hostname references live demo server.

In order to publish client-side device attributes to ThingsBoard platform, one needs to publish following message:

mosquitto_pub -h "demo.thingsboard.io" -t "v1/gateway/attributes" -u "$ACCESS_TOKEN" -m '{"Device A": { "fw_version": "1.0", "battery": 87 }}'

Request attribute values from the ThingsBoard platform

Use this API to request client-side or shared device attributes from ThingsBoard platform. Make attention that you need to subscribe to the response topic first in order to receive the response.

Subscribe topic:

v1/gateway/attributes/response

Publish topic:

v1/gateway/attributes/request

Payload:

{
  "id": $request_id,
  "device": "Device A",
  "client": ["key1", "key2"],
  "shared": ["key3", "key4"]
}

Fields:

id – required. Your integer request identifier.
device – required. The device name in ThingsBoard.
client – optional. An array of client-side attribute keys to request.
shared – optional. An array of shared attribute keys to request.

Use this topic to subscribe to shared device attribute changes. Take attention that you need to subscribe to the topic first in order to receive updates.

Subscribe topic:

v1/gateway/attributes

Response message format:

{
  "device": "Device A",
  "data": {
    "attribute1": "value1",
    "attribute2": 42
  }
}

Fields:

device – the device name in ThingsBoard.
data – map of updated shared attributes.

Telemetry upload API

Use this API to publish telemetry for one or more devices in a single MQTT message.

Topic:

v1/gateway/telemetry

Payload:

{
  "Device A": [
    {
      "ts": 1483228800000,
      "values": {
        "temperature": 42,
        "humidity": 80
      }
    },
    {
      "ts": 1483228801000,
      "values": {
        "temperature": 43,
        "humidity": 82
      }
    }
  ],
  "Device B": [
    {
      "ts": 1483228800000,
      "values": {
        "temperature": 42,
        "humidity": 80
      }
    }
  ]
}

Fields:

device – required. The device name in ThingsBoard.
ts – Unix timestamp in milliseconds.
values – required. Key-value map of telemetry fields (e.g., temperature, humidity).

Behavior:

If the device with the given name does not exist, ThingsBoard creates it automatically with default profile name.
If the telemetry keys do not exist, they are created.
Telemetry data is stored with the provided timestamps.

Example

Don’t forget to replace demo.thingsboard.io with your host and $ACCESS_TOKEN with your gateway’s access token. In this example, the hostname references live demo server.

In order to publish device telemetry to ThingsBoard platform, one needs to publish following message:

mosquitto_pub -h "demo.thingsboard.io" -t "v1/gateway/telemetry" -u "$ACCESS_TOKEN" -m '{"Device A": [{"ts": 1700000000000, "values": {"temperature": 23.5, "humidity": 61 }}]}'

RPC API

Server-side RPC

Use this API to receive and respond to RPC commands from ThingsBoard for devices behind the Gateway.

Subscribe topic:

v1/gateway/rpc

Request message format:

{"device": "Device A", "data": {"id": $request_id, "method": "toggle_gpio", "params": {"pin": 1}}}

Response topic:

v1/gateway/rpc

Response message format:

{"device": "Device A", "id": $request_id, "data": {"success": true}}

Fields:

device – the device name in ThingsBoard.
id – your integer request identifier.
data – response payload.

You need to subscribe to the request topic first in order to receive RPC commands. After processing the RPC command, you can publish the response message to the response topic.

Claiming devices API

ThingsBoard supports a claiming mechanism that allows end users to take ownership of pre-provisioned devices. For conceptual details, see Claiming devices guide.

Topic:

v1/gateway/claim

Payload:

{
  "Device A": {
    "secretKey": "value_A",
    "durationMs": 60000
  },
  "Device B": {
    "secretKey": "value_B",
    "durationMs": 60000
  }
}

Per-device parameters:

secretKey – optional. The secret key assigned to the device for claiming. If omitted, an empty string is used.
durationMs – optional. Claiming duration in milliseconds. If omitted, the system parameter device.claim.duration is used (in the file /etc/thingsboard/conf/thingsboard.yml).

Example

In order to inform ThingsBoard platform to start claiming process for devices, one needs to publish following message:

mosquitto_pub -h "demo.thingsboard.io" -t "v1/gateway/claim" -u "$ACCESS_TOKEN" -m '{"Device A": {"secretKey": "mySecret", "durationMs": 60000}}'

Protocol customization

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

Troubleshooting

Commands mosquitto_pub or mosquitto_sub doesn’t execute?

MQTTLinux or macOS

MQTTWindows

Install mqtt client for Ubuntu:

sudo apt-get install mosquitto-clients

Install cURL for macOS:

brew install mosquitto-clients

Replace $ACCESS_TOKEN with corresponding value.

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

For example, $ACCESS_TOKEN is ABC123:

mosquitto_pub -d -q 1 -h "mqtt.eu.thingsboard.cloud" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

Successful output should look similar to this one:

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

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.

Press the Win + X, then select "System". Then click on the "System" page; — Press the Win + X, then select “System”. Then click on the “System” page;

Navigate to the "About" section, then click "Advanced system settings"; — 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 “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 “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; — 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; — Click “OK” button to save changes in the environment variables;

Finally, click "OK" button to apply all changes in the system properties. — Finally, click “OK” button to apply all changes in the system properties.

Open the Terminal and replace $ACCESS_TOKEN with corresponding value.

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

For example, $ACCESS_TOKEN is ABC123:

mosquitto_pub -d -q 1 -h "mqtt.eu.thingsboard.cloud" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

Successful output should look similar to this one:

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

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.

MQTT Gateway API Reference

Introduction

Prerequisites

Device Connect API

Device Disconnect API

Attributes API

Publish attribute to the ThingsBoard platform

Request attribute values from the ThingsBoard platform

Subscribe to attribute updates from the ThingsBoard platform

Telemetry upload API

RPC API

Server-side RPC

Claiming devices API

Protocol customization

Troubleshooting

Next steps