CoAP

• 入门
  • CoAP基础
  • 客户端
  • CoAP身份验证和错误代码
• Key-value格式
• 遥测上传API
• 属性API
  • 将属性更新发布到服务器
  • 从服务器请求属性值
  • 从服务器订阅属性更新
• RPC API
  • 服务器端RPC
  • 客户端RPC
• 声明设备
• 自定义协议
• 下一步

入门

CoAP基础

CoAP是轻量级物联网协议用于受限的设备。您可以在此处找到有关CoAP的更多信息。CoAP协议基于UDP，但与HTTP类似它使用请求-响应模型。CoAP观察选项允许订阅资源并接收有关资源更改的通知。

ThingsBoard服务器节点充当支持常规请求和观察请求的CoAP服务器。

客户端

你可以在网上找到针对不同编程语言的CoAP客户端库。本文中的示例将基于CoAP cli作为使用工具，您可以使用我们的Hello World指南中的说明。

CoAP身份验证和错误代码

我们将在本文中使用令牌凭证访问设备，这些凭证稍后将称为 $ACCESS_TOKEN。应用程序需要在每个CoAP请求中包括 $ACCESS_TOKEN 作为路径参数。可能的错误代码及其原因：

• 4.00 请求无效 - 请求参数与正文错误，请求无效。
• 4.01 未授权 - $ACCESS_TOKEN无效。
• 4.04 未找到 - 找不到资源。

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服务器节点，请将POST请求发送到以下URL：

coap://host/api/v1/$ACCESS_TOKEN/telemetry

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

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

或者

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

请注意，在这种情况下，服务器端时间戳将分配给上传的数据！

如果您的设备能够获得客户端时间戳，则可以使用以下格式：

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

In the example above, we assume that “1451649600512” is a unix timestamp with milliseconds precision. For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’

• Example
• telemetry-data-as-object.json
• telemetry-data-as-array.json
• telemetry-data-with-ts.json

resources/coap-telemetry.sh

# Publish data as an object without timestamp (server-side timestamp will be used) cat telemetry-data-as-object.json | coap post coap://localhost/api/v1/$ACCESS_TOKEN/telemetry # Publish data as an array of objects without timestamp (server-side timestamp will be used) cat telemetry-data-as-array.json | coap post coap://localhost/api/v1/$ACCESS_TOKEN/telemetry # Publish data as an object with timestamp (server-side timestamp will be used) cat telemetry-data-with-ts.json | coap post coap://localhost/api/v1/$ACCESS_TOKEN/telemetry

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服务器节点，请将POST请求发送到以下URL：

coap://host/api/v1/$ACCESS_TOKEN/attributes

• Example
• new-attributes-values.json

resources/coap-attributes-publish.sh
# Publish client-side attributes update cat new-attributes-values.json | coap post coap://localhost/api/v1/$ACCESS_TOKEN/attributes

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服务器节点请求客户端或共享设备属性，请将GET请求发送到以下URL：

coap://host/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

• Example
• Result

resources/coap-attributes-request.sh
# Send CoAP attributes request coap get coap://localhost/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

resources/attributes-response.json
{"key1":"value1"}

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

从服务器订阅属性更新

为了订阅共享设备属性更改，请将带有Observe选项的GET请求发送到以下URL：

coap://host/api/v1/$ACCESS_TOKEN/attributes

一旦服务器端组件之一（REST API或规则链）更改了共享属性，客户端将收到以下更新：

• Example
• Result

resources/coap-attributes-subscribe.sh
# Subscribe to attribute updates coap get -o coap://localhost/api/v1/$ACCESS_TOKEN/attributes

resources/attributes-response.json
{"key1":"value1"}

RPC API

服务器端RPC

为了从服务器订阅RPC命令，请将带有观察标志的GET请求发送到以下URL：

coap://host/api/v1/$ACCESS_TOKEN/rpc

订阅后，客户端可以接收rpc请求。RPC请求正文的示例如下所示：

{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

• id - 请求ID，int
• method - RPC方法名称, string
• params - -RPC方法参数，自定义json对象

并可以使用POST请求回复以下网址：

coap://host/api/v1/$ACCESS_TOKEN/rpc/{$id}

其中 $id 是整数请求标识符。

• Example Subscribe
• Example Reply
• Reply Body

resources/coap-rpc-subscribe.sh
# Subscribe to RPC requests coap get -o coap://localhost/api/v1/$ACCESS_TOKEN/rpc

resources/coap-rpc-reply.sh
# Publish response to RPC request cat rpc-response.json | coap post coap://localhost/api/v1/$ACCESS_TOKEN/rpc/1

resources/rpc-response.json
{"result":"ok"}

客户端RPC

为了将RPC命令发送到服务器，请将POST请求发送到以下URL：

coap://host/api/v1/$ACCESS_TOKEN/rpc

请求和响应主体都应该是有效的JSON文档。文档的内容特定于将处理您的请求的规则节点。

• Example Request
• Request Body
• Response Body

resources/coap-rpc-from-client.sh
# Post client-side rpc request cat rpc-client-request.json | coap post coap://localhost/api/v1/$ACCESS_TOKEN/rpc

resources/rpc-client-request.json
{"method": "getTime", "params":{}}

resources/rpc-server-response.json
{"time":"2016 11 21 12:54:44.287"}

声明设备

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

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

coap://host/api/v1/$ACCESS_TOKEN/claim

支持的数据格式为：

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

请注意，以上字段是可选的。如果未指定secretKey，则使用空字符串作为默认值。万一durationMs毫秒未指定时，系统参数device.claim.duration被使用（在文件/etc/thingsboard/conf/thingsboard.yml）。

自定义协议

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

下一步

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

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

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

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

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

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

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

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