whtp/mqtt.md

WH Telemetry Protocol over MQTT 补充说明

本文件提供将 WH Telemetry Protocol（WHTP）封装并传输于 MQTT 的推荐做法与约定，用于指导设备端、边缘网关及云端服务的接入与实现。

本文档为补充说明，仅描述 传输层（MQTT）相关约定。应用层载荷 仍遵循主规范 WH Telemetry Protocol Specification。

总览

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 + 设备证书 (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 主规范。

// 示例：设备侧发布
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，便于云端告警。