Thingsboard API - MQTT API - 《Thingsboard 二次开发中文文档》

入门
Key-value格式
遥测上传API
属性API
RPC API
- 服务端
设备配置
自定义协议

入门

MQTT基础

MQTT是一种轻量级的发布-订阅消息传递协议，它可能最适合各种物联网设备。
你可以在此处找到有关MQTT的更多信息，ThingsBoard服务器支持QoS级别0（最多一次）和QoS级别1（至少一次）以及一组预定义主题的MQTT代理。

客户端

你可以在网上找到大量的MQTT客户端库，本文中的示例将基于Mosquitto和MQTT.js您可以使用我们的Hello World指南中的说明。

MQTT连接

我们将在本文中使用令牌凭据对进行设备访问，这些凭证稍后将称为$ACCESS_TOKEN应用程序需要发送用户名包含$ACCESS_TOKEN的MQTT CONNECT消息。
连接状态码说明：

0x00 连接成功 - 成功连接
0x04 连接失败 - 用户名或密码错误。
0x05 连接未授权 - -用户名包含无效的 $ACCESS_TOKEN。

Key-value格式

ThingsBoard支持以JSON格式的key-value字符串，值可以是string、bool、float、long或者二进制格式的序列化字符串；有关更多详细信息请参见协议自定义。
例如:

{
 "stringKey":"value1", 
 "booleanKey":true, 
 "doubleKey":42.0, 
 "longKey":73, 
 "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

遥测上传API

发布遥测数据到ThingsBoard服务端必须PUBLISH消息发送到下面主题：

v1/devices/me/telemetry

支持的最简单的数据格式是：

{"key1":"value1", "key2":"value2"}

或者

[{"key1":"value1"}, {"key2":"value2"}]

请注意 在这种情况下服务端时间戳将分配给上传的数据!
如果您的设备能够获得客户端时间戳，则可以使用以下格式：

{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

在上面的示例中我们假设“1451649600512”是具有毫秒精度的Unix时间戳。
例如：值’1451649600512’对应于’2016年1月1日星期五 12：00：00.512 GMT’

Mosquitto（resources/mosquitto-telemetry.sh）

# Publish data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-object.json"
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-array.json"
# Publish data as an object with timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"

MQTT.js(resources/mqtt-js-telemetry.sh)

# Publish data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data-as-object.json | mqtt pub -v -h "127.0.0.1" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
cat telemetry-data-as-array.json | mqtt pub -v -h "127.0.0.1" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s
# Publish data as an object with timestamp (server-side timestamp will be used)
cat telemetry-data-with-ts.json | mqtt pub -v -h "127.0.0.1" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s

telemetry-data-as-object.json(resources/telemetry-data-as-object.json)

{
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
  "someNumber": 42,
  "someArray": [1,2,3],
  "someNestedObject": {"key": "value"}
}
}

teltmetry-data-as-array.json(resources/telemetry-data-as-array.json)
```
[{"key1":"value1"}, {"key2":true}]
```

telemetry-data-with-ts.json(resources/telemetry-data-with-ts.json)

{
"ts": 1451649600512,
"values": {
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1, 2, 3],
    "someNestedObject": {
      "key": "value"
    }
  }
}
}

属性API

ThingsBoard属性API能够使设备具备如下功能

将客户端设备属性上传到服务端
从服务端请求客户端和共享属性
从服务端订阅共享属性

通过服务端发布客户端属性
通过ThingsBoard服务端发布客户端属性必须PUBLISH消息到下面主题:
v1/devices/me/attributes

mosquitto（resources/mosquitto-attributes-publish.sh）

# Publish client-side attributes update
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"

MQTT.js(resources/mqtt-js-attributes-publish.sh)

# Publish client-side attributes update
cat new-attributes-values.json | mqtt pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN' -s

resources/new-attributes-values.json(resources/new-attributes-values.json)
```
{
"attribute1": "value1",
"attribute2": true,
"attribute3": 42.0,
"attribute4": 73,
"attribute5": {
  "someNumber": 42,
  "someArray": [1,2,3],
  "someNestedObject": {"key": "value"}
}
}
```
通过服务端获取属性值
通过ThingsBoard服务端获取客户端属性或共享属性必须PUBLISH消息到下面主题:
```
v1/devices/me/attributes/request/$request_id
```
其中$request_id表示整数的请求标识符。
在发送带有请求的PUBLISH消息之前客户端需要订阅。
```
v1/devices/me/attributes/response/+
```
以下示例是用javascript基于mqtt.js编写的代码。
命令行示例不可用因为订阅和发布需要在同一mqtt会话中进行。

MQTT.js(resources/mqtt-js-attributes-request.sh)

export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js

mqtt-js-attributes-request.js（resources/mqtt-js-attributes-request.js） ```json var mqtt = require(‘mqtt’) var client = mqtt.connect(‘mqtt://127.0.0.1’,{ username: process.env.TOKEN })

client.on(‘connect’, function () { console.log(‘connected’) client.subscribe(‘v1/devices/me/attributes/response/+’) client.publish(‘v1/devices/me/attributes/request/1’, ‘{“clientKeys”:”attribute1,attribute2”, “sharedKeys”:”shared1,shared2”}’) })

client.on(‘message’, function (topic, message) { console.log(‘response.topic: ‘ + topic) console.log(‘response.body: ‘ + message.toString()) client.end() })


- Result([resources/attributes-response.json](https://raw.githubusercontent.com/thingsboard/thingsboard.github.io/master/docs/reference/resources/attributes-response.json))
```json
{"key1":"value1"}

请注意：客户端和共享设备属性键的交集是不好的做法！但是对于客户端、共享和服务端属性仍然可能具有相同的密钥。

通过服务端订阅属性

通过服务端订阅共享属性必须SUBSCRIBE消息到下面主题：

v1/devices/me/attributes

如果服务端组件（例如REST API或规则链）更改了共享属性时客户端就会收到对应属性值：

{"key1":"value1"}

mosquitto（resources/mosquitto-attributes-subscribe.sh）

# Subscribes to attribute updates
mosquitto_sub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"

MQTT.js

# Subscribes to attribute updates
mqtt sub -v "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN'

RPC API

服务端

客户端订阅服务端RPC命令必须SUBSCRIBE消息发送下面主题：

v1/devices/me/rpc/request/+

订阅后客户端会收到一条命令作为对相应主题的PUBLISH命令：

v1/devices/me/rpc/request/$request_id

$request_id表示请求的整型标识符。
客户端PUBLISH下面主题进行响应：

v1/devices/me/rpc/response/$request_id

以下示例是用javascript基于mqtt.js编写的代码。
命令行示例不可用因为订阅和发布需要在同一mqtt会话中进行。

MQTT.js（resources/mqtt-js-rpc-from-client.sh）

export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js

mqtt-js-rpc-from-server.js ```javascript var mqtt = require(‘mqtt’); var client = mqtt.connect(‘mqtt://127.0.0.1’,{ username: process.env.TOKEN });

client.on(‘connect’, function () { console.log(‘connected’); client.subscribe(‘v1/devices/me/rpc/request/+’) });

client.on(‘message’, function (topic, message) { console.log(‘request.topic: ‘ + topic); console.log(‘request.body: ‘ + message.toString()); var requestId = topic.slice(‘v1/devices/me/rpc/request/‘.length); //client acts as an echo service client.publish(‘v1/devices/me/rpc/response/‘ + requestId, message); });

<a name="5AOOo"></a>
### 客户端
将RPC命令发送到服务端必须PUBLISH消息发送到下面主题：
```powershell
v1/devices/me/rpc/request/$request_id

$request_id表示请求的整型标识符，服务端必须发布到下面主题：

v1/devices/me/rpc/response/$request_id

以下示例是用javascript基于mqtt.js编写的代码。
命令行示例不可用因为订阅和发布需要在同一mqtt会话中进行。

MQTT.js（resources/mqtt-js-rpc-from-client.sh）

export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js

mqtt-js-rpc-from-server.js ```javascript var mqtt = require(‘mqtt’); var client = mqtt.connect(‘mqtt://127.0.0.1’, { username: process.env.TOKEN });

client.on(‘connect’, function () { console.log(‘connected’); client.subscribe(‘v1/devices/me/rpc/response/+’); var requestId = 1; var request = { “method”: “getTime”, “params”: {} }; client.publish(‘v1/devices/me/rpc/request/‘ + requestId, JSON.stringify(request)); });

client.on(‘message’, function (topic, message) { console.log(‘response.topic: ‘ + topic); console.log(‘response.body: ‘ + message.toString()); });


<a name="F0tcx"></a>
## 声明设备
请参阅相应的文章以获取有关[声明设备](http://www.ithingsboard.com/docs/user-guide/claiming-devices)功能的更多信息。<br />为了启动声明设备，请向以下主题发送PUBLISH消息：
```powershell
v1/devices/me/claim

支持的数据格式为：

{"secretKey":"value", "durationMs":60000}

注意： 以上字段是可选的如果未指定secretKey则使用空字符串作为默认值；device.claim.duration毫秒未指定时系统参数device.claim.duration则使用(/etc/thingsboard/conf/thingsboard.yml)。

设备配置

请参阅相应的文章以获取有关设备供应功能的更多信息。
为了启动设备供应，请发送供应请求到以下主题：

/provision

另外，您应该将username或clientId设置为Provision。
支持的数据格式为：

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

自定义协议

通过更改相应的模块可以针对特定用例完全定制MQTT传输。

MQTT API

入门