whtp/READMD.md

WH Telemetry Protocol

...

总览

...

消息字段

Version (version)

...

消息类型 (msg_type)

消息模式 (mode)

仅 descriptive 有良好定义 ... (TODO)

设备 ID (dev_id)

UUID

设备类型 (dev_type)

...

消息时间戳 (timestamp)

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)

type EnumDefinition = {
    id: string,
    value: Record<string, number>
}

newtype Enum = number

原始型別 (primitive)

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 如下:

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

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 * 1000ms (各个 field 不允许小数)
• 若使用 number, 则表示采样间隔为 number 秒 (允许小数)
• 若不指定, 则默认为 1s

单位 (unit)

建议使用 UCUM