171 lines
2.9 KiB
Markdown
171 lines
2.9 KiB
Markdown
# WH Telemetry Protocol
|
|
|
|
...
|
|
|
|
## 总览
|
|
|
|
...
|
|
|
|
## 消息字段
|
|
|
|
### Version (`version`)
|
|
|
|
...
|
|
|
|
### 消息类型 (`msg_type`)
|
|
|
|
### 消息模式 (`mode`)
|
|
|
|
仅 descriptive 有良好定义
|
|
... (TODO)
|
|
|
|
### 设备 ID (`dev_id`)
|
|
|
|
UUID
|
|
|
|
### 设备类型 (`dev_type`)
|
|
|
|
...
|
|
|
|
### 消息时间戳 (`timestamp`)
|
|
|
|
```typescript
|
|
type Timestamp =
|
|
| number // UNIX seconds (default), same as `unix_s`
|
|
| { unix_s: number }
|
|
| { unix_ms: number }
|
|
| { unix_us: number }
|
|
| { unix_ns: number }
|
|
| { iso8601: string } // e.g. "2025-01-01T00:00:00Z"
|
|
```
|
|
|
|
### field 字段 (`fields`)
|
|
|
|
see ...
|
|
|
|
### 消息元数据 (`metadata`)
|
|
|
|
#### 全局枚举 (`enums`)
|
|
|
|
See data type and enum section
|
|
|
|
#### 位置信息 (`location`)
|
|
|
|
...
|
|
|
|
#### 电量 (`battery`)
|
|
|
|
...
|
|
|
|
#### 序列号 (`seq`)
|
|
|
|
...
|
|
|
|
#### 用户自定义信息 (`user`)
|
|
|
|
...
|
|
|
|
## field 字段
|
|
|
|
### 标识符 (`id`)
|
|
|
|
... (TODO, just like symbol name convention in common programming languages)
|
|
|
|
### 值 (`value`)
|
|
|
|
符合 `DataType` 的值 (见 `data_type` 章节)
|
|
|
|
### 元数据 (`metadata`)
|
|
|
|
#### 数据类型
|
|
|
|
##### 枚举类型 (`enums`)
|
|
|
|
```typescript
|
|
type EnumDefinition = {
|
|
id: string,
|
|
value: Record<string, number>
|
|
}
|
|
```
|
|
|
|
```haskell
|
|
newtype Enum = number
|
|
```
|
|
|
|
##### 原始型別 (`primitive`)
|
|
|
|
```haskell
|
|
type PrimitiveType = string | number | boolean
|
|
|
|
type ScalarType = string | number | boolean | Enum
|
|
type ArrayType T = T[] -- array<T>
|
|
type IrregularType T = { v: T[], t: Timestamp[] } -- irregular<T>
|
|
|
|
type DataType =
|
|
| ScalarType
|
|
| ArrayType ScalarType
|
|
| IrregularType ScalarType
|
|
```
|
|
|
|
##### 总结
|
|
|
|
所有合法的 `data_type` 如下:
|
|
|
|
```typescript
|
|
type DataType =
|
|
| "string"
|
|
| "number"
|
|
| "boolean"
|
|
| `enum:${string}` // global enum
|
|
| "enum:this" // inline enum
|
|
| `array<string>`
|
|
| `array<number>`
|
|
| `array<boolean>`
|
|
| `array<enum:${string}>`
|
|
| `array<enum:this>`
|
|
| `irregular<string>`
|
|
| `irregular<number>`
|
|
| `irregular<boolean>`
|
|
| `irregular<enum:${string}>`
|
|
| `irregular<enum:this>`
|
|
```
|
|
|
|
- `null` 和 `undefined` 是非法的
|
|
- 嵌套是非法的
|
|
|
|
#### 标签 (`label`)
|
|
|
|
UTF-8 字符串
|
|
|
|
#### 错误码 (`error_code`)
|
|
|
|
...
|
|
|
|
#### 错误信息 (`error_msg`)
|
|
|
|
...
|
|
|
|
#### 置信度 (`confidence`)
|
|
|
|
...
|
|
|
|
#### 采样间隔 (`sample_interval`)
|
|
|
|
仅对 `ArrayType` 有意义, 建议每个 `ArrayType` 都显式填写该字段, 若不指定, 则默认为 1s
|
|
|
|
```typescript
|
|
type SampleIntervalObject = { ms?: number, s?: number, m?: number, h?: number, d?: number, w?: number }
|
|
type SampleInterval =
|
|
| number // seconds
|
|
| SampleIntervalObject
|
|
```
|
|
|
|
- 若使用 `SampleIntervalObject`, 则总采样间隔为
|
|
`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` 秒 (允许小数)
|
|
- 若不指定, 则默认为 1s
|
|
|
|
#### 单位 (`unit`)
|
|
|
|
建议使用 [UCUM](https://ucum.org/ucum)
|