Add MQTT transport layer documentation for WH Telemetry Protocol, detailing connection practices, message structure, and best practices for implementation.
This commit is contained in:
33
README.md
Normal file
33
README.md
Normal file
@ -0,0 +1,33 @@
|
||||
# WH Telemetry Protocol（WHTP）
|
||||
|
||||
> A lightweight, self-describing telemetry protocol based on UTF-8 JSON
|
||||
|
||||
WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JSON 遥测上行协议**。它强调 **自描述能力** 与 **轻量化设计**，在带宽、功耗与开发效率之间取得平衡，帮助设备端与云端快速完成数据对接。
|
||||
|
||||
## 特性亮点
|
||||
|
||||
- **自描述（Self-descriptive）**：数据类型、单位、采样间隔等元信息随报文一并上送，脱离外部 Schema 亦可独立解析。
|
||||
- **单一载体（JSON）**：无需生成器或专用编解码库，主流语言天然支持。
|
||||
- **时间表达力强**：支持从秒到纳秒的多粒度 UNIX 时间戳，或 ISO-8601 字符串。
|
||||
- **批量数据友好**：内置等间隔 `array<T>` 与非等间隔 `irregular<T>` 两种批量格式，可显著降低消息数。
|
||||
- **枚举支持**：全局或内联枚举可读性强，兼具类型安全。
|
||||
- **错误／置信度模型**：统一的 `error_code` + `confidence` 机制，便于数据质量管理。
|
||||
- **多传输层**：已提供 [MQTT 补充说明](mqtt.md)，亦可轻松扩展至 HTTP、WebSocket、CoAP 等。
|
||||
|
||||
## 快速上手
|
||||
|
||||
1. 阅读主规范 [schema.md](schema.md)，了解字段定义与类型系统。
|
||||
2. 查看 [example.jsonc](example.jsonc) 获取完整示例。
|
||||
3. 若采用 MQTT 作为载体，参考 [mqtt.md](mqtt.md) 的主题、QoS、Retain 与连接安全实践。
|
||||
4. 参见 [schema.json](schema.json) 获取 [JSON Schema](https://json-schema.org/) 定义。
|
||||
|
||||
## 仓库结构
|
||||
|
||||
| 路径 | 说明 |
|
||||
| --------------- | --------------------------------- |
|
||||
| `schema.md` | WHTP 主规范（协议字段与类型定义） |
|
||||
| `mqtt.md` | MQTT 传输层补充说明 |
|
||||
| `example.jsonc` | 完整示例消息，含字段注释 |
|
||||
| `README.md` | 当前文件，项目概览 |
|
||||
|
||||
|
||||
71
mqtt.md
Normal file
71
mqtt.md
Normal file
@ -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`，便于云端告警。
|
||||
@ -1,4 +1,4 @@
|
||||
# WH Telemetry Protocol
|
||||
# WH Telemetry Protocol Specification
|
||||
|
||||
WH Telemetry Protocol（简称 WHTP）是一套以 JSON 为载体的遥测数据上行协议，强调自描述能力与轻量化设计，适用于物联网设备与云端之间的高效数据传输。
|
||||
|
||||
@ -85,9 +85,10 @@ type Timestamp =
|
||||
> [!NOTE]
|
||||
> 根级 (root-level) 时间戳表示消息生成或入队时刻, 字段级 (field-level) 时间戳表示实际数据采样时刻, 应使用字段级时间戳进行所有时间序列分析
|
||||
|
||||
### field 字段 (`fields`)
|
||||
### 消息描述字段组 (`fields`)
|
||||
|
||||
必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。关于 `Field` 对象的定义详见后文 "field 字段" 章节。
|
||||
必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。
|
||||
关于 `Field` 对象的定义详见后文 ["消息描述字段"](#%E6%B6%88%E6%81%AF%E6%8F%8F%E8%BF%B0%E5%AD%97%E6%AE%B5) 章节。
|
||||
|
||||
### 消息元数据 (`metadata`)
|
||||
|
||||
@ -175,7 +176,7 @@ type Location = {
|
||||
type UserData = Record<string, any>
|
||||
```
|
||||
|
||||
## 消息描述字段 (fields)
|
||||
## 消息描述字段
|
||||
|
||||
### 标识符 (`id`)
|
||||
|
||||
Reference in New Issue
Block a user