首页 / 工程规范 / 设备协议与云端接口契约

设备协议与云端接口契约

设备接入、MQTT Topic、载荷编码、影子合并、异步命令、激活与版本冻结的协议治理规则。

设备协议MQTTProtobuf设备影子
本页目录

先冻结协议族

doc 中出现了至少两套设备 MQTT 草案，不能在同一产品线直接拼接使用：

草案设备身份/鉴权Topic 与载荷适用结论
Tracker Protobuf 草案ProductID.DeviceName、设备/产品组合用户名、HMAC-SHA256 派生 Token$thing/up|down/property|event|action/{ProductID}/{DeviceName}；Protobuf tracker.proto适合作为低功耗 GPS Tracker 的 Schema 驱动协议候选。
系统接口 V2 草案组合 Client ID、IMEI、预置随机密码device/{imei}/up|down；status/event/cmd/ack/ota/config 类型；MessagePack ↔ JSON适合作为另一设备族/接口表面草案，不能假定与 Protobuf Topic 互通。
近场/媒体草案BLE、Local HTTPS、Matter Tunnel、WebRTC 等用于激活、局域网管理或媒体信令/传输不是 MQTT 上报协议的替代品；需有单独的会话、证书和权限契约。
冻结前禁止编码：不能在云端“猜测”载荷格式，也不能依靠 Topic 字符串兼容多个设备族。每个设备产品必须绑定一个不可变 protocol_profile 和明确的升级/迁移路线。

标准契约要素

契约项必须冻结的内容
产品与设备身份产品 ID、设备 ID/IMEI/SN 的角色、格式、是否可变、证书/密钥轮换和激活前后的身份状态。
连接与 ACLMQTT 版本、TLS/mTLS、Client ID、用户名/签名算法、Keep Alive、遗嘱、Topic 读写权限和限流。
Topic上行属性/事件、下行配置/动作、回复/诊断/OTA 的模板；每条消息的发布方、订阅方、QoS、Retain 和分区键。
载荷编码（Protobuf 或 MessagePack 等）、Schema ID/版本、字段类型/单位/枚举、未知字段策略、大小上限和压缩策略。
可靠性消息 ID、幂等窗口、设备重试、平台 ACK、乱序规则、离线队列、死信与重放；QoS 不是唯一可靠性机制。
时间源端事件时间、平台接收时间、单位/精度、时钟偏差和补传排序；禁止混用秒/毫秒而不带 Schema 版本。
错误与演进设备/平台错误码、可重试性、向前/向后兼容、灰度设备范围、弃用版本和迁移截止时间。

激活、影子与命令闭环

激活与接入

  1. 设备出厂登记产品、硬件身份和初始可信材料；后台导入不等于设备已激活或归属某用户。
  2. App 通过受控近场流程读取设备摘要并请求云端验真；敏感材料不在 App/日志中持久化。
  3. 设备按产品协议建立 MQTT 连接，Broker 认证并授予最小 Topic ACL；设备上报激活/在线事件。
  4. 云端创建或更新设备状态，App 通过激活状态/绑定会话确认终态；超时、拒绝和重复激活都有明确状态码。

影子与异步命令

  1. 设备增量上报属性，平台按版本/时间/字段策略合并为影子；原始消息和影子快照不能互相替代。
  2. App/Admin 创建命令时写入 command_id、目标设备、期望结果、有效期和幂等键，先返回“已受理”。
  3. 网关按设备协议编码并下发；设备回执携带原命令关联 ID、执行结果和错误码。
  4. 命令状态从受理、已下发、已确认到成功/失败/超时；重试和设备重连不得产生重复高风险操作。

版本治理与验收

  • 以版本化的 .proto/IDL 或等价机器可读 Schema 作为唯一载荷来源，生成设备/服务端代码和兼容性测试；文档示例不能取代 Schema。
  • 在接入层以 protocol_profile + schema_version 路由到专用 Codec Adapter；Adapter 负责转换，不污染业务模型。
  • 构造真实 MQTT 包回归：Topic、QoS、载荷字节、尾部零值、错误 ACK、重复/乱序/离线重发、权限拒绝、Schema 版本不兼容。
  • 主要来源：architecture/GPS Tracker MQTT协议文档.md、architecture/GPS_Tracker接入适配开发文档.md、architecture/通信协议流程.md、specs/设备与云平台系统接口*.md。跨 Java/Go 调用契约见gRPC 契约与接口安全。