入门
CoAP基础
CoAP是轻量级物联网协议用于受限的设备。
你可以在此处找到有关CoAP的更多信息，CoAP协议基于UDP但与HTTP类似它使用请求-响应模型。
CoAP观察者选项允许订阅资源并接收有关资源更改的通知。
ThingsBoard服务器节点充当支持常规请求和观察请求的CoAP服务器。
客户端
你可以在网上找到针对不同编程语言的CoAP客户端库本文中的示例将基于CoAP cli作为使用工具，你可以使用我们的Hello World指南中的说明。
1
npm install coap-cli -g
注意：COAP CLI不支持查询参数如果需要使用查询参数则应使用COAP客户端要安装Coap-Client请执行：
- Ubuntu 20.04:
sudo apt install libcoap2-bin - Ubuntu 18.04:
sudo apt install libcoap1-bin
CoAP身份验证和错误代码
我们将在本文中使用令牌凭证访问设备这些凭证稍后将称为$ACCESS_TOKEN应用程序需要在每个CoAP请求中包括$ACCESS_TOKEN作为路径参数。
可能的错误代码及其原因：
- 4.00 请求无效 - 请求参数与正文错误无效请求
- 4.01 未授权 - $ACCESS_TOKEN无效
- 4.04 未找到 - 找不到资源
通过X.509证书替换身份验证。
Key-value格式
ThingsBoard支持以JSON格式的key-value字符串值可以是string、bool、float、long或者二进制格式的序列化字符串；有关更多详细信息请参见协议自定义。
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 transport type在设备配置文件文章中的配置部分。
也可以使用自定义二进制格式或某些序列化框架有关更多详细信息请参见自定义协议。
遥测上传API
为了将遥测数据发布到ThingsBoard服务器节点，请将POST请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/telemetry
支持的最简单的数据格式是：
1
{"key1":"value1", "key2":"value2"}
或
1
[{"key1":"value1"}, {"key2":"value2"}]
请注意在这种情况下服务器端时间戳将分配给上传的数据！
如果您的设备能够获得客户端时间戳则可以使用以下格式：
1
{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}
在上面的示例中我们假设“1451649600512”是具有毫秒精度的Unix时间戳。
例如：值’1451649600512’对应于’2016年1月1日 星期五 12：00：00.512 GMT’
|
|
|
|
属性API
ThingsBoard属性API能够使设备具备如下功能
将属性更新发布到服务器
为了将客户端设备属性发布到ThingsBoard服务器节点，请将POST请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/attributes
|
|
请求属性
为了向ThingsBoard服务器节点请求客户端或共享设备属性，请将GET请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
注意：此示例用Coap-Client而不是CoAp CLI显示因为CoAp CLI不支持查询参数请参阅Client库。
|
|
请注意客户端和共享设备属性键的交集是不好的做法！但是对于客户端、共享和服务器端属性具有相同的密钥。
订阅属性
为了订阅共享设备属性更改请将带有Observe选项的GET请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/attributes
一旦服务器端组件之一（REST API或规则链）更改了共享属性客户端将收到以下更新：
|
|
支持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
通过从服务器订阅RPC命令请将带有观察标志的GET请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/rpc
订阅后客户端可以接收rpc请求。
RPC请求例如下所示：
1
2
3
4
5
6
7
8
{
"id": "1",
"method": "setGpio",
"params": {
"pin": "23",
"value": 1
}
}
说明
- id - 请求ID，int
- method - RPC方法名称, string
- params - -RPC方法参数，自定义json对象
并可以使用POST请求回复以下网址：
1
coap://host/api/v1/$ACCESS_TOKEN/rpc/{$id}
其中$id是整数请求标识符。
参见下面示例：
-
使用RPC debug terminal在仪表板调试
-
从服务器订阅RPC命令并在第一个终端窗口中带有observe标志的发送请求
-
将RPC请求”connect”发送到设备
-
在第二个终端窗口中模拟将响应从设备发送到服务器
-
收到设备的响应: {“result”:”ok”}
|
|
|
客户端RPC
为了将RPC命令发送到服务器，请将POST请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/rpc
请求和响应主体都应该是有效的JSON文档。
参见下面示例：
-
在规则链中添加两个节点”script”和”rpc call reply”
-
在script中输入函数：
1
return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};
-
将请求发送到服务器
-
收到服务器的响应
|
|
|
声明设备
请参阅相应的文章以获取有关声明设备功能的更多信息。
为了启动声明设备，请将POST请求发送到以下URL：
1
coap://host/api/v1/$ACCESS_TOKEN/claim
支持的数据格式为：
1
{"secretKey":"value", "durationMs":60000}
请注意上述字段是可选的如果未指定secretKey则使用空字符串作为默认值。
如果未指定durationms则使用系统参数device.claim.duration（在文件/etc/etting/themings/conf/conf/thexboard.yml中使用）。
设备预配置
请参阅相应的文章并获取有关[设备供应]Device provisioning功能的更多信息。
启动设备配置请将发布请求发送到以下URL：
1
coap://host/api/v1/provision
The supported data format is:
1
2
3
4
5
{
"deviceName": "DEVICE_NAME",
"provisionDeviceKey": "u7piawkboq8v32dmcmpp",
"provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}
硬件API
COAP客户必须发布GET请求。
1
coap get coap://host/api/v1/${access_token}/firmware?title=${title}&version=${version}
说明
host - 本地主机或平台地址
${access_token} - 设备访问令牌
${title} - 固件标题
${version} - 固件的目标版本
自定义协议
通过更改相应的模块可以针对特定用例完全定制HTTP传输。
下一步
-
入门指南 - 快速学习ThingsBoard相关功能。
-
安装指南 - 学习如何在各种操作系统上安装ThingsBoard。
-
可 视 化 - 学习如何配置复杂的ThingsBoard仪表板说明。
-
数据处理 - 学习如何使用ThingsBoard规则引擎。
-
数据分析 - 学习如何使用规则引擎执行基本的分析任务。
-
硬件样品 - 学习如何将各种硬件平台连接到ThingsBoard。
-
高级功能 - 学习高级ThingsBoard功能。
-
开发指南 - 学习ThingsBoard中的贡献和开发。
