whtp/README.md

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 补充说明，亦可轻松扩展至 HTTP、WebSocket、CoAP 等。

快速上手

1. 阅读主规范 schema.md，了解字段定义与类型系统。
2. 查看 example.jsonc 获取完整示例。
3. 若采用 MQTT 作为载体，参考 mqtt.md 的主题、QoS、Retain 与连接安全实践。
4. 参见 schema.json 获取 JSON Schema 定义。

仓库结构

路径	说明
schema.md	WHTP 主规范（协议字段与类型定义）
mqtt.md	MQTT 传输层补充说明
example.jsonc	完整示例消息，含字段注释
README.md	当前文件，项目概览