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:
@ -15,7 +15,7 @@ WH Telemetry Protocol(简称 **WHTP**)是一套面向物联网场景的 **JS
|
||||
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/) 定义。
|
||||
4. 参见 [schema.json](schema.json) 获取 [JSON Schema](https://json-schema.org/) 定义。使用 [ATLASSIAN JSON Schema Viewer](https://json-schema.app/view/%23?url=https%3A%2F%2Fweihua-iot.cn%2Fschema.json) 在线可视化/校验。
|
||||
|
||||
## 仓库结构
|
||||
|
||||
|
||||
24
schema.md
24
schema.md
@ -1,10 +1,22 @@
|
||||
# WH Telemetry Protocol Specification
|
||||
|
||||
WH Telemetry Protocol(简称 WHTP)是一套以 JSON 为载体的遥测数据上行协议,强调自描述能力与轻量化设计,适用于物联网设备与云端之间的高效数据传输。
|
||||
WH Telemetry Protocol(WHTP)是一套专为物联网场景设计的轻量级、强自描述性遥测数据上行协议,采用 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**。
|
||||
|
||||
Reference in New Issue
Block a user