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-client
- Ubuntu 20.04+
1
| sudo apt install libcoap2-bin
|
- Ubuntu 18.04
1
| sudo apt install libcoap1-bin
|
认证方式
ThingsBoard支持两种认证方式以保护CoAP连接。
支持的方式：
本指南示例采用基于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请求。
首先选择认证方式：
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry
|
⚠️ 请勿忘记将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
|
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/telemetry
|
⚠️ 请勿忘记将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
|
支持的最简数据格式为：
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’。
示例
以下为发布不同类型遥测数据的命令示例。
⚠️ 请勿忘记替换
• $THINGSBOARD_EDGE_HOST_NAME 为您的ThingsBoard Edge主机名或IP地址。
• $ACCESS_TOKEN 为您的设备访问令牌。
示例1。
以对象形式发布无时间戳数据（将使用服务器端时间戳），数据来自telemetry-data-as-object.json文件。
1
| cat telemetry-data-as-object.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry
|
|
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文件。
1
| cat telemetry-data-as-array.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry
|
|
JSON文件内容：
1
| [{"key1":"value1"}, {"key2":true}]
|
示例3。
以带时间戳的对象形式发布数据（将使用遥测时间戳），数据来自telemetry-data-with-ts.json文件。
1
| cat telemetry-data-with-ts.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry
|
|
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 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes
|
⚠️ 请勿忘记将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
使用 new-attributes-values.json 文件中的数据发布客户端属性更新。
「new-attributes-values.json」 文件内容：
1
2
3
4
5
6
7
8
9
10
11
| {
"attribute1": "value1",
"attribute2": true,
"attribute3": 42.0,
"attribute4": 73,
"attribute5": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
|
执行命令：
1
| cat new-attributes-values.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes
|
|
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/attributes
|
⚠️ 请勿忘记将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
Publish client-side attributes update using data from new-attributes-values.json file.
The content of the “new-attributes-values.json” file:
1
2
3
4
5
6
7
8
9
10
11
| {
"attribute1": "value1",
"attribute2": true,
"attribute3": 42.0,
"attribute4": 73,
"attribute5": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
|
执行命令：
1
| cat new-attributes-values.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/attributes
|
|
从服务器请求属性值
为从ThingsBoard服务节点请求客户端或共享设备属性，发送GET请求。
首先选择认证方式：
向以下 URL 发送 GET 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
|
⚠️ 请勿忘记将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
注意： 此示例使用 coap-client 而非 CoAP cli，因 CoAP cli 不支持查询参数。请参阅 客户端库配置。
执行命令：
1
| coap-client -m get "coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"
|
|
向以下 URL 发送 GET 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
|
⚠️ 请勿忘记将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
注意： 此示例使用 coap-client 而非 CoAP cli，因 CoAP cli 不支持查询参数。请参阅 客户端库配置。
执行命令：
1
| coap-client -m get "coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"
|
|
结果：
1
| {"client":{"attribute1":"value1","attribute2":true}}
|
请注意：
客户端与共享设备属性键存在交集是不佳实践！ 但仍可为client、shared甚至server-side属性使用相同键。
订阅来自服务器的属性更新
为订阅共享设备属性变更，发送带Observe选项的GET请求。
首先选择认证方式：
向以下 URL 发送带 Observe 选项的 GET 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes
|
⚠️ 请勿忘记将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
当共享属性被任一服务端组件（REST API 或规则链）修改后，客户端将收到如下更新：
执行命令：
1
| coap get -o coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes
|
|
向以下 URL 发送带 Observe 选项的 GET 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/attributes
|
⚠️ 请勿忘记将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
当共享属性被任一服务端组件（REST API 或规则链）修改后，客户端将收到如下更新：
执行命令：
1
| coap get -o coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/attributes
|
|
结果：
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 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
|
其中
• $THINGSBOARD_EDGE_HOST_NAME 为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 为设备的 access token。
订阅后，客户端将接收 RPC 请求。RPC 请求体示例：
1
2
3
4
5
6
7
8
| {
"id": "1",
"method": "setGpio",
"params": {
"pin": "23",
"value": 1
}
}
|
其中
• id：请求 id，整数请求标识符
• method：RPC 方法名，字符串
• params：RPC 方法参数，自定义 json 对象
要回复 RPC 请求，请向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/{$id}
|
其中 $id 为整数请求标识符。
示例
- 在ThingsBoard 实例中使用 RPC 调试终端部件。
- 使用以下命令订阅来自服务器的 RPC 命令。在第一个终端窗口中发送带 observe 标志的 GET 请求：
1
| coap-client -m get coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc -s 100 -B 100
|
「s」选项表示 subscribe，值需以秒为单位指定。
「B」选项表示 break（在指定超时后结束操作），值需以秒为单位指定。
- 使用 RPC 调试终端部件向设备发送「connect」RPC 请求。
- 将 rpc-response.json 文件保存到本机。
- 在第二个终端窗口中模拟设备向服务器发送响应：
1
| coap-client -f rpc-response.json -m post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/1
|
⚠️ 请将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
将收到设备响应：
|
向以下 URL 发送带 observe 标志的 GET 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc
|
⚠️ 其中 $THINGSBOARD_EDGE_HOST_NAME 为你的 ThingsBoard Edge 主机名或 IP 地址。
订阅后，客户端将接收 RPC 请求。RPC 请求体示例：
1
2
3
4
5
6
7
8
| {
"id": "1",
"method": "setGpio",
"params": {
"pin": "23",
"value": 1
}
}
|
其中
• id：请求 id，整数请求标识符
• method：RPC 方法名，字符串
• params：RPC 方法参数，自定义 json 对象
要回复 RPC 请求，请向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc/{$id}
|
Where $id is an integer request identifier.
Example
- Use RPC debug terminal widget in your ThingsBoard instance;
- Subscribe to RPC commands from the server using the command below. To do this, in the first terminal window send GET request with observe flag.
1
| coap-client -m get coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc -s 100 -B 100
|
「s」选项表示 subscribe，值需以秒为单位指定。
「B」选项表示 break（在指定超时后结束操作），值需以秒为单位指定。
- 使用 RPC 调试终端部件向设备发送「connect」RPC 请求。
- 将 rpc-response.json 文件保存到本机。
- 在第二个终端窗口中模拟设备向服务器发送响应：
1
| coap-client -f rpc-response.json -m post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc/1
|
⚠️ 请将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
|
Client-side RPC
为向服务器发送RPC命令，发送POST请求。
首先选择认证方式：
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
|
其中
• $THINGSBOARD_EDGE_HOST_NAME 为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 为设备的 access token。
请求体和响应体均需为有效 JSON 文档，文档内容取决于处理请求的规则节点。
示例
1
| return {msg: {time: new Date()}, metadata: metadata, msgType: msgType};
|
1
| cat rpc-client-request.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc
|
⚠️ 请将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
1
| {"time":"Thursday, February 5, 2026, 9:08:22 AM Coordinated Universal Time"}
|
|
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc
|
⚠️ 其中 $THINGSBOARD_EDGE_HOST_NAME 为你的 ThingsBoard Edge 主机名或 IP 地址。
请求体和响应体均需为有效 JSON 文档，文档内容取决于处理请求的规则节点。
示例
1
| return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};
|
1
| cat rpc-client-request.json | coap post coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/rpc
|
⚠️ 请将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
1
| {"time":"2016 11 21 12:54:44.287"}
|
|
Claiming devices
设备认领功能允许最终用户在设备部署并连接至ThingsBoard后，安全地将设备关联到其账户。
设备认领流程及支持场景的详细说明请参见认领设备文档。
为启动设备认领，发送POST请求。
首先选择认证方式：
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/claim
|
⚠️ 请勿忘记将
• $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
• $ACCESS_TOKEN 替换为设备的 access token。
|
向以下 URL 发送 POST 请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/claim
|
⚠️ 请勿忘记将 $THINGSBOARD_EDGE_HOST_NAME 替换为你的 ThingsBoard Edge 主机名或 IP 地址。
|
支持的数据格式为：
1
| {"secretKey":"value", "durationMs":60000}
|
请注意
上述字段均为可选。secretKey未指定时，默认使用空字符串。 durationMs未指定时，使用系统参数device.claim.duration（位于/etc/thingsboard/conf/thingsboard.yml）。
Device provisioning
设备预配置支持设备动态注册，无需在ThingsBoard界面手动创建。
预配置流程及支持场景的详细说明请参见设备预配置文档。
预配置请求
为启动设备预配置，向以下URL发送POST请求：
1
| coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/provision
|
其中 $THINGSBOARD_EDGE_HOST_NAME 为您的ThingsBoard Edge主机名或IP地址。
请求载荷
预配置请求须使用以下JSON格式：
1
2
3
4
5
| {
"deviceName": "DEVICE_NAME",
"provisionDeviceKey": "u7piawkboq8v32dmcmpp",
"provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}
|
载荷字段
- deviceName — 待预配置设备的名称。
- provisionDeviceKey — ThingsBoard中配置的预配置密钥。
- provisionDeviceSecret — 与预配置密钥关联的预配置密钥。
若提供的凭据有效，ThingsBoard将自动创建设备（若不存在）并返回设备凭据，使设备可与平台通信。
Firmware API
选择认证方式：
CoAP 客户端需向以下地址发起 GET 请求：
1
| coap get coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION
|
其中
- $THINGSBOARD_HOST_NAME：localhost 或平台地址
- $ACCESS_TOKEN：设备 access token
- $TITLE：固件标题
- $VERSION：目标固件版本
|
CoAP 客户端需向以下地址发起 GET 请求：
1
| coap get coap://$THINGSBOARD_EDGE_HOST_NAME/api/v1/firmware?title=$TITLE&version=$VERSION
|
其中
- $THINGSBOARD_HOST_NAME：localhost 或平台地址；
- $TITLE：固件标题；
- $VERSION：目标固件版本。
|
协议自定义
可通过修改对应模块，针对特定用例完全自定义CoAP传输。
下一步
-
快速入门指南 - 快速了解ThingsBoard主要功能，约15-30分钟完成。
-
数据可视化 - 配置ThingsBoard复杂仪表盘的说明。
-
数据处理与操作 - 学习使用ThingsBoard规则引擎。
-
IoT数据分析 - 学习使用规则引擎执行基本分析任务。
-
高级功能 - 了解ThingsBoard高级功能。
-
贡献与开发 - 了解ThingsBoard贡献与开发。