# WH Telemetry Protocol（WHTP）

> A lightweight, self-describing telemetry protocol based on UTF-8 JSON

WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JSON 遥测上行协议**。它强调 **自描述能力** 与 **轻量化设计**，在带宽、功耗与开发效率之间取得平衡，帮助设备端与云端快速完成数据对接。

## 特性亮点

- **自描述（Self-descriptive）**：数据类型、单位、采样间隔等元信息随报文一并上送，脱离外部 Schema 亦可独立解析。
- **批量数据友好**：内置等间隔 `array<T>` 与非等间隔 `irregular<T>` 两种批量格式，可显著降低消息数。
- **枚举支持**：全局或内联枚举可读性强，兼具类型安全。

## 快速上手

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`     | 当前文件，项目概览                |