x
This commit is contained in:
242
READMD.md
242
READMD.md
@ -1,37 +1,62 @@
|
|||||||
# WH Telemetry Protocol
|
# WH Telemetry Protocol
|
||||||
|
|
||||||
...
|
WH Telemetry Protocol（简称 WHTP）是一套以 JSON 为载体的遥测数据上行协议，强调自描述能力与轻量化设计，适用于物联网设备与云端之间的高效数据传输。
|
||||||
|
|
||||||
## 总览
|
## 总览
|
||||||
|
|
||||||
...
|
WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描述消息本身及其环境；`fields` 数组承载具体测量项。根级字段概览如下：
|
||||||
|
|
||||||
|
| 字段 | 必选 | 类型 | 说明 |
|
||||||
|
| --------- | ---- | --------------- | ---------------------------------------------- |
|
||||||
|
| version | 是 | number | 协议主版本号 |
|
||||||
|
| msg_type | 是 | string | 消息类别，目前仅 `"telemetry"` |
|
||||||
|
| mode | 否 | string | 工作模式，`"descriptive"`（默认）或 `"strict"` |
|
||||||
|
| dev_id | 是 | string | 设备唯一标识（UUID v4） |
|
||||||
|
| dev_type | 否 | string / object | 设备型号标识 |
|
||||||
|
| timestamp | 是 | Timestamp | 消息生成时刻 |
|
||||||
|
| fields | 是 | Field[] | 采集字段数组 |
|
||||||
|
| metadata | 否 | object | 消息级元数据 |
|
||||||
|
|
||||||
## 消息字段
|
## 消息字段
|
||||||
|
|
||||||
### Version (`version`)
|
### Version (`version`)
|
||||||
|
|
||||||
...
|
必填。正整数，仅表示协议主版本号。当前版本为 **1**。
|
||||||
|
|
||||||
### 消息类型 (`msg_type`)
|
### 消息类型 (`msg_type`)
|
||||||
|
|
||||||
|
必填。字符串。目前仅允许 `"telemetry"`，用于上传遥测数据。
|
||||||
|
|
||||||
### 消息模式 (`mode`)
|
### 消息模式 (`mode`)
|
||||||
|
|
||||||
仅 descriptive 有良好定义
|
可选，字符串，默认 `"descriptive"`。
|
||||||
... (TODO)
|
|
||||||
|
* `descriptive` —— 自描述模式，允许在字段 `metadata` 中携带全部上下文信息，消息本身即可被独立解析。
|
||||||
|
* `strict` —— 严格模式，不允许出现字段级 `metadata`，字段定义需通过外部文档约定，适用于带宽受限或固定 Schema 场景。(目前无实际意义, 需要与二进制协议配合)
|
||||||
|
|
||||||
### 设备 ID (`dev_id`)
|
### 设备 ID (`dev_id`)
|
||||||
|
|
||||||
UUID
|
必填。设备唯一标识，采用 UUID v4 格式（如 `148413b4-c352-49a9-9c48-9d15276a99e7`），在设备生命周期内保持不变。
|
||||||
|
|
||||||
### 设备类型 (`dev_type`)
|
### 设备类型 (`dev_type`)
|
||||||
|
|
||||||
...
|
```typescript
|
||||||
|
type DeviceType = string | { type_id: string } | { type_name: string }
|
||||||
|
```
|
||||||
|
|
||||||
|
可选。用于标识设备类别或型号。支持三种写法：
|
||||||
|
|
||||||
|
1. **字符串**：例如 `"device_type_name"`；与 `{ "type_name": string }` 等价
|
||||||
|
2. **对象** `{ "type_id": UUID }`；UUID 为设备型号的唯一标识, 由平台分配
|
||||||
|
3. **对象** `{ "type_name": string }`。
|
||||||
|
|
||||||
|
以上三种写法在语义上等价，由数据生产方按需选择。
|
||||||
|
|
||||||
### 消息时间戳 (`timestamp`)
|
### 消息时间戳 (`timestamp`)
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
type Timestamp =
|
type Timestamp =
|
||||||
| number // UNIX seconds (default), same as `unix_s`
|
| number // UNIX seconds (default), same as `{ unix_s: number }`
|
||||||
| { unix_s: number }
|
| { unix_s: number }
|
||||||
| { unix_ms: number }
|
| { unix_ms: number }
|
||||||
| { unix_us: number }
|
| { unix_us: number }
|
||||||
@ -41,53 +66,100 @@ type Timestamp =
|
|||||||
|
|
||||||
### field 字段 (`fields`)
|
### field 字段 (`fields`)
|
||||||
|
|
||||||
see ...
|
必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。关于 `Field` 对象的定义详见后文 "field 字段" 章节。
|
||||||
|
|
||||||
### 消息元数据 (`metadata`)
|
### 消息元数据 (`metadata`)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface MessageMetadata {
|
||||||
|
enums?: EnumDefinition[];
|
||||||
|
location?: Location;
|
||||||
|
battery?: number;
|
||||||
|
seq?: number;
|
||||||
|
user?: Record<string, any>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
#### 全局枚举 (`enums`)
|
#### 全局枚举 (`enums`)
|
||||||
|
|
||||||
See data type and enum section
|
可选。全局枚举定义表，用于在字段 `metadata.data_type` 中以 `enum:<id>` 形式引用。
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
type EnumDefinition = { id: string; value: Record<string, number> };
|
||||||
|
```
|
||||||
|
|
||||||
|
示例：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
"metadata": {
|
||||||
|
"enums": [
|
||||||
|
{
|
||||||
|
"id": "air_quality",
|
||||||
|
"value": { "good": 1, "moderate": 2, "bad": 3 }
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
#### 位置信息 (`location`)
|
#### 位置信息 (`location`)
|
||||||
|
|
||||||
...
|
可选。表示消息采集时的设备地理位置：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"coordinates": [24.123456, 120.123456], // 纬度、经度（度）
|
||||||
|
"coordinate_system": "wgs84", // 可选，指定坐标系, 默认 "gcj02" 可选项为 wgs84, gcj02, bd09
|
||||||
|
"accuracy": 10, // 可选，水平精度（米）
|
||||||
|
"altitude": 100 // 可选，海拔高度（米）
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
#### 电量 (`battery`)
|
#### 电量 (`battery`)
|
||||||
|
|
||||||
...
|
可选。数字，范围 0–100，对应设备剩余电量百分比。
|
||||||
|
|
||||||
#### 序列号 (`seq`)
|
#### 序列号 (`seq`)
|
||||||
|
|
||||||
...
|
可选。无符号整数。每上传一条消息递增 1，用于检测丢包或乱序。达到上限后循环计数（默认为 32 位无符号整数回绕）。
|
||||||
|
|
||||||
#### 用户自定义信息 (`user`)
|
#### 用户自定义信息 (`user`)
|
||||||
|
|
||||||
...
|
可选。任意键值对，为数据生产方保留的自定义信息区：
|
||||||
|
|
||||||
## field 字段
|
## field 字段
|
||||||
|
|
||||||
### 标识符 (`id`)
|
### 标识符 (`id`)
|
||||||
|
|
||||||
... (TODO, just like symbol name convention in common programming languages)
|
必填。ASCII 字符串，仅允许字母、数字与下划线，且不得以数字开头。长度建议 1–64 字符。例如 `temperature_sensor`。
|
||||||
|
|
||||||
### 值 (`value`)
|
### 值 (`value`)
|
||||||
|
|
||||||
符合 `DataType` 的值 (见 `data_type` 章节)
|
字段实际测量值，其类型必须与 `metadata.data_type` 完全对应，形态分三类：
|
||||||
|
|
||||||
|
1. **标量** — `string | number | boolean | enum`
|
||||||
|
```jsonc
|
||||||
|
"value": 42
|
||||||
|
```
|
||||||
|
2. **等间隔数组 (array)** — `T[]`，通过 `sample_interval` 指定采样间隔
|
||||||
|
```jsonc
|
||||||
|
"value": [1, 2, 3],
|
||||||
|
"metadata": { "data_type": "array<number>", "sample_interval": 0.5 }
|
||||||
|
```
|
||||||
|
3. **非等间隔（irregular）** — `{ v: T[], t: Timestamp[] }`
|
||||||
|
```jsonc
|
||||||
|
"value": { "v": [1,2,3], "t": [1715145600,1715145601,1715145603] },
|
||||||
|
"metadata": { "data_type": "irregular<number>" }
|
||||||
|
```
|
||||||
|
`t` 数组必须与 `v` 数组长度相同, 且 `t` 数组中的时间戳必须严格递增, 否则会被视为非法数据
|
||||||
|
|
||||||
|
`null` 与 `undefined` 不被支持，嵌套数组（如 `array<array<number>>`）亦非法。
|
||||||
|
|
||||||
### 元数据 (`metadata`)
|
### 元数据 (`metadata`)
|
||||||
|
|
||||||
#### 数据类型
|
#### 数据类型 (`data_type`)
|
||||||
|
|
||||||
##### 枚举类型 (`enums`)
|
##### 枚举类型 (`enums`)
|
||||||
|
|
||||||
```typescript
|
|
||||||
type EnumDefinition = {
|
|
||||||
id: string,
|
|
||||||
value: Record<string, number>
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```haskell
|
```haskell
|
||||||
newtype Enum = number
|
newtype Enum = number
|
||||||
```
|
```
|
||||||
@ -135,36 +207,138 @@ type DataType =
|
|||||||
|
|
||||||
#### 标签 (`label`)
|
#### 标签 (`label`)
|
||||||
|
|
||||||
UTF-8 字符串
|
可选。字段展示名，UTF-8 字符串，便于人机界面直观呈现。
|
||||||
|
|
||||||
|
示例：`"label": "温度"`
|
||||||
|
|
||||||
#### 错误码 (`error_code`)
|
#### 错误码 (`error_code`)
|
||||||
|
|
||||||
...
|
可选。非零整数。0 表示无错误；其他值与以下错误码表对应，用于描述测量异常。
|
||||||
|
|
||||||
|
| 代码 | 分类 | 名称 | 描述 |
|
||||||
|
| ---------- | ---------- | --------------------- | -------------------------------------------------------- |
|
||||||
|
| 0 | 通用 | OK | 无错误（**不应在 `error_code` 字段出现**，仅表字段正常） |
|
||||||
|
| 1 | 通用 | UNKNOWN_ERROR | 未知错误，无法归类 |
|
||||||
|
| 2 | 通用 | UNSUPPORTED_DATA_TYPE | 不支持的数据类型或格式 |
|
||||||
|
| 3 | 通用 | INVALID_VALUE | 字段值非法（超范围、格式错等） |
|
||||||
|
| 16 | 设备 | DEVICE_BUSY | 设备繁忙，暂无法提供数据 |
|
||||||
|
| 17 | 设备 | DEVICE_INIT_FAILED | 设备初始化失败 |
|
||||||
|
| 32 | 传输 | PACKET_LOST | 报文丢失（重传失败） |
|
||||||
|
| 33 | 传输 | CRC_ERROR | 校验和 / CRC 错误 |
|
||||||
|
| 48 | 供电 | LOW_BATTERY | 电量过低，测量值可能不可靠 |
|
||||||
|
| 64 | 传感器 | SENSOR_DISCONNECTED | 传感器掉线或未接入 |
|
||||||
|
| 65 | 传感器 | SENSOR_MALFUNCTION | 传感器故障（无响应、数据乱流等） |
|
||||||
|
| 66 | 传感器 | SENSOR_OUT_OF_RANGE | 超出测量范围 |
|
||||||
|
| 80 | 校准 | CALIBRATION_REQUIRED | 需要校准或校准过期 |
|
||||||
|
| 96 | 存储 | STORAGE_FULL | 本地存储空间不足 |
|
||||||
|
| 112 | GNSS | GPS_FIX_LOST | GNSS 信号丢失，无位置信息 |
|
||||||
|
| 128–511 | 预留 | — | 预留给未来通用错误 |
|
||||||
|
| 512–1023 | 应用 | — | 留给具体应用 / 产品线自定义 |
|
||||||
|
| 1024–65535 | 厂商自定义 | — | 厂商或项目私有错误码区间 |
|
||||||
|
|
||||||
#### 错误信息 (`error_msg`)
|
#### 错误信息 (`error_msg`)
|
||||||
|
|
||||||
...
|
可选。UTF-8 字符串，对 `error_code` 进行人类可读的补充说明。
|
||||||
|
|
||||||
#### 置信度 (`confidence`)
|
#### 置信度 (`confidence`)
|
||||||
|
|
||||||
...
|
```typescript
|
||||||
|
type Confidence = number | number[]
|
||||||
|
```
|
||||||
|
|
||||||
|
数组形式 (`number[]`) 仅对数组 (等间隔/非等间隔) 有意义, 表示每个采样点的置信度, 其长度应与采样点数量相同; 若不指定, 则默认为 1
|
||||||
|
|
||||||
#### 采样间隔 (`sample_interval`)
|
#### 采样间隔 (`sample_interval`)
|
||||||
|
|
||||||
仅对 `ArrayType` 有意义, 建议每个 `ArrayType` 都显式填写该字段, 若不指定, 则默认为 1s
|
可选。采样间隔, 用于描述 `value` 为等间隔数组时, 数组中每个元素的时间间隔 (建议所有等间隔数组都显式填写该字段)
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
type SampleIntervalObject = { ms?: number, s?: number, m?: number, h?: number, d?: number, w?: number }
|
type TimeDelta = { ms?: number, s?: number, m?: number, h?: number, d?: number, w?: number }
|
||||||
type SampleInterval =
|
type SampleInterval =
|
||||||
| number // seconds
|
| number // seconds
|
||||||
| SampleIntervalObject
|
| TimeDelta
|
||||||
```
|
```
|
||||||
|
|
||||||
- 若使用 `SampleIntervalObject`, 则总采样间隔为
|
- 若使用 `TimeDelta`, 则总采样间隔为
|
||||||
`ms + s * 1000 + m * 60 * 1000 + h * 60 * 60 * 1000 + d * 24 * 60 * 60 * 1000 + w * 7 * 24 * 60 * 60 * 1000`ms (各个 field 不允许小数)
|
`ms + s * 1000 + m * 60 * 1000 + h * 60 * 60 * 1000 + d * 24 * 60 * 60 * 1000 + w * 7 * 24 * 60 * 60 * 1000`ms (各个 field 不允许小数)
|
||||||
- 若使用 `number`, 则表示采样间隔为 `number` 秒 (允许小数)
|
- 若使用 `number`, 则表示采样间隔为 `number` 秒 (允许小数)
|
||||||
- 若不指定, 则默认为 1s
|
|
||||||
|
若不指定, 则默认为 1s
|
||||||
|
|
||||||
|
示例：`"sample_interval": 0.5`（两次采样间隔 0.5 秒）
|
||||||
|
|
||||||
#### 单位 (`unit`)
|
#### 单位 (`unit`)
|
||||||
|
|
||||||
建议使用 [UCUM](https://ucum.org/ucum)
|
可选。测量值单位。推荐使用 [UCUM](https://ucum.org/ucum) 码（如 `"Cel"` 代表摄氏度），也支持自由字符串。
|
||||||
|
|
||||||
|
示例：`"unit": "Cel"`
|
||||||
|
|
||||||
|
#### 内联枚举 (`enum`)
|
||||||
|
|
||||||
|
可选。当 `data_type` 为 `enum:this` 及其衍生类型时, 用于定义内联枚举值
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
type InlineEnum = Record<string, number>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 用户自定义信息 (`user`)
|
||||||
|
|
||||||
|
可选。任意键值对，为数据生产方保留的自定义信息区：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
type UserData = Record<string, any>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 伪代码类型定义
|
||||||
|
|
||||||
|
以下以 TypeScript 伪代码展示核心结构，帮助快速对接实现：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 时间戳
|
||||||
|
type Timestamp =
|
||||||
|
| number // UNIX seconds
|
||||||
|
| { unix_s: number }
|
||||||
|
| { unix_ms: number }
|
||||||
|
| { unix_us: number }
|
||||||
|
| { unix_ns: number }
|
||||||
|
| { iso8601: string };
|
||||||
|
|
||||||
|
// 采样间隔
|
||||||
|
type SampleInterval = number | { ms?: number; s?: number; m?: number; h?: number; d?: number; w?: number };
|
||||||
|
|
||||||
|
// 枚举定义
|
||||||
|
type EnumDefinition = { id: string; value: Record<string, number> };
|
||||||
|
|
||||||
|
// Field 元数据
|
||||||
|
interface FieldMetadata {
|
||||||
|
data_type: string;
|
||||||
|
timestamp?: Timestamp;
|
||||||
|
sample_interval?: SampleInterval;
|
||||||
|
unit?: string;
|
||||||
|
label?: string;
|
||||||
|
confidence?: number | number[];
|
||||||
|
error_code?: number;
|
||||||
|
error_msg?: string;
|
||||||
|
enum?: Record<string, number>; // inline enum when data_type === "enum:this"
|
||||||
|
user?: Record<string, any>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Field
|
||||||
|
interface Field {
|
||||||
|
id: string;
|
||||||
|
value: DataType;
|
||||||
|
metadata: FieldMetadata;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 根消息
|
||||||
|
interface Message {
|
||||||
|
version: 1;
|
||||||
|
msg_type: "telemetry";
|
||||||
|
mode?: "descriptive" | "strict"; // 仅支持 descriptive 模式
|
||||||
|
dev_id: string;
|
||||||
|
dev_type?: string | { type_id: string } | { type_name: string };
|
||||||
|
timestamp: Timestamp;
|
||||||
|
fields: Field[];
|
||||||
|
metadata?: MessageMetadata;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|||||||
@ -171,7 +171,7 @@
|
|||||||
// defaults to 0 for non-error cases
|
// defaults to 0 for non-error cases
|
||||||
//
|
//
|
||||||
// well-defined error codes are in separate documentation
|
// well-defined error codes are in separate documentation
|
||||||
"error_code": 1001,
|
"error_code": 64,
|
||||||
// optional
|
// optional
|
||||||
// a custom error message
|
// a custom error message
|
||||||
"error_msg": "sensor disconnected",
|
"error_msg": "sensor disconnected",
|
||||||
|
|||||||
Reference in New Issue
Block a user