MQTT Device API Reference

入门
Key-value格式
遥测上传API
属性API
支持JSON
RPC API
- 服务端
- 客户端
声明设备
设备预配置
硬件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
MQTT.js
telemetry-data-as-object.json
telemetry-data-as-array.json
telemetry-data-with-ts.json

# Publish data as an object without timestamp (server-side timestamp will be used). Replace $ACCESS_TOKEN with corresponding value.
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m "{"temperature":42}"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "ABC123" -m "{"temperature":42}"

# Publish data as an object without timestamp (server-side timestamp will be used) using data from file. Replace $ACCESS_TOKEN with corresponding value.
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-object.json"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "ABC123" -f "telemetry-data-as-object.json"

# Publish data as an array of objects without timestamp (server-side timestamp will be used)  using data from file. Replace $ACCESS_TOKEN with corresponding value.
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-array.json"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "ABC123" -f "telemetry-data-as-array.json"

# Publish data as an object with timestamp (telemetry timestamp will be used)  using data from file. Replace $ACCESS_TOKEN with corresponding value.
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u "ABC123" -f "telemetry-data-with-ts.json"

# Publish data as an object without timestamp (server-side timestamp will be used). Replace $ACCESS_TOKEN with corresponding value.
mqtt pub -v -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -m "{"temperature":42}"
# For example, $ACCESS_TOKEN is ABC123:
mqtt pub -v -q 1 -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u 'ABC123' -m "{"temperature":42}"

# Publish data as an object without timestamp (server-side timestamp will be used). Replace $ACCESS_TOKEN with corresponding value.
cat telemetry-data-as-object.json | mqtt pub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m ""
# For example, $ACCESS_TOKEN is ABC123:
cat telemetry-data-as-object.json | mqtt pub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u 'ABC123' -s -m ""

# Publish data as an array of objects without timestamp (server-side timestamp will be used). Replace $ACCESS_TOKEN with corresponding value.
cat telemetry-data-as-array.json | mqtt pub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m ""
# For example, $ACCESS_TOKEN is ABC123:
cat telemetry-data-as-array.json | mqtt pub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u 'ABC123' -s -m ""

# Publish data as an object with timestamp (telemetry timestamp will be used). Replace $ACCESS_TOKEN with corresponding value.
cat telemetry-data-with-ts.json | mqtt pub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m ""
# For example, $ACCESS_TOKEN is ABC123:
cat telemetry-data-with-ts.json | mqtt pub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/telemetry" -u 'ABC123' -s -m ""

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

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

{
  "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
MQTT.js
new-attributes-values.json

# Publish client-side attributes update. Replace $ACCESS_TOKEN with corresponding value.
mosquitto_pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "ABC123" -m "{"attribute1": "value1", "attribute2": true}"

# Publish client-side attributes update from file. Replace $ACCESS_TOKEN with corresponding value.
mosquitto_pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "ABC123" -f "new-attributes-values.json"

# Publish client-side attributes update. Replace $ACCESS_TOKEN with corresponding value.
cat new-attributes-values.json | mqtt pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN' -s -m ""
# For example, $ACCESS_TOKEN is ABC123:
cat new-attributes-values.json | mqtt pub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u 'ABC123' -s -m ""

{
  "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会话中进行。

替换$ACCESS_TOKEN为设备的访问令牌

MQTT.js
mqtt-js-attributes-request.js
Result

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

var mqtt = require('mqtt')
var client  = mqtt.connect('mqtt://thingsboard.cloud',{
    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()
})

{"client":{"attribute1":"value1","attribute2":true}}

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

通过服务端订阅属性

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

v1/devices/me/attributes

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

{"key1":"value1"}

Mosquitto
MQTT.js

# Subscribes to attribute updates. Replace $ACCESS_TOKEN with corresponding value.
mosquitto_sub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"
# For example, $ACCESS_TOKEN is ABC123:
mosquitto_sub -d -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u "ABC123"

# Subscribes to attribute updates. Replace $ACCESS_TOKEN with corresponding value.
mqtt sub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN'
# For example, $ACCESS_TOKEN is ABC123:
mqtt sub -v -h "mqtt.thingsboard.cloud" -t "v1/devices/me/attributes" -u 'ABC123'

支持JSON

We added support of JSON data structures to telemetry and attributes API to simplify work with device configuration. JSON support allows you to both upload from the device, and push to device nested objects. You can store one configuration JSON as a shared attribute and push it to the device. You can also process the JSON data in the rule engine and raise alarms, etc.

Therefore, this improvement minimizes the number of Database operations when ThingsBoard stores the data. For example, “temperature” and “humidity” would be stored as separate rows in SQL or NoSQL databases in order to efficiently aggregate this data for visualization. Since there is no need to aggregate JSON data, we can store all the content as one row instead of separate rows for each configuration item. In some of our environments, it is possible to decrease the number of database operations more than 10 times by aggregating multiple parameters within one JSON.

Learn more about JSON value support with the video.

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会话中进行。

替换$ACCESS_TOKEN为设备的访问令牌

使用RPC debug terminal在仪表板调试
订阅服务器RPC命令
请求”connect”发送到设备
收到设备的响应

Subscribe to RPC commands from the server

Send an RPC request "connect" to the device

You should receive a response from the device

MQTT.js
mqtt-js-rpc-from-server.js

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

var mqtt = require('mqtt');
var client  = mqtt.connect('mqtt://thingsboard.cloud',{
    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);
});

如果你的MQTT设备是网关则Thingsboard将发送服务器端RPC（通知）了解已配置设备实体的更改。
你的MQTT网关设备将收到删除或重命名设备的服务RPC解决事件。

客户端

将RPC命令发送到服务端必须PUBLISH消息发送到下面主题：

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

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

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

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

替换$ACCESS_TOKEN为设备的访问令牌

在规则链中添加两个节点”script”和”rpc call reply”
在script中输入函数：

return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};

将请求发送到服务器
收到服务器的响应

Add two nodes to the Rule Chain: "script" and "rpc call reply"

In the script node enter the function: return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};

You should receive a response from the server

example.sh
mqtt-js-rpc-from-client.js

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

var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://thingsboard.cloud', {
    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());
});

声明设备

请参阅相应的文章以获取有关声明设备功能的更多信息。

启动声明设备请将POST请求发送到以下URL：

v1/devices/me/claim

The supported data format is:

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

请注意上述字段是可选的如果未指定secretKey则使用空字符串作为默认值。
如果未指定durationms则使用系统参数device.claim.duration（在文件/etc/etting/themings/conf/conf/thexboard.yml中使用）。

设备预配置

请参阅相应的文章并获取有关[设备供应]Device provisioning功能的更多信息。

启动设备配置请将发布请求发送到以下URL：

/provision

将username或clientId设为provision。

支持数据格式如下：

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

硬件API

当Thingsboard通过HTTP启动固件更新时它会设置FW_TITLE，FW_VERSION，FW_CHECKSUM，FW_CHECKSUM_ALGORITHM共享属性。

要接收共享属性更新该设备必须获取请求。

v1/devices/me/attributes/response/+

说明

+是通配符。

当MQTT设备收到FW_TITLE和FW_Version共享属性的更新时，必须它将发布消息发送到

v2/fw/request/${requestId}/chunk/${chunkIndex} 

说明

${requestId} - 与固件更新相对应的数字每个固件更新${requestId}必须不同。 ${chunkIndex} - 与固件块索引相对应的数字${chunkID}是从0开始计数。 MQTT payload为字节中固件块的大小。

对于每个新的固件更新需要更改请求ID并订阅

v2/fw/response/+/chunk/+

说明

+是通配符。

自定义协议

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

下一步

入门指南 - 快速学习ThingsBoard相关功能。
可视化 - 学习如何配置复杂的ThingsBoard仪表板说明。
数据处理 - 学习如何使用ThingsBoard规则引擎。
数据分析 - 学习如何使用规则引擎执行基本的分析任务。
硬件样品 - 学习如何将各种硬件平台连接到ThingsBoard。
高级功能 - 学习高级ThingsBoard功能。

本页目录

MQTT Device API Reference

入门

MQTT基础

客户端

MQTT连接

Key-value格式

遥测上传API

属性API

通过服务端发布客户端属性

通过服务端获取属性值

通过服务端订阅属性

支持JSON

RPC API

服务端

客户端

声明设备

设备预配置

硬件API

自定义协议

下一步