crosstyan/whtp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update example.jsonc timestamps and correct location coordinates order in README.md; enhance documentation clarity and add notes for timestamp usage.

Browse Source
This commit is contained in:
crosstyan
2025-07-07 17:50:11 +08:00
parent e42e3ca665
commit ff4d97f0cc
3 changed files with 80 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
READMD.md
View File

@ -32,7 +32,7 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描
可选，字符串，默认 `"descriptive"`。 可选，字符串，默认 `"descriptive"`。
* `descriptive` —— 自描述模式，允许在字段 `metadata` 中携带全部上下文信息，消息本身即可被独立解析。 * `descriptive` —— 自描述模式，允许在字段 `metadata` 中携带全部上下文信息，消息本身即可被独立解析。
* `strict` —— 严格模式，不允许出现字段级 `metadata`，字段定义需通过外部文档约定，适用于带宽受限或固定 Schema 场景。(目前无实际意义, 需要与二进制协议配合) * `strict` (RFU, reserved for future use) —— 严格模式，不允许出现字段级 `metadata`，字段定义需通过外部文档约定，适用于带宽受限或固定 Schema 场景。(目前无实际意义, 需要与二进制协议配合)
### 设备 ID (`dev_id`) ### 设备 ID (`dev_id`)
@ -50,9 +50,14 @@ type DeviceType = string | { type_id: string } | { type_name: string }
2. **对象** `{ "type_id": UUID }`；UUID 为设备型号的唯一标识, 由平台分配 2. **对象** `{ "type_id": UUID }`；UUID 为设备型号的唯一标识, 由平台分配
3. **对象** `{ "type_name": string }`。 3. **对象** `{ "type_name": string }`。
以上三种写法在语义上等价，由数据生产方按需选择。 > [!NOTE]
>
> 以上三种写法在语义上等价, 由数据生产方按需选择
>
> - 对于长期稳定的系统, 推荐使用 `{ "type_id": UUID }` 格式, 作为稳定的唯一标识符
> - 对于临时场景, 可以使用 `string` 或 `{ "type_name": string }` 格式
### 消息时间戳 (`timestamp`) ### 根级时间戳 (`timestamp`)
```typescript ```typescript
type Timestamp = type Timestamp =
@ -72,11 +77,14 @@ type Timestamp =
- `unix_ms` → UNIX 毫秒 - `unix_ms` → UNIX 毫秒
- `unix_us` → UNIX 微秒 - `unix_us` → UNIX 微秒
- `unix_ns` → UNIX 纳秒 - `unix_ns` → UNIX 纳秒
- `iso8601` → ISO8601 标准格式（推荐 UTC，Z 结尾） - `iso8601` → [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) 标准格式（必须为 UTC，以 Z 结尾或包含 +00:00 时区偏移）
> [!WARNING] > [!WARNING]
> `"timestamp": "2025-01-01T00:00:00Z"` 为非法, 应使用 `"timestamp": { "iso8601": "2025-01-01T00:00:00Z" }` 或 `"timestamp": 1715145600` > `"timestamp": "2025-01-01T00:00:00Z"` 为非法, 应使用 `"timestamp": { "iso8601": "2025-01-01T00:00:00Z" }` 或 `"timestamp": 1715145600`
> [!NOTE]
> 根级 (root-level) 时间戳表示消息生成或入队时刻, 字段级 (field-level) 时间戳表示实际数据采样时刻, 应使用字段级时间戳进行所有时间序列分析
### field 字段 (`fields`) ### field 字段 (`fields`)
必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。关于 `Field` 对象的定义详见后文 "field 字段" 章节。 必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。关于 `Field` 对象的定义详见后文 "field 字段" 章节。
@ -100,10 +108,11 @@ interface MessageMetadata {
可选。全局枚举定义表，用于在字段 `fields[*].metadata.data_type` 中以 `enum:<id>` 形式引用。 可选。全局枚举定义表，用于在字段 `fields[*].metadata.data_type` 中以 `enum:<id>` 形式引用。
```typescript ```typescript
type EnumDefinition = { id: string; value: Record<string, number> }; type InlineEnum = Record<string, number>
type EnumDefinition = { id: string; value: InlineEnum };
``` ```
示例： 示例
```jsonc ```jsonc
"metadata": { "metadata": {
@ -116,16 +125,37 @@ type EnumDefinition = { id: string; value: Record<string, number> };
} }
``` ```
等价于
```cpp
enum class AirQuality {
GOOD = 1,
MODERATE = 2,
BAD = 3,
};
```
#### 位置信息 (`location`) #### 位置信息 (`location`)
可选。表示消息采集时的设备地理位置： 可选。表示消息采集时的设备地理位置
```typescript
type Location = {
coordinates: [number, number]; // 经度 (longitude)、纬度 (latitude)（度）; 顺序不可颠倒
coordinate_system?: "wgs84" | "gcj02" | "bd09"; // 可选，指定坐标系, 默认 "gcj02"
accuracy?: number; // 可选，水平精度（米）
altitude?: number; // 可选，海拔高度（米）
}
```
示例
```jsonc ```jsonc
{ {
"coordinates": [24.123456, 120.123456], // 纬度、经度（度） "coordinates": [120.123456, 24.123456], // 经度、纬度（度）
"coordinate_system": "wgs84", // 可选，指定坐标系, 默认 "gcj02" 可选项为 wgs84, gcj02, bd09 "coordinate_system": "wgs84",
"accuracy": 10, // 可选，水平精度（米） "accuracy": 10,
"altitude": 100 // 可选，海拔高度（米） "altitude": 100
} }
``` ```
@ -139,7 +169,11 @@ type EnumDefinition = { id: string; value: Record<string, number> };
#### 用户自定义信息 (`user`) #### 用户自定义信息 (`user`)
可选。任意键值对，为数据生产方保留的自定义信息区： 可选。任意键值对，为数据生产方保留的自定义信息区
```typescript
type UserData = Record<string, any>
```
## 消息描述字段 (fields) ## 消息描述字段 (fields)
@ -167,7 +201,7 @@ type EnumDefinition = { id: string; value: Record<string, number> };
``` ```
`t` 数组必须与 `v` 数组长度相同, 且 `t` 数组中的时间戳必须严格递增, 否则会被视为非法数据 `t` 数组必须与 `v` 数组长度相同, 且 `t` 数组中的时间戳必须严格递增, 否则会被视为非法数据
`null` 与 `undefined` 不被支持，嵌套数组（如 `array<array<number>>`）亦非法。 `null` 与 `undefined` 不被支持，嵌套数组（如 `array<array<number>>`）亦为非法。
### 元数据 (`metadata`) ### 元数据 (`metadata`)
@ -283,26 +317,26 @@ type BatchType T = ArrayType T | IrregularType T
可选。非零整数。0 表示无错误；其他值与以下错误码表对应，用于描述测量异常。 可选。非零整数。0 表示无错误；其他值与以下错误码表对应，用于描述测量异常。
| 代码 | 分类 | 名称 | 描述 | | 代码 | 分类 | 名称 | 描述 |
| ---------- | ---------- | --------------------- | -------------------------------------------------------- | | ---------- | ---------- | --------------------- | ------------------------------------------ |
| 0 | 通用 | OK | 无错误（**不应在 `error_code` 字段出现**，仅表字段正常） | | 0 | 通用 | OK | 无错误（**不应在 `error_code` 字段出现**） |
| 1 | 通用 | UNKNOWN_ERROR | 未知错误，无法归类 | | 1 | 通用 | UNKNOWN_ERROR | 未知错误，无法归类 |
| 2 | 通用 | UNSUPPORTED_DATA_TYPE | 不支持的数据类型或格式 | | 2 | 通用 | UNSUPPORTED_DATA_TYPE | 不支持的数据类型或格式 |
| 3 | 通用 | INVALID_VALUE | 字段值非法（超范围、格式错等） | | 3 | 通用 | INVALID_VALUE | 字段值非法（超范围、格式错等） |
| 16 | 设备 | DEVICE_BUSY | 设备繁忙，暂无法提供数据 | | 16 | 设备 | DEVICE_BUSY | 设备繁忙，暂无法提供数据 |
| 17 | 设备 | DEVICE_INIT_FAILED | 设备初始化失败 | | 17 | 设备 | DEVICE_INIT_FAILED | 设备初始化失败 |
| 32 | 传输 | PACKET_LOST | 报文丢失（重传失败） | | 32 | 传输 | PACKET_LOST | 报文丢失（重传失败） |
| 33 | 传输 | CRC_ERROR | 校验和 / CRC 错误 | | 33 | 传输 | CRC_ERROR | 校验和 / CRC 错误 |
| 48 | 供电 | LOW_BATTERY | 电量过低，测量值可能不可靠 | | 48 | 供电 | LOW_BATTERY | 电量过低，测量值可能不可靠 |
| 64 | 传感器 | SENSOR_DISCONNECTED | 传感器掉线或未接入 | | 64 | 传感器 | SENSOR_DISCONNECTED | 传感器掉线或未接入 |
| 65 | 传感器 | SENSOR_MALFUNCTION | 传感器故障（无响应、数据乱流等） | | 65 | 传感器 | SENSOR_MALFUNCTION | 传感器故障（无响应、数据乱流等） |
| 66 | 传感器 | SENSOR_OUT_OF_RANGE | 超出测量范围 | | 66 | 传感器 | SENSOR_OUT_OF_RANGE | 超出测量范围 |
| 80 | 校准 | CALIBRATION_REQUIRED | 需要校准或校准过期 | | 80 | 校准 | CALIBRATION_REQUIRED | 需要校准或校准过期 |
| 96 | 存储 | STORAGE_FULL | 本地存储空间不足 | | 96 | 存储 | STORAGE_FULL | 本地存储空间不足 |
| 112 | GNSS | GPS_FIX_LOST | GNSS 信号丢失，无位置信息 | | 112 | GNSS | GPS_FIX_LOST | GNSS 信号丢失，无位置信息 |
| 128–511 | 预留 | — | 预留给未来通用错误 | | 128–511 | 预留 | — | 预留给未来通用错误 |
| 512–1023 | 应用 | — | 留给具体应用 / 产品线自定义 | | 512–1023 | 应用 | — | 留给具体应用 / 产品线自定义 |
| 1024–65535 | 厂商自定义 | — | 厂商或项目私有错误码区间 | | 1024–65535 | 厂商自定义 | — | 厂商或项目私有错误码区间 |
#### 错误信息 (`error_msg`) #### 错误信息 (`error_msg`)
@ -321,11 +355,15 @@ type Confidence = number | number[]
置信度的取值范围为 0 至 1，其中 0 表示完全不可信，1 表示完全可信（100%）。 置信度的取值范围为 0 至 1，其中 0 表示完全不可信，1 表示完全可信（100%）。
> [!NOTE]
> 当一个字段包含非零的 `error_code` 时, 强烈建议将置信度设置为 0 以表示该字段值不可靠
> [!WARNING] > [!WARNING]
> - 对于单值（scalar）数据，不应填写数组形式的置信度，若填写则无意义，解析器将会忽略 > - 对于单值（scalar）数据，不应填写数组形式的置信度，若填写则无意义，解析器将会忽略
> - 对于批量数据，既可填写单一置信度（所有采样点共享），也可填写置信度数组（每个采样点单独指定） > - 对于批量数据，既可填写单一置信度（所有采样点共享），也可填写置信度数组（每个采样点单独指定）
> - 如未指定 confidence 字段，则默认所有采样点的置信度为 1 > - 如未指定 confidence 字段，则默认所有采样点的置信度为 1
#### 采样间隔 (`sample_interval`) #### 采样间隔 (`sample_interval`)
可选。采样间隔, 用于描述 `value` 为等间隔数组时, 数组中每个元素的时间间隔 (建议所有等间隔数组都显式填写该字段) 可选。采样间隔, 用于描述 `value` 为等间隔数组时, 数组中每个元素的时间间隔 (建议所有等间隔数组都显式填写该字段)
@ -414,7 +452,7 @@ interface Field {
interface Message { interface Message {
version: 1; version: 1;
msg_type: "telemetry"; msg_type: "telemetry";
mode?: "descriptive" | "strict"; // 仅支持 descriptive 模式 mode?: "descriptive" | "strict"; // 目前仅支持 descriptive 模式
dev_id: string; dev_id: string;
dev_type?: string | { type_id: string } | { type_name: string }; dev_type?: string | { type_id: string } | { type_name: string };
timestamp: Timestamp; timestamp: Timestamp;

16
example.jsonc
View File

@ -138,11 +138,11 @@
// any legal timestamp format is supported // any legal timestamp format is supported
"t": [ "t": [
1715145600, 1715145600,
1715145600, 1715145602,
1715145600, 1715145604,
1715145600, 1715145606,
1715145600, 1715145608,
1715145600 1715145610
] ]
}, },
"metadata": { "metadata": {
@ -200,9 +200,9 @@
// optional // optional
"location": { "location": {
"coordinates": [ "coordinates": [
24.123456, 120.123456,
120.123456 24.123456
], // latitude and longitude in degrees ], // longitude and latitude in degrees
// optional, defaults to "gcj02" // optional, defaults to "gcj02"
"coordinate_system": "wgs84", // "wgs84", "gcj02", "bd09" "coordinate_system": "wgs84", // "wgs84", "gcj02", "bd09"
// optional // optional

338
schema.json
View File

@ -1,338 +0,0 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/telemetry.schema.json",
"title": "Telemetry Message",
"description": "Schema describing a telemetry message exchanged by devices.",
"type": "object",
"additionalProperties": false,
"properties": {
"version": {
"type": "integer",
"minimum": 1,
"description": "Protocol semantic version (integer)."
},
"msg_type": {
"type": "string",
"enum": [
"telemetry"
],
"description": "Currently only the literal string 'telemetry' is supported."
},
"dev_id": {
"$ref": "#/$defs/uuid"
},
"dev_type": {
"description": "Device type identifier (string or one-of helper objects).",
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"required": [
"type_id"
],
"additionalProperties": false,
"properties": {
"type_id": {
"$ref": "#/$defs/uuid"
}
}
},
{
"type": "object",
"required": [
"type_name"
],
"additionalProperties": false,
"properties": {
"type_name": {
"type": "string"
}
}
}
]
},
"timestamp": {
"$ref": "#/$defs/timestamp"
},
"fields": {
"type": "array",
"description": "Array of discrete or batch field objects.",
"items": {
"oneOf": [
{
"$ref": "#/$defs/discrete_field"
},
{
"$ref": "#/$defs/batch_field"
}
]
}
},
"enum": {
"type": "array",
"items": {
"$ref": "#/$defs/enum_definition"
}
},
"location": {
"$ref": "#/$defs/location"
},
"battery": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Battery percentage (0-100)."
},
"sqe": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295,
"description": "Sample sequence counter (uint32)."
}
},
"required": [
"version",
"msg_type",
"dev_id",
"dev_type",
"timestamp",
"fields"
],
"$defs": {
"uuid": {
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"description": "UUID v4 string."
},
"timestamp": {
"description": "UNIX epoch (seconds) or an object with a single alternative timestamp representation.",
"oneOf": [
{
"type": "number"
},
{
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"additionalProperties": false,
"properties": {
"unix_ns": {
"type": "number"
},
"unix_us": {
"type": "number"
},
"unix_ms": {
"type": "number"
},
"unix_s": {
"type": "number"
},
"iso8601": {
"type": "string",
"format": "date-time"
}
}
}
]
},
"sample_interval": {
"oneOf": [
{
"type": "number",
"description": "Interval in seconds."
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"ms": {
"type": "number"
},
"s": {
"type": "number"
},
"m": {
"type": "number"
},
"h": {
"type": "number"
},
"d": {
"type": "number"
},
"w": {
"type": "number"
}
}
}
]
},
"confidence": {
"oneOf": [
{
"type": "number",
"minimum": 0,
"maximum": 1
},
{
"type": "array",
"items": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
]
},
"discrete_field": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"data_type",
"value",
"timestamp"
],
"properties": {
"name": {
"type": "string"
},
"data_type": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"timestamp": {
"$ref": "#/$defs/timestamp"
},
"unit": {
"type": "string"
},
"confidence": {
"$ref": "#/$defs/confidence"
}
}
},
"batch_field": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"array_type",
"value",
"timestamp"
],
"properties": {
"name": {
"type": "string"
},
"array_type": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
},
"timestamp": {
"$ref": "#/$defs/timestamp"
},
"sample_interval": {
"$ref": "#/$defs/sample_interval"
},
"unit": {
"type": "string"
},
"confidence": {
"$ref": "#/$defs/confidence"
}
}
},
"enum_definition": {
"type": "object",
"additionalProperties": false,
"required": [
"identifier",
"value"
],
"properties": {
"identifier": {
"type": "string"
},
"value": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
}
},
"location": {
"type": "object",
"additionalProperties": false,
"required": [
"coordinates"
],
"properties": {
"coordinates": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": [
{
"type": "number",
"minimum": -90,
"maximum": 90
},
{
"type": "number",
"minimum": -180,
"maximum": 180
}
]
},
"coordinate_system": {
"type": "string",
"enum": [
"wgs84",
"gcj02",
"bd09"
],
"default": "gcj02"
},
"accuracy": {
"type": "number",
"minimum": 0
},
"altitude": {
"type": "number"
}
}
}
}
}