- Introduction
- Basic MQTT API
- Device Connect API
- Device Disconnect API
- Attributes API
- Telemetry upload API
- RPC API
- Claiming devices API
- Protocol customization
- Next steps
Introduction
The Gateway is a special type of device in ThingsBoard that is able to act as a bridge between external devices connected to different systems and ThingsBoard. Gateway API provides the ability to exchange data between multiple devices and the platform using single MQTT connection. The Gateway also acts as a ThingsBoard device and can leverage existing MQTT Device API to report stats, receive configuration updates and much more.
The API listed below is used by ThingsBoard 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 ThingsBoard 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, ThingsBoard will lookup or create a device with the name specified. Also, ThingsBoard will publish messages about new attribute updates and RPC commands for a particular device to this Gateway.
Device Disconnect API
In order to inform ThingsBoard 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, ThingsBoard will no longer publish updates for this particular device to this Gateway.
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
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 ThingsBoard 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 ThingsBoard 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
-
入门指南 - 快速学习ThingsBoard相关功能。
-
安装指南 - 学习如何在各种操作系统上安装ThingsBoard。
-
可 视 化 - 学习如何配置复杂的ThingsBoard仪表板说明。
-
数据处理 - 学习如何使用ThingsBoard规则引擎。
-
数据分析 - 学习如何使用规则引擎执行基本的分析任务。
-
硬件样品 - 学习如何将各种硬件平台连接到ThingsBoard。
-
高级功能 - 学习高级ThingsBoard功能。