MQTT Gateway API

A Gateway in ThingsBoard is a special device that acts as a bridge, maintaining a single MQTT connection to ThingsBoard Edge while proxying data for multiple physical devices behind it. The gateway itself is also a standard ThingsBoard device and can use the regular MQTT Device API to publish its own telemetry and attributes.

This API is used by the open-source ThingsBoard IoT Gateway.

The examples in this guide use mosquitto_pub and mosquitto_sub from the Mosquitto package.

sudo apt-get install mosquitto-clients

brew install mosquitto

Set up environment variables used in all examples:

export ACCESS_TOKEN=your_gateway_access_token
export EDGE_HOST=your_edge_host_or_ip

Inform ThingsBoard Edge that a device behind the Gateway is 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. Device profile name. Defaults to default if omitted.

Behavior:

• If the device does not exist, ThingsBoard creates it automatically.
• If the profile name is provided and does not exist, ThingsBoard creates it automatically.
• Once connected, ThingsBoard routes shared attribute updates and RPC commands for this device through the Gateway.

Example 1. Connect a device:

mosquitto_pub -h "$EDGE_HOST" -t "v1/gateway/connect" \
  -u "$ACCESS_TOKEN" -m '{"device": "Device A"}'

Example 2. Connect a device with a specific profile:

mosquitto_pub -h "$EDGE_HOST" -t "v1/gateway/connect" \
  -u "$ACCESS_TOKEN" -m '{"device": "Device A", "type": "Sensor A"}'

Inform ThingsBoard Edge that a device behind the Gateway is no longer active.

Topic: v1/gateway/disconnect

Payload:

{"device": "Device A"}

Behavior:

• If the device does not exist, ThingsBoard ignores the message.
• After processing, ThingsBoard stops routing attribute updates and RPC commands for that device through the Gateway.

Example:

mosquitto_pub -h "$EDGE_HOST" -t "v1/gateway/disconnect" \
  -u "$ACCESS_TOKEN" -m '{"device": "Device A"}'

The Gateway can publish client-side attributes, request attribute values, and subscribe to shared attribute updates for devices behind it. See Working with attributes for attribute type details.

Upload client-side attributes for one or more devices. All keys in the payload are stored as client-side attributes.

Topic: v1/gateway/attributes

Payload:

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

Behavior:

• If the device does not exist, ThingsBoard creates it with the default profile.
• New attribute keys are created; existing keys are updated.

Example:

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

Subscribe to the response topic first, then publish the request.

Subscribe topic: v1/gateway/attributes/response

Publish topic: v1/gateway/attributes/request

Payload:

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

• id — required. Integer request identifier. The response includes the same id.
• device — required. The device name in ThingsBoard.
• client — optional. Client-side attribute keys to retrieve.
• shared — optional. Shared attribute keys to retrieve.

Subscribe to receive shared attribute changes pushed by ThingsBoard for devices behind the Gateway.

Subscribe topic: v1/gateway/attributes

Message format:

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

• device — the device name in ThingsBoard.
• data — map of updated shared attribute keys and values.

Publish time-series data for one or more devices in a single 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}}
  ]
}

• ts — optional. Unix timestamp in milliseconds. If omitted, the server assigns the current time.
• values — required. Key-value map of telemetry fields.

Behavior:

• If the device does not exist, ThingsBoard creates it with the default profile.
• New telemetry keys are created; data is stored at the provided timestamps.

Example:

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

Receive RPC commands from ThingsBoard for devices behind the Gateway and publish responses.

Subscribe topic: v1/gateway/rpc

Request message format:

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

Response topic: v1/gateway/rpc

Response message format:

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

• device — the device name in ThingsBoard.
• id — the request identifier. Must match the id from the request.
• data — response payload.

Initiate the claiming process so end users can take ownership of pre-provisioned devices.

Topic: v1/gateway/claim

Payload:

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

Per-device parameters:

• secretKey — optional. Secret key assigned to the device. Defaults to an empty string.
• durationMs — optional. Claiming window in milliseconds. Defaults to the device.claim.duration system parameter.

Example:

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

The MQTT transport can be fully customized for specific use cases by modifying the corresponding transport module.