Add MQTT transport layer documentation for WH Telemetry Protocol, detailing connection practices, message structure, and best practices for implementation.

2025-07-07 18:28:10 +08:00
parent 7217f74488
commit fd95fe90ee
3 changed files with 109 additions and 4 deletions
--- a/mqtt.md
+++ b/mqtt.md
@ -0,0 +1,71 @@
+# WH Telemetry Protocol over MQTT 补充说明
+
+本文件提供将 WH Telemetry Protocol（WHTP）封装并传输于 MQTT 的推荐做法与约定，用于指导设备端、边缘网关及云端服务的接入与实现。
+
+> 本文档为补充说明，仅描述 **传输层**（MQTT）相关约定。**应用层载荷** 仍遵循主规范 [WH Telemetry Protocol Specification](schema.md)。
+
+## 总览
+
+1. **主题命名**：采用层级语义化主题，便于基于通配符的订阅聚合。
+2. **QoS**：默认使用 QoS1（至少一次），对高可靠性场景可使用 QoS2；不建议使用 QoS0。
+3. **Retain**：遥测上行包默认不使用 Retain；状态类消息（如 LWT）可 Retain。
+4. **连接安全**：~~TLS 是推荐选项，并配合基于证书或 Token 的双向认证。~~ 目前为调试期间, 使用无加密的 MQTT 连接的 1883 端口, 请生产方做好随时更换为 TLS 的准备
+5. **会话管理**：生产端保持持久会话（Clean Start = 0），避免在网络抖动时丢失消息。
+
+## 连接与认证
+
+| 项目         | 建议                                                                                                            |
+| ------------ | --------------------------------------------------------------------------------------------------------------- |
+| 端口         | ~~`8883`（TLS）~~ / `1883`（非 TLS，仅调试）                                                                    |
+| 加密         | ~~启用 TLS 1.2+；设备应校验服务器证书~~ 调试阶段无加密, 使用无验证方式传输                                      |
+| 客户端标识符 | 使用设备 ID (`dev_id`)                                                                                          |
+| 认证方式     | ~~(1) 双向 TLS + 设备证书<br/> (2) Username/Password 传递 JWT/OAuth2 Token~~ 调试阶段无认证, 使用无验证方式传输 |
+| Keep-alive   | 60s–180s; 服务器以 1.5 倍 keep-alive 作为超时阈值                                                               |
+
+## 消息主题
+
+假设设备唯一标识 `dev_id = 148413b4-c352-49a9-9c48-9d15276a99e7`，则常用主题如下：
+
+| 方向 | 主题模板            | 示例                                           | 说明                                 |
+| ---- | ------------------- | ---------------------------------------------- | ------------------------------------ |
+| 上行 | `/whtp/up/{dev_id}` | `whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7` | 发送遥测数据（Payload 为 WHTP JSON） |
+
+
+## QoS 与重传策略
+
+| 场景     | 建议 QoS | 说明                                                 |
+| -------- | -------: | ---------------------------------------------------- |
+| 遥测数据 |        1 | 至少一次，可接受少量重复；设备收到 PUBACK 即视为成功 |
+| 关键告警 |        2 | 云端必须且仅一次收到                                 |
+
+> [!NOTE]
+> **重复消息去重** 使用 `root.metadata.seq`（循环计数）及 MQTT 报文 `packetId` 实现。
+
+## Payload 格式
+
+MQTT Payload **必须**为 UTF-8 编码的文本，遵循 [WHTP 主规范](schema.md)。
+
+```jsonc
+// 示例：设备侧发布
+Topic   : /whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7
+QoS     : 1
+Retained: false
+Payload : {
+  "version": 1,
+  "msg_type": "telemetry",
+  "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7",
+  "dev_type": "device_type_name",
+  "timestamp": 1715145600,
+  "fields": [
+    { "id": "temperature", "value": 23.5, "metadata": { "data_type": "number", "unit": "Cel" } }
+  ]
+}
+```
+
+## 最佳实践
+
+1. **批量上传**：对高频采样数据使用 `array<T>` 或 `irregular<T>`，显著降低 MQTT 消息数。
+2. **压缩**：在弱网场景可使用 MQTT v5 `content-type: application/json` + `payload-format-indicator:1` 并启用网关级 gzip。
+3. **流控**：设备端应监控 `MQTT_backpressure`，在云端未及时 ACK 时，暂存数据并退避重发，避免阻塞实时队列。
+4. **时间同步**：定期通过 NTP 或云端 SNTP 服务校准，确保时间戳精度。
+5. **错误处理**：当 `error_code ≠ 0` 时，建议 `confidence = 0` 并增加 `error_msg`，便于云端告警。