协议总览
2025/10/12大约 2 分钟
协议总览
平台设备接入基于 MQTT 3.1.1 + JSON(UTF-8),报文风格与阿里云 IoT(Alink)兼容但存在实现差异,请以本章节为准。本页是速查入口,详细内容见各分篇。
接入要素
| 要素 | 取值 | 详见 |
|---|---|---|
| 设备三元组 | ProductKey + DeviceName + DeviceSecret(控制台获取) | 建立 MQTT 连接 |
| ClientId | {pk}.{dn}|timestamp={毫秒},signmethod=hmacsha256| | 建立 MQTT 连接 |
| Username | {deviceName}&{productKey} | 建立 MQTT 连接 |
| Password | HMAC(deviceSecret, 原文) 大写十六进制 | 签名算法 |
| Broker | MQTT mqtt.xiaolizi.tech:2883 / MQTTS mqtts.xiaolizi.tech:9883(以控制台返回为准) | 连接参数 |
Topic 前缀速查
上行 /sys/{pk}/{dn}/thing/event/property/post 属性上报
/sys/{pk}/{dn}/thing/event/{identifier}/post 事件上报
/sys/{pk}/{dn}/thing/service/property/set_reply 属性设置回复
/ext/rrpc/{messageId}/sys/{pk}/{dn}/thing/service/{identifier} 同步服务回复(回原Topic)
/shadow/update/{pk}/{dn} 影子请求
/ota/device/inform/{pk}/{dn} /ota/device/progress/{pk}/{dn} OTA版本/进度
下行 /sys/{pk}/{dn}/thing/service/property/set 属性设置
/sys/{pk}/{dn}/thing/service/{identifier} 异步服务调用
/shadow/get/{pk}/{dn} 影子回复/期望下发
/ota/device/upgrade/{pk}/{dn} OTA升级指令
/{pk}/{dn}/user/{topicShortName} 自定义Topic完整 Topic 总表与订阅清单见 Topic 与报文约定。
能力分篇
| 分篇 | 内容 |
|---|---|
| 建立 MQTT 连接 | 控制台准备、签名算法(Python/Java/C/ESP-IDF)、动态注册、鉴权流程 |
| Topic 与报文约定 | Topic 总表、JSON 信封、必订阅清单、QoS 约定 |
| 物模型 | 属性上报、事件上报、属性设置、服务调用(同步/异步) |
| 诊断、日志、信号与位置 | 网络诊断、本地日志、日志配置、信号/位置上报、自定义 Topic |
| 设备影子 | reported/desired、版本控制、云端 control 推送 |
| OTA 升级 | 版本/进度上报、固件查询、批量推送指令 |
| 联调与验证 | MQTTX/mosquitto/Python 示例、验收清单 |
| 错误码与故障排查 | 错误码速查、排错表、已知限制 |