Update example.jsonc timestamps and correct location coordinates order in README.md; enhance documentation clarity and add notes for timestamp usage.
This commit is contained in:
106
READMD.md
106
READMD.md
@ -32,7 +32,7 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描
|
||||
可选，字符串，默认 `"descriptive"`。
|
||||
|
||||
* `descriptive` —— 自描述模式，允许在字段 `metadata` 中携带全部上下文信息，消息本身即可被独立解析。
|
||||
* `strict` —— 严格模式，不允许出现字段级 `metadata`，字段定义需通过外部文档约定，适用于带宽受限或固定 Schema 场景。(目前无实际意义, 需要与二进制协议配合)
|
||||
* `strict` (RFU, reserved for future use) —— 严格模式，不允许出现字段级 `metadata`，字段定义需通过外部文档约定，适用于带宽受限或固定 Schema 场景。(目前无实际意义, 需要与二进制协议配合)
|
||||
|
||||
### 设备 ID (`dev_id`)
|
||||
|
||||
@ -50,9 +50,14 @@ type DeviceType = string | { type_id: string } | { type_name: string }
|
||||
2. **对象** `{ "type_id": UUID }`；UUID 为设备型号的唯一标识, 由平台分配
|
||||
3. **对象** `{ "type_name": string }`。
|
||||
|
||||
以上三种写法在语义上等价，由数据生产方按需选择。
|
||||
> [!NOTE]
|
||||
>
|
||||
> 以上三种写法在语义上等价, 由数据生产方按需选择
|
||||
>
|
||||
> - 对于长期稳定的系统, 推荐使用 `{ "type_id": UUID }` 格式, 作为稳定的唯一标识符
|
||||
> - 对于临时场景, 可以使用 `string` 或 `{ "type_name": string }` 格式
|
||||
|
||||
### 消息时间戳 (`timestamp`)
|
||||
### 根级时间戳 (`timestamp`)
|
||||
|
||||
```typescript
|
||||
type Timestamp =
|
||||
@ -72,11 +77,14 @@ type Timestamp =
|
||||
- `unix_ms` → UNIX 毫秒
|
||||
- `unix_us` → UNIX 微秒
|
||||
- `unix_ns` → UNIX 纳秒
|
||||
- `iso8601` → ISO8601 标准格式（推荐 UTC，Z 结尾）
|
||||
- `iso8601` → [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) 标准格式（必须为 UTC，以 Z 结尾或包含 +00:00 时区偏移）
|
||||
|
||||
> [!WARNING]
|
||||
> `"timestamp": "2025-01-01T00:00:00Z"` 为非法, 应使用 `"timestamp": { "iso8601": "2025-01-01T00:00:00Z" }` 或 `"timestamp": 1715145600`
|
||||
|
||||
> [!NOTE]
|
||||
> 根级 (root-level) 时间戳表示消息生成或入队时刻, 字段级 (field-level) 时间戳表示实际数据采样时刻, 应使用字段级时间戳进行所有时间序列分析
|
||||
|
||||
### field 字段 (`fields`)
|
||||
|
||||
必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。关于 `Field` 对象的定义详见后文 "field 字段" 章节。
|
||||
@ -100,10 +108,11 @@ interface MessageMetadata {
|
||||
可选。全局枚举定义表，用于在字段 `fields[*].metadata.data_type` 中以 `enum:<id>` 形式引用。
|
||||
|
||||
```typescript
|
||||
type EnumDefinition = { id: string; value: Record<string, number> };
|
||||
type InlineEnum = Record<string, number>
|
||||
type EnumDefinition = { id: string; value: InlineEnum };
|
||||
```
|
||||
|
||||
示例：
|
||||
示例
|
||||
|
||||
```jsonc
|
||||
"metadata": {
|
||||
@ -116,16 +125,37 @@ type EnumDefinition = { id: string; value: Record<string, number> };
|
||||
}
|
||||
```
|
||||
|
||||
等价于
|
||||
|
||||
```cpp
|
||||
enum class AirQuality {
|
||||
GOOD = 1,
|
||||
MODERATE = 2,
|
||||
BAD = 3,
|
||||
};
|
||||
```
|
||||
|
||||
#### 位置信息 (`location`)
|
||||
|
||||
可选。表示消息采集时的设备地理位置：
|
||||
可选。表示消息采集时的设备地理位置
|
||||
|
||||
```typescript
|
||||
type Location = {
|
||||
coordinates: [number, number]; // 经度 (longitude)、纬度 (latitude)（度）; 顺序不可颠倒
|
||||
coordinate_system?: "wgs84" | "gcj02" | "bd09"; // 可选，指定坐标系, 默认 "gcj02"
|
||||
accuracy?: number; // 可选，水平精度（米）
|
||||
altitude?: number; // 可选，海拔高度（米）
|
||||
}
|
||||
```
|
||||
|
||||
示例
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"coordinates": [24.123456, 120.123456], // 纬度、经度（度）
|
||||
"coordinate_system": "wgs84", // 可选，指定坐标系, 默认 "gcj02" 可选项为 wgs84, gcj02, bd09
|
||||
"accuracy": 10, // 可选，水平精度（米）
|
||||
"altitude": 100 // 可选，海拔高度（米）
|
||||
"coordinates": [120.123456, 24.123456], // 经度、纬度（度）
|
||||
"coordinate_system": "wgs84",
|
||||
"accuracy": 10,
|
||||
"altitude": 100
|
||||
}
|
||||
```
|
||||
|
||||
@ -139,7 +169,11 @@ type EnumDefinition = { id: string; value: Record<string, number> };
|
||||
|
||||
#### 用户自定义信息 (`user`)
|
||||
|
||||
可选。任意键值对，为数据生产方保留的自定义信息区：
|
||||
可选。任意键值对，为数据生产方保留的自定义信息区
|
||||
|
||||
```typescript
|
||||
type UserData = Record<string, any>
|
||||
```
|
||||
|
||||
## 消息描述字段 (fields)
|
||||
|
||||
@ -167,7 +201,7 @@ type EnumDefinition = { id: string; value: Record<string, number> };
|
||||
```
|
||||
`t` 数组必须与 `v` 数组长度相同, 且 `t` 数组中的时间戳必须严格递增, 否则会被视为非法数据
|
||||
|
||||
`null` 与 `undefined` 不被支持，嵌套数组（如 `array<array<number>>`）亦非法。
|
||||
`null` 与 `undefined` 不被支持，嵌套数组（如 `array<array<number>>`）亦为非法。
|
||||
|
||||
### 元数据 (`metadata`)
|
||||
|
||||
@ -283,26 +317,26 @@ type BatchType T = ArrayType T | IrregularType T
|
||||
|
||||
可选。非零整数。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 | 厂商自定义 | — | 厂商或项目私有错误码区间 |
|
||||
| 代码 | 分类 | 名称 | 描述 |
|
||||
| ---------- | ---------- | --------------------- | ------------------------------------------ |
|
||||
| 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`)
|
||||
|
||||
@ -321,11 +355,15 @@ type Confidence = number | number[]
|
||||
|
||||
置信度的取值范围为 0 至 1，其中 0 表示完全不可信，1 表示完全可信（100%）。
|
||||
|
||||
> [!NOTE]
|
||||
> 当一个字段包含非零的 `error_code` 时, 强烈建议将置信度设置为 0 以表示该字段值不可靠
|
||||
|
||||
> [!WARNING]
|
||||
> - 对于单值（scalar）数据，不应填写数组形式的置信度，若填写则无意义，解析器将会忽略
|
||||
> - 对于批量数据，既可填写单一置信度（所有采样点共享），也可填写置信度数组（每个采样点单独指定）
|
||||
> - 如未指定 confidence 字段，则默认所有采样点的置信度为 1
|
||||
|
||||
|
||||
#### 采样间隔 (`sample_interval`)
|
||||
|
||||
可选。采样间隔, 用于描述 `value` 为等间隔数组时, 数组中每个元素的时间间隔 (建议所有等间隔数组都显式填写该字段)
|
||||
@ -414,7 +452,7 @@ interface Field {
|
||||
interface Message {
|
||||
version: 1;
|
||||
msg_type: "telemetry";
|
||||
mode?: "descriptive" | "strict"; // 仅支持 descriptive 模式
|
||||
mode?: "descriptive" | "strict"; // 目前仅支持 descriptive 模式
|
||||
dev_id: string;
|
||||
dev_type?: string | { type_id: string } | { type_name: string };
|
||||
timestamp: Timestamp;
|
||||
|
||||
Reference in New Issue
Block a user