CoAP 上下行对接指南

DTS服务（Digital Twin Service）提供了轻量化的 CoAP（Constrained Application Protocol）接入网关。本文档旨在帮助物联网设备端开发者与第三方系统集成商，快速理解并实现基于 CoAP 协议的双向数据互通。

协议说明

DTS服务的 CoAP 接入方案支持上行数据采集与下行控制调用两个方向的双向通信：

• 上行通信：终端设备或第三方边缘系统作为 CoAP 客户端，主动向 DTS服务的 CoAP 服务端（Server）发起请求，上报属性遥测、事件告警或设备基础数据。
• 下行通信：DTS服务作为 CoAP 客户端，主动向第三方部署的 CoAP 服务端（Server）下发请求，执行产品定义的服务调用或反控指令。

[!WARNING] 当前版本的 CoAP 网关通道不支持 DTLS 安全传输，亦不支持流式响应（Observe 订阅模式/分块传输）。通信采用标准非加密的 UDP 传输，报文最大建议在 MTU 限制（1280 字节）内，避免网络碎片化导致数据丢包。

上行接入地址

终端设备或第三方系统向上行上报数据时，请使用以下 CoAP 统一资源路径（URI）规范：

coap://{gatewayHost}:5683/up/{productId}/{method}

参数详细说明如下：

属性上报

属性上报用于高频或定期同步设备实时的遥测指标及状态数据。

• 请求地址： text coap://{gatewayHost}:5683/up/{productId}/0
• 请求方式：POST
• Payload 格式：application/json
• 请求体示例： json { "deviceId": "device-001", "temperature": 4.5, "humidity": 62, "timestamp": 1782479141200 } 字段说明：deviceId 为终端物理设备唯一 ID，timestamp 为毫秒级时间戳。其余字段（如 temperature）需与平台的产品 Profile 属性定义严格对齐。
• 返回示例： json { "code": 0, "message": "success" } 返回码说明：code: 0 标识网关成功接收并投递至 DTS服务解析引擎。

事件上报

事件上报用于呈报设备在运行过程中产生的特定业务事件、系统故障或用户操作记录。

• 请求地址： text coap://{gatewayHost}:5683/up/{productId}/1
• 请求方式：POST
• Payload 格式：application/json
• 请求体示例： json { "deviceId": "device-001", "eventCode": "door_open", "eventTime": 1782479141200, "status": "open" } 字段说明：eventCode 标识发生的事件类型编码，eventTime 为事件发生时的毫秒级时间戳，其余字段为该事件的输出参数。
• 返回示例： json { "code": 0, "message": "success" }

设备上报

设备上报（设备注册）用于向平台动态宣告新设备实体的上线，以实现免建档设备自动入库。

• 请求地址： text coap://{gatewayHost}:5683/up/{productId}/2
• 请求方式：POST
• Payload 格式：application/json

• 请求体支持单设备对象或多设备数组。

• 单设备请求体示例： json { "deviceId": "device-001", "deviceName": "测试设备001", "deviceStatus": 1, "timestamp": 1782479141200 }

• 多设备批量请求体示例： json [ { "deviceId": "device-001", "deviceName": "测试设备001", "deviceStatus": 1 }, { "deviceId": "device-002", "deviceName": "测试设备002", "deviceStatus": 0 } ]

上行数据格式说明

DTS服务网关层对 CoAP 上行 Payload 的数据格式支持以下两种处理机制：

1. 标准数据格式：如果产品配置选择此模式，Payload 中字段名和数值必须与产品 Profile（本体模型）中定义的属性和事件标识符一一对应，网关将进行自动对齐解析。
2. 定制数据格式（透传模式）：当设备端报文格式不可修改时，设备只需保证上报的是合法 JSON。网关层会将报文送入关联的产品 JavaScript 消息解析脚本中，由脚本完成字段转换与特征取值映射。

下行服务配置

当需要通过 DTS服务主动对物理设备进行控制或调用其服务时，网关提供了 CoAP Client 代理功能。

首先，需在网关管理控制台中，为目标网关服务实例配置 CoAP 服务：

接着，在产品 Profile 定义的服务中，配置对应的动作路径。支持使用动态路由变量及参数占位符：

/qa/${route}?message=${message}

当触发服务调用时，网关会自动将 CoAP 服务基准地址与产品动作路径进行拼接，拼装出最终的 CoAP 请求路由：

coap://127.0.0.1:19131/downlink/qa/demo-route?message=hello

下行请求体

当下发控制指令时，DTS服务会将系统层面的服务调用参数组装为 CoAP Request Payload。

• 网关下发的 Payload 示例： json { "route": "demo-route", "message": "hello" }
• 第三方 CoAP 服务端处理完指令后返回的响应载荷必须是标准的 JSON 格式，网关会将其解析并作为服务调用回执返回给 DTS服务。

错误约定

网关在处理 CoAP 请求时，如果遇到以下非正常场景，会直接拦截并返回错误信息：