MQTT接入

设备交互

通过 MQTT 完成数据上报、共享属性交互、配置读取、控制指令、设备联动和固件升级。

设备建立正式连接后,按产品启用的能力实现下列交互。完整主题及配置要求见主题总览。

数据上报

设备应先完成连接认证,按接入前准备配置产品物模型,声明所使用的数据键和类型。数据上报及确认主题见主题总览。

综合数据上报

设备只通过以下主题上报遥测和客户端属性:

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允许的请求字段用途
查询目录catalogversion、type获取来源设备当前可用的联动标识和名称;已知标识时可直接触发,不必每次先查询目录。
执行联动executeversion、type、bindingCode按联动标识执行平台预先配置的指令和参数。每次新的动作使用新的请求编号。
查询结果queryversion、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 错误信息。

相关文档

© 2026 飞鸟智联