马上体验
解决方案
客户
案例
合作伙伴
关于我们
报价 文档 指南

ThingsBoard API参考

设备连接和服务器端API。

MQTT

入门

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’

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"
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
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"}
  }
}
resources/telemetry-data-as-array.json
 
[{"key1":"value1"}, {"key2":true}]
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
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"
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
 
{
  "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会话中进行。

resources/mqtt-js-attributes-request.sh
 
export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js
resources/mqtt-js-attributes-request.js
 
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()
})

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

通过服务端订阅属性

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

v1/devices/me/attributes

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

{"key1":"value1"}
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"
resources/mqtt-js-attributes-subscribe.sh
 
# 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会话中进行。

resources/mqtt-js-rpc-from-server.sh
 
export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js
resources/mqtt-js-rpc-from-server.js
 
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);
});

客户端

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

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

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

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

以下示例是用javascript基于mqtt.js编写的代码。

命令行示例不可用因为订阅和发布需要在同一mqtt会话中进行。

resources/mqtt-js-rpc-from-client.sh
 
export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-client.js
resources/mqtt-js-rpc-from-client.js
 
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());
});

声明设备

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

为了启动声明设备，请向以下主题发送PUBLISH消息：

v1/devices/me/claim

支持的数据格式为：

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

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

自定义协议

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

下一步

  • 入门指南 - 这些指南提供了ThingsBoard主要功能的快速概述。

  • 安装指南 - 了解如何在各种操作系统上安装ThingsBoard。

  • 数据看板 - 这些指南包含有关如何配置复杂的ThingsBoard仪表板的说明。

  • 数据处理 - 了解如何使用ThingsBoard规则引擎。

  • 数据分析 - 了解如何使用规则引擎执行基本的分析任务。

  • 硬件样品 - 了解如何将各种硬件平台连接到ThingsBoard。

  • 高级功能 - 了解高级ThingsBoard功能。

  • 开发指南 - 了解ThingsBoard中的贡献和开发。