DEVICE CONTRACTS

协议中心

本地开发基线

一个稳定核心，三种设备形态

固件、平台和应用，使用同一套可演进的设备语言。

南向协议写入固件与网关，北向协议提供给深脑、球球老师和业务运营系统。供应商协议只在适配层结束。
南向

设备协议

身份、心跳、遥测、事件、命令与回执

权威层

造物云契约

永久设备 ID、所有权代次、能力与规范化事件

北向

业务接口

REST API、事件订阅、媒体就绪通知

传输分工

不要让一条协议承担所有数据。

MQTT / TLS

心跳、遥测、配置、命令与回执。消息体小，可重试，可离线恢复。

8883

HTTPS

录音文件与固件包。支持校验和、断点续传和短时签名地址。

443

WSS + Opus

球球老师实时语音。直接进入 AI 实时网关，不经过 ThingsBoard。

443
主题约定

MQTT topic

zy/v1/devices/{deviceId}/up设备上行
zy/v1/devices/{deviceId}/down平台命令
zy/v1/devices/{deviceId}/ack命令回执
统一消息信封
{
  "schema": "zaowuyun.device.v1",
  "protocol_version": "1.0",
  "message_id": "MSG_01J8R7M2",
  "device_id": "DVC_QQ_01J8R1P8",
  "ownership_epoch": 1,
  "sent_at": "2026-08-31T08:00:00.000Z",
  "type": "telemetry.reported",
  "payload": { "battery_percent": 72 }
}
命令状态机

命令不是一次请求，而是一段可审计生命周期。

1queued
2accepted
3executing
4succeeded

身份

每台设备独立证书，造物云设备 ID 永久稳定。

防重放

命令带幂等键、过期时间与 ownership_epoch。

版本

小版本只新增可选字段，改变语义必须升主版本。

大文件

音频不走 MQTT，上传完成后只发布媒体就绪事件。