x

READMD.md

@@ -0,0 +1,170 @@
+# 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)