设备交互
设备建立正式连接后,按产品启用的能力实现下列交互。完整主题及配置要求见主题总览。
数据上报
设备应先完成连接认证,按接入前准备配置产品物模型,声明所使用的数据键和类型。数据上报及确认主题见主题总览。
综合数据上报
设备只通过以下主题上报遥测和客户端属性:
v1/devices/{token}/data
报文顶层只允许包含 messageId、telemetry 和 client。其中 messageId 不能为空,telemetry 必须是采集点数组,每个采集点只能包含毫秒时间戳 ts 和非空数据对象 values。
{
"messageId": "20260914-000001",
"telemetry": [
{
"ts": 1789462300000,
"values": {
"machineCode": "DEVICE-MC-001",
"temperature": 25.4,
"humidity": 60.2
}
}
],
"client": {
"firmwareVersion": "1.2.0",
"currentWorkMode": "AUTO"
}
}
所有字段、数据类型和取值范围都必须在产品物模型中提前声明。每包最多包含一百个采集点,采集时间最多向前追溯三十天,最多超前平台时间五分钟。
设备每次周期上报都必须在 telemetry[].values 中携带相同的 machineCode。首次有效上报会锁定该设备的机器码,后续不得更改,也不得与其他设备重复。
认领前,平台只登记机器码并返回确认,不会保存其他遥测或触发业务规则。因此,认领前收到成功确认不代表普通遥测已经入库。
数据确认与重试
设备在上报前必须先订阅:
v1/devices/{token}/ack/+
平台完成数据事务后,会通过以下主题返回处理结果:
v1/devices/{token}/ack/{messageId}
{
"messageId": "20260914-000001",
"code": 200,
"msg": "上报成功"
}
| 状态码 | 处理方式 |
|---|---|
200 | 数据已经成功提交 |
20001 | 相同消息已经处理,不得更换消息编号重复发送同一批数据 |
40001 | 报文或物模型校验失败,修正数据后使用新的消息编号上报 |
50000 | 平台处理异常,可保留原消息编号重试 |
等待确认超时后,应使用原 messageId 重试。平台按照设备和消息编号进行幂等处理,重复数据不会再次写入遥测历史或重复触发规则。
共享属性
配置下发与平台属性查询
按需配置:需要平台维护并下发共享配置的设备实现。 本节的“读取”是设备读取平台保存的属性;平台读取设备本机配置见配置读取。
共享属性用于平台向设备下发需要持久保存的目标配置。设备订阅以下主题接收变更:
v1/devices/{token}/attributes
平台下发内容为扁平键值对象:
{
"targetTemperature": 26.5,
"workMode": "AUTO"
}
设备收到后应校验、保存并应用收到的属性键值,未包含的属性不应被当作删除。共享属性由平台维护,设备不得通过综合数据报文反向上报共享属性。需要持续上报配置的实际生效状态时,可在物模型中另行定义客户端属性;需要临时读取本机配置时,使用配置读取中的读取协议。
设备查询平台属性
使用共享配置的设备启动或重新连接后,应先订阅 v1/devices/{token}/attributes/response/+,再向以下主题主动读取最新属性:
v1/devices/{token}/attributes/request/{requestId}
请求必须同时包含 clientKeys 和 sharedKeys 字符串数组,不需要的类别使用空数组:
{
"clientKeys": ["firmwareVersion"],
"sharedKeys": ["targetTemperature", "workMode"]
}
平台通过 v1/devices/{token}/attributes/response/{requestId} 返回已保存的属性值,请求与响应编号一致:
{
"client": {
"firmwareVersion": "1.2.0"
},
"shared": {
"targetTemperature": 26.5,
"workMode": "AUTO"
}
}
属性交互的区别
| 需求 | 发起方 | 使用主题 | 读取或写入对象 |
|---|---|---|---|
| 修改设备共享配置 | 平台 | attributes | 平台下发属性变更,设备保存并应用。 |
| 启动或重连后恢复平台配置 | 设备 | attributes/request、attributes/response | 查询平台已保存的属性值。 |
| 获取设备当前保存的配置 | 平台 | attributes/read/request、attributes/read/response | 查询设备本机值,仅返回读取结果。 |
配置读取
按需配置:需要管理端获取设备本机配置的设备实现。 此能力用于查看、核对或编辑设备当前保存的配置,不能用共享属性中的平台属性查询结果代替。
管理员在共享属性设置中点击“获取”时,平台向在线设备发送读取请求。每次请求读取一个物模型已定义的共享属性,设备订阅:
v1/devices/{token}/attributes/read/request/+
实际收到的主题为 v1/devices/{token}/attributes/read/request/{requestId},其中请求编号由平台生成。请求内容:
{
"key": "system_config"
}
system_config 仅用于说明属性键的位置,应替换为该产品实际定义的共享属性键。设备读取本机保存的对应配置后,通过以下主题响应:
v1/devices/{token}/attributes/read/response/{requestId}
读取成功:
{
"success": true,
"data": {
"key": "system_config",
"value": {}
}
}
读取失败:
{
"success": false,
"error": "设备未保存该项配置"
}
| 项目 | 处理要求 |
|---|---|
| 请求对应关系 | 响应主题使用收到的原请求编号,成功响应中的 data.key 必须与请求的 key 完全一致。 |
| 响应字段 | 成功报文顶层只包含 success、data,data 只包含 key、value;失败报文只包含 success、非空字符串 error。success 必须是布尔值。 |
| 配置内容 | value 使用设备实际保存的值,数据类型应符合该共享属性的物模型定义。上面的空对象仅展示响应封装,不规定配置内部字段;参数设置、笼位位置、模板设置、报警灯设置、系统配置等内容由设备端自行组织和解析。 |
| JSON 属性 | 对象或数组直接放入 value,不能先转换成 JSON 字符串再传输。平台不额外规定这些配置的内部结构,不接受非有限数值。 |
| 大小与时限 | 单条响应最大为 256 KiB,按 UTF-8 编码后的字节数计算。平台默认等待十秒,读取等待时间最大三十秒;设备应及时返回,不支持离线排队读取。 |
| 重复或过期响应 | 平台只接收仍在等待中的对应响应;已完成、已超时或没有读取请求的响应会被忽略。响应设置 retain=false。 |
| 管理端效果 | “获取”仅把读取结果填入编辑表单,不会自动保存平台属性,也不会再次下发配置。管理员确认设置后才保存并下发。 |
控制指令
按需配置:支持远程控制,或作为设备联动目标的设备实现。 设备联动的目标设备沿用本节的请求和响应协议,不需要单独增加一套目标控制主题。
需要立即执行的设备动作应在产品物模型中定义为服务。平台通过以下主题下发请求:
v1/devices/{token}/rpc/request/{requestId}
{
"method": "setRelay",
"params": {
"channel": 1,
"state": true
}
}
设备应校验方法和参数,执行后使用相同请求编号返回结果:
v1/devices/{token}/rpc/response/{requestId}
{
"success": true,
"data": {
"channel": 1,
"state": true
}
}
设备必须使用布尔值 success 返回实际执行结果,不能用“已收到请求”代替“已执行成功”。执行失败时返回 success: false,并通过 error 或 message 说明原因。单条响应最大为四千字节。
设备应按指令请求编号处理重复投递:同一编号只执行一次,后续重复消息返回原执行结果,避免重复动作。
管理端发起的离线调用可能进入排队状态;设备联动不采用离线补发。平台显示“已下发”只表示 MQTT 服务已确认接收发布消息,不代表目标设备已经收到或执行成功;最终执行结果应以设备响应为准。
设备联动
按需配置:需要主动触发其他设备动作的来源设备实现 platform 主题。 仅接受控制的目标设备实现控制指令中的 rpc 主题即可。
设备联动由来源设备的本地业务逻辑发起。例如,喂食器需要打开电箱的照明时,喂食器向平台提交联动标识,平台按已配置的目标设备、控制指令和固定参数向电箱发送远程调用,再将执行状态返回喂食器。配置联动本身不会自动根据遥测触发动作。
平台配置与设备职责
在来源设备详情侧板的“设备联动”标签页中新增配置,填写名称和联动标识,选择目标设备、其产品物模型中的控制指令及参数,并设置是否启用和响应超时。超时默认十秒,可配置一至六十秒。
来源设备与目标设备必须是同一有效租户下已认领、未停用且凭据有效的不同设备,产品也必须有效。来源设备只使用自己的访问令牌,不需要知道目标设备的访问令牌。
例如,联动标识 light_on 对应目标电箱的 setRelay 指令,固定参数为 channel: 1、state: true。关闭照明应另行配置一个标识,例如 light_off,使用 state: false。来源设备不能在联动请求中临时指定目标设备、控制方法或参数。
来源设备的请求与响应
来源设备先订阅:
v1/devices/{token}/platform/response/+
然后通过以下主题发送请求:
v1/devices/{token}/platform/request/{requestId}
请求编号由来源设备生成,仅允许字母、数字、下划线和连字符,长度为一至六十四个字符。version 必须为整数 1。请求只允许包含对应操作规定的字段,单条请求最大为四千字节。
| 操作 | type | 允许的请求字段 | 用途 |
|---|---|---|---|
| 查询目录 | catalog | version、type | 获取来源设备当前可用的联动标识和名称;已知标识时可直接触发,不必每次先查询目录。 |
| 执行联动 | execute | version、type、bindingCode | 按联动标识执行平台预先配置的指令和参数。每次新的动作使用新的请求编号。 |
| 查询结果 | query | version、type | 使用原执行请求编号查询该次联动的最新状态,不会重新执行。 |
查询可用联动目录
使用一个新的请求编号,例如 catalog_001,发送:
{
"version": 1,
"type": "catalog"
}
平台在 v1/devices/{token}/platform/response/catalog_001 返回当前有效且已启用的配置:
{
"version": 1,
"requestId": "catalog_001",
"type": "catalog",
"bindings": [
{
"code": "light_on",
"name": "打开照明"
},
{
"code": "light_off",
"name": "关闭照明"
}
]
}
没有可用配置时 bindings 为空数组。返回的 code 用于执行请求的 bindingCode。
触发联动
例如向 v1/devices/{token}/platform/request/feeder_light_001 发布:
{
"version": 1,
"type": "execute",
"bindingCode": "light_on"
}
平台校验配置后创建指令,并返回当前状态。后续状态和最终结果也通过 v1/devices/{token}/platform/response/feeder_light_001 返回;首次响应可能仍在排队或执行中,应继续等待最终结果。
目标设备收到的是标准远程调用:
{
"method": "setRelay",
"params": {
"channel": 1,
"state": true
}
}
该调用使用目标设备自己的 rpc/request/{rpcRequestId} 主题。平台为目标指令生成的 rpcRequestId 与来源设备的 requestId 是两个编号。 目标设备必须使用收到的目标指令编号返回 rpc/response/{rpcRequestId},不能使用喂食器的执行请求编号。
目标设备执行完成后可以返回:
{
"success": true,
"message": "照明已开启"
}
平台向来源设备返回的成功结果示例:
{
"version": 1,
"requestId": "feeder_light_001",
"bindingCode": "light_on",
"rpcRequestId": "link_0123456789abcdef0123456789abcdef0123456789abcdef01234567",
"status": "SUCCESS",
"terminal": true,
"sent": true,
"sendState": "CONFIRMED",
"reason": "",
"receivedAt": 1791500000000,
"expiresAt": 1791500010000,
"success": true,
"result": {
"success": true,
"message": "照明已开启"
}
}
receivedAt 和 expiresAt 为毫秒时间戳。terminal 表示该请求是否已经结束;处理中响应不包含最终 success 和 result。成功或设备明确返回失败时,result 只提供执行结果及简短消息,不透传目标设备响应中的其他数据。
查询某次执行结果
没有收到最终响应,或来源设备断线后需要恢复查询时,向原执行主题 v1/devices/{token}/platform/request/feeder_light_001 发布:
{
"version": 1,
"type": "query"
}
平台返回原请求的当前状态。查询必须沿用原执行请求编号,且不能带 bindingCode。查询不存在的请求会被拒绝;查询只读取状态,不会再次发送目标控制指令。来源设备应保存未结束请求的编号,重连后先恢复响应订阅,再查询原请求。
执行状态与重试
status | 是否结束 | 含义与设备处理 |
|---|---|---|
QUEUED | 否 | 平台已受理,等待内部执行;不等于离线排队补发。继续等待或查询。 |
PROCESSING | 否 | 平台正在发送或核对发送结果,消息可能已经发出。不能自行认定目标动作未执行。 |
DELIVERED | 否 | MQTT 服务已确认发布,等待目标设备实际响应。不能视为执行成功。 |
SUCCESS | 是 | 目标设备已明确返回 success: true,可按成功处理。 |
FAILED | 是 | 目标设备已明确返回 success: false,查看 reason 和 result.message。 |
TIMEOUT | 是 | 在时限内没有得到有效结果;结合发送状态判断,可能已经执行,不能直接当作未执行并重复触发。 |
CANCELED | 是 | 指令因目标离线、配置失效等原因在发送前取消,查看 reason。 |
REJECTED | 是 | 请求字段、联动标识或设备授权条件不符合要求,或查询记录不存在;查看 reason。 |
拒绝响应包含 version、requestId、status、terminal、success、sent 和 reason,不保证包含目标指令编号或其他执行记录字段。
| 发送状态 | 含义 |
|---|---|
NOT_SENT | 尚未发送,平台可以在原请求的有效期内继续处理。 |
POSSIBLE | 消息可能已经发出,平台不会自动重复发布,以免目标设备重复动作。 |
CONFIRMED | 发布已经得到确认,或已收到目标设备的有效响应。仍需看执行 status,不能仅据此判断业务成功。 |
sent: true 对应 sendState: CONFIRMED,表示发送确认,不表示动作成功;sent: false 且 sendState: POSSIBLE 时,也不能认定消息未到达目标设备。
- 目标离线时取消联动,不在目标重连后补发。需要新的动作时,由来源设备根据当前业务状态重新判断,并使用新请求编号发起。
- 对同一次动作重试必须保留原请求编号和相同请求内容,平台返回原记录,不会再次创建或发布目标指令。同一编号改用其他联动标识会被拒绝。
- 已结束的请求不会因为再次提交而重新执行。执行新的动作需要新的编号;超时但可能已发送时,应先核对目标状态再决定是否发起新动作。
- 最终状态通知可能因来源设备离线或网络中断而无法接收,不应假定重连后会自动补齐所有通知,使用
query查询原请求。 - 目标设备必须按自己的远程调用请求编号去重,并如实返回执行结果。
管理端可在指令日志中按“设备联动”来源筛选执行记录,查看目标指令的状态和联动详情。
固件升级
按需配置:仅支持平台远程固件升级的设备需要实现。 使用 ota/request/{requestId} 发布请求或进度,订阅 ota/response/+ 接收结果和任务。
设备检查升级时,通过升级请求主题发送当前版本:
{
"action": "CHECK",
"currentVersion": "1.2.0"
}
平台使用相同请求编号返回无可用更新或存在可用更新。存在更新时,响应中会包含版本、下载地址、文件大小和校验信息。
设备下载和安装过程中,应使用平台任务的同一请求编号上报进度:
{
"action": "PROGRESS",
"status": "UPDATING",
"progress": 80
}
允许的升级状态为 DOWNLOADING、DOWNLOADED、VERIFIED、UPDATING、UPDATED 和 FAILED。进度必须是零到一百之间的整数;失败时可附加 errorMessage 错误信息。