From 03e20a7c87062795e97cf7717809529ef661c0c1 Mon Sep 17 00:00:00 2001 From: crosstyan Date: Mon, 7 Jul 2025 19:19:51 +0800 Subject: [PATCH] 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. --- README.md | 2 +- schema.md | 24 +++++++++++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 297c918..b570f1a 100644 --- a/README.md +++ b/README.md @@ -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) 在线可视化/校验。 ## 仓库结构 diff --git a/schema.md b/schema.md index 61732bc..7927916 100644 --- a/schema.md +++ b/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**。