72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
# 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`，便于云端告警。
|