Enhance WH Telemetry Protocol documentation in README.md and schema.md; clarify protocol features, message structure, and self-describing capabilities for improved understanding and usability.

This commit is contained in:
2025-07-07 19:19:51 +08:00
parent fb42ca777f
commit 03e20a7c87
2 changed files with 18 additions and 8 deletions

View File

@ -1,10 +1,22 @@
# WH Telemetry Protocol Specification
WH Telemetry Protocol简称 WHTP是一套以 JSON 为载体的遥测数据上行协议,强调自描述能力与轻量化设计,适用于物联网设备与云端之间的高效数据传输
WH Telemetry ProtocolWHTP是一套专为物联网场景设计的轻量级、强自描述性遥测数据上行协议,采用 JSON 作为数据承载格式。WHTP 面向传感器数据、遥测采集、边缘网关等设备与云端的数据交互,兼顾数据结构规范、易于解析与灵活拓展,适用于农业、环境监测、工业自动化等多种场景
## 总览
协议设计核心特点:
WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描述消息本身及其环境;`fields` 数组承载具体测量项。根级字段概览如下:
- 自描述:字段类型、单位、置信度、枚举、错误信息等全部可内嵌于消息,无需依赖外部 schema 即可独立解析
- 结构统一:所有遥测消息采用统一的数据结构,便于前端/平台/存储适配与二次开发
- 严格类型:禁止 null、嵌套数组所有值类型需显式声明保证数据一致性与可校验性
- 批量与单点兼容支持标量、等间隔数组与非等间隔irregular三种采样模式灵活适配各类采集需求
- 可扩展性预留元数据metadata与用户自定义信息user支持平台与业务个性化扩展
- 错误与置信机制:内建错误码、错误信息与置信度表达,方便数据质量管理与自动化校验
消息结构总览:
- 根级字段:描述消息身份、设备、时间、环境等全局信息
- 字段组fields每个测量项field携带唯一 ID、测量值value、类型元信息metadata
## 根级字段
| 字段 | 必选 | 类型 | 说明 |
| --------- | ---- | --------------- | ---------------------------------------------- |
@ -13,12 +25,10 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描
| mode | 否 | string | 工作模式,`"descriptive"`(默认)或 `"strict"` |
| dev_id | 是 | string | 设备唯一标识NanoID |
| dev_type | 是 | string / object | 设备型号标识 |
| timestamp | 是 | Timestamp | 消息生成时刻 |
| fields | 是 | Field[] | 采集字段数组 |
| timestamp | 是 | `Timestamp` | 消息生成时刻 |
| fields | 是 | `Field[]` | 采集字段数组 |
| metadata | 否 | object | 消息级元数据 |
## 根级字段
### Version (`version`)
必填。正整数,仅表示协议主版本号。当前版本为 **1**