- 客户端库配置
- 认证方式
- Key-value 格式
- 遥测上传API
- Attributes API
- JSON value support
- RPC API
- Claiming devices
- Device provisioning
- Firmware API
- 协议自定义
- 下一步
CoAP是一种面向受限物联网设备的轻量级、基于UDP的协议。虽采用类似HTTP的请求-响应模型，CoAP针对低功耗、低带宽网络进行了优化。更多CoAP信息请见此处。
CoAP Observe选项支持订阅资源并在资源变更时接收通知。
ThingsBoard服务节点充当CoAP服务器，同时支持常规和Observe请求。
客户端库配置
不同平台和语言有多种CoAP客户端库可用。
本指南示例基于命令行CoAP客户端CoAP cli。
安装CoAP CLI（Linux/macOS）
1
npm install coap-cli -g
注意：CoAP CLI不支持查询参数。若需查询参数，请使用coap-client。
安装coap-client
- Ubuntu 20.04+
1
sudo apt install libcoap2-bin
- Ubuntu 18.04
1
sudo apt install libcoap1-bin
认证方式
ThingsBoard支持两种认证方式以保护CoAP连接。
支持的方式：
- Access token。每次CoAP请求的路径参数中包含唯一设备访问令牌。
- X.509 certificates。使用数字证书认证设备，基于公钥基础设施（PKI）建立安全通信。
本指南示例采用基于access token的认证。
错误码及原因：
- 4.00 Bad Request - URL、参数或载荷无效
- 4.01 Unauthorized - access token无效
- 4.04 Not Found - 请求的资源不存在
Key-value 格式
默认情况下，ThingsBoard 支持 JSON 形式的 key-value 内容。Key 始终为字符串，value 可为 string、boolean、double、long 或 JSON。 例如：
1
2
3
4
5
6
7
8
9
10
11
{
"stringKey":"value1",
"booleanKey":true,
"doubleKey":42.0,
"longKey":73,
"jsonKey": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
也可通过Protocol Buffers发送数据。 详见设备配置文档中的CoAP传输类型配置章节。
也可使用自定义二进制格式或序列化框架。详见协议自定义。
遥测上传API
向ThingsBoard服务节点发布遥测数据时，发送POST请求。
首先选择认证方式：
支持的最简数据格式为：
1
{"key1":"value1", "key2":"value2"}
or
1
[{"key1":"value1"}, {"key2":"value2"}]
请注意
在此情况下，将使用服务器端时间戳作为上传数据的时间戳！
若设备能获取客户端时间戳，可使用以下格式：
1
{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}
其中 1451649600512 为毫秒精度的Unix时间戳。例如 ‘1451649600512’ 对应 ‘Fri, 01 Jan 2016 12:00:00.512 GMT’。
示例
以下为发布不同类型遥测数据的命令示例。
⚠️ 请勿忘记替换
$ACCESS_TOKEN为您的设备访问令牌。
示例1。
以对象形式发布无时间戳数据（将使用服务器端时间戳），数据来自telemetry-data-as-object.json文件。
|
JSON文件内容：
1
2
3
4
5
6
7
8
9
10
11
{
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
示例2。
以对象数组形式发布无时间戳数据（将使用服务器端时间戳），数据来自telemetry-data-as-array.json文件。
|
JSON文件内容：
1
[{"key1":"value1"}, {"key2":true}]
示例3。
以带时间戳的对象形式发布数据（将使用遥测时间戳），数据来自telemetry-data-with-ts.json文件。
|
JSON文件内容：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"ts": 1451649600512,
"values": {
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
"someNumber": 42,
"someArray": [1, 2, 3],
"someNestedObject": {
"key": "value"
}
}
}
}
Attributes API
ThingsBoard属性API允许设备：
向服务器发布属性更新
为将客户端设备属性发布至ThingsBoard服务节点，发送POST请求。
首先选择认证方式：
向以下 URL 发送 POST 请求：
使用 new-attributes-values.json 文件中的数据发布客户端属性更新。 「new-attributes-values.json」 文件内容： 执行命令： |
向以下 URL 发送 POST 请求： Publish client-side attributes update using data from new-attributes-values.json file. The content of the “new-attributes-values.json” file: 执行命令： |
从服务器请求属性值
为从ThingsBoard服务节点请求客户端或共享设备属性，发送GET请求。
首先选择认证方式：
向以下 URL 发送 GET 请求：
注意： 此示例使用 coap-client 而非 CoAP cli，因 CoAP cli 不支持查询参数。请参阅 客户端库配置。 执行命令： |
向以下 URL 发送 GET 请求： 注意： 此示例使用 coap-client 而非 CoAP cli，因 CoAP cli 不支持查询参数。请参阅 客户端库配置。 执行命令： |
结果：
1
{"client":{"attribute1":"value1","attribute2":true}}
请注意：
客户端与共享设备属性键存在交集是不佳实践！ 但仍可为client、shared甚至server-side属性使用相同键。
订阅来自服务器的属性更新
为订阅共享设备属性变更，发送带Observe选项的GET请求。
首先选择认证方式：
向以下 URL 发送带 Observe 选项的 GET 请求：
当共享属性被任一服务端组件（REST API 或规则链）修改后，客户端将收到如下更新： 执行命令： |
向以下 URL 发送带 Observe 选项的 GET 请求： 当共享属性被任一服务端组件（REST API 或规则链）修改后，客户端将收到如下更新： 执行命令： |
结果：
1
{"client":{"attribute1":"value1","attribute2":true}}
JSON value support
我们为遥测和属性 API 增加了 JSON 数据结构支持，以便简化设备配置操作。 JSON 支持允许从设备上传数据，并将嵌套对象推送到设备。 可将一份配置 JSON 存为共享属性并推送到设备，也可在规则引擎中处理 JSON 数据并触发告警等。
因此，该改进在ThingsBoard 存储数据时减少了数据库操作次数。 例如，「temperature」和「humidity」会作为独立行存储在 SQL 或 NoSQL 数据库中，以便高效聚合用于可视化。 由于 JSON 数据无需聚合，可将全部内容存为一行，而无需为每个配置项单独成行。 在某些环境中，通过在单个 JSON 中聚合多个参数，可将数据库操作次数减少 10 倍以上。
通过该 视频 了解更多 JSON 值支持内容。
RPC API
Server-side RPC
为订阅来自服务器的RPC命令，发送带observe标志的GET请求。
首先选择认证方式：
向以下 URL 发送带 observe 标志的 GET 请求：
订阅后，客户端将接收 RPC 请求。RPC 请求体示例：
要回复 RPC 请求，请向以下 URL 发送 POST 请求：
示例
「 「
将收到设备响应：      |
向以下 URL 发送带 observe 标志的 GET 请求： 订阅后，客户端将接收 RPC 请求。RPC 请求体示例：
要回复 RPC 请求，请向以下 URL 发送 POST 请求：
Example
「 「
  |
Client-side RPC
为向服务器发送RPC命令，发送POST请求。
首先选择认证方式：
向以下 URL 发送 POST 请求：
请求体和响应体均需为有效 JSON 文档，文档内容取决于处理请求的规则节点。
     |
向以下 URL 发送 POST 请求： 请求体和响应体均需为有效 JSON 文档，文档内容取决于处理请求的规则节点。
  |
Claiming devices
设备认领功能允许最终用户在设备部署并连接至ThingsBoard后，安全地将设备关联到其账户。 设备认领流程及支持场景的详细说明请参见认领设备文档。
为启动设备认领，发送POST请求。
首先选择认证方式：
支持的数据格式为：
1
{"secretKey":"value", "durationMs":60000}
请注意
上述字段均为可选。secretKey未指定时，默认使用空字符串。 durationMs未指定时，使用系统参数device.claim.duration（位于/etc/thingsboard/conf/thingsboard.yml）。
Device provisioning
设备预配置支持设备动态注册，无需在ThingsBoard界面手动创建。 预配置流程及支持场景的详细说明请参见设备预配置文档。
预配置请求
为启动设备预配置，向以下URL发送POST请求：
1
coap://coap.eu.thingsboard.cloud/api/v1/provision
请求载荷
预配置请求须使用以下JSON格式：
1
2
3
4
5
{
"deviceName": "DEVICE_NAME",
"provisionDeviceKey": "u7piawkboq8v32dmcmpp",
"provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}
载荷字段
- deviceName — 待预配置设备的名称。
- provisionDeviceKey — ThingsBoard中配置的预配置密钥。
- provisionDeviceSecret — 与预配置密钥关联的预配置密钥。
若提供的凭据有效，ThingsBoard将自动创建设备（若不存在）并返回设备凭据，使设备可与平台通信。
Firmware API
选择认证方式：
CoAP 客户端需向以下地址发起 GET 请求： 其中
|
CoAP 客户端需向以下地址发起 GET 请求： 其中
|
协议自定义
可通过修改对应模块，针对特定用例完全自定义CoAP传输。