MQTT Gateway API Reference

On this page

MQTT Gateway API Reference

Introduction

The Gateway is a special type of device in IoT Hub that is able to act as a bridge between external devices connected to different systems and IoT Hub. Gateway API provides the ability to exchange data between multiple devices and the platform using single MQTT connection. The Gateway also acts as a IoT Hub device and can leverage existing MQTT Device API to report stats, receive configuration updates and much more.

The API listed below is used by IoT Hub open-source IoT Gateway.

Basic MQTT API

Please refer to generic MQTT Device API to get information about data format, authentication options, etc.

Device Connect API

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

1
2

Topic: v1/gateway/connect
Message: {"device":"Device A"}

where Device A is your device name.

Once received, IoT Hub will lookup or create a device with the name specified. Also, IoT Hub will publish messages about new attribute updates and RPC commands for a particular device to this Gateway.

Device Disconnect API

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

1
2

Topic: v1/gateway/disconnect
Message: {"device":"Device A"}

where Device A is your device name.

Once received, IoT Hub will no longer publish updates for this particular device to this Gateway.

Attributes API

IoT Hub 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 IoT Hub server node, send PUBLISH message to the following topic:

1
2

Topic: v1/gateway/attributes
Message: {"Device A":{"attribute1":"value1", "attribute2": 42}, "Device B":{"attribute1":"value1", "attribute2": 42}}

where Device A and Device B are your device names, attribute1 and attribute2 are attribute keys.

Request attribute values from the server

In order to request client-side or shared device attributes to IoT Hub server node, send PUBLISH message to the following topic:

1
2

Topic: v1/gateway/attributes/request
Message: {"id": $request_id, "device": "Device A", "client": true, "key": "attribute1"}

where $request_id is your integer request identifier, Device A is your device name, client identifies a client or shared attribute scope and key is the attribute key.

Before sending PUBLISH message with the request, client need to subscribe to

1

Topic: v1/gateway/attributes/response

and expect messages with result in the following format:

1

Message: {"id": $request_id, "device": "Device A", "value": "value1"}
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/gateway/attributes

and expect messages with result in the following format:

1

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

Telemetry upload API

In order to publish device telemetry to IoT Hub server node, send PUBLISH message to the following topic:

1

Topic: v1/gateway/telemetry

Message:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

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

where Device A and Device B are your device names, temperature and humidity are telemetry keys and ts is unix timestamp in milliseconds.

RPC API

Server-side RPC

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

1

v1/gateway/rpc

and expect messages with individual commands in the following format:

1

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

Once command is processed by device, gateway can send commands back using following format:

1

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

where $request_id is your integer request identifier, Device A is your device name and method is your RPC method name.

Claiming devices API

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

Topic: v1/gateway/claim

Message:

1
2
3
4
5
6
7
8
9
10

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

where Device A and Device B are your device names, secretKey and durationMs are optional keys. 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).

Protocol customization

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

Next steps