From fb42ca777fdca756f90dfc22a4293dce383b2ed2 Mon Sep 17 00:00:00 2001 From: crosstyan Date: Mon, 7 Jul 2025 18:52:54 +0800 Subject: [PATCH] Update device identifier format from UUID to NanoID in example.jsonc, mqtt.md, schema.json, and schema.md; enhance documentation to reflect changes in device ID representation. --- README.md | 6 ------ example.jsonc | 4 ++-- mqtt.md | 12 ++++++------ schema.json | 8 +++++--- schema.md | 8 ++++---- 5 files changed, 17 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index d9ffb59..297c918 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,8 @@ WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JS ## 特性亮点 - **自描述（Self-descriptive）**：数据类型、单位、采样间隔等元信息随报文一并上送，脱离外部 Schema 亦可独立解析。 -- **单一载体（JSON）**：无需生成器或专用编解码库，主流语言天然支持。 -- **时间表达力强**：支持从秒到纳秒的多粒度 UNIX 时间戳，或 ISO-8601 字符串。 - **批量数据友好**：内置等间隔 `array` 与非等间隔 `irregular` 两种批量格式，可显著降低消息数。 - **枚举支持**：全局或内联枚举可读性强，兼具类型安全。 -- **错误／置信度模型**：统一的 `error_code` + `confidence` 机制，便于数据质量管理。 -- **多传输层**：已提供 [MQTT 补充说明](mqtt.md)，亦可轻松扩展至 HTTP、WebSocket、CoAP 等。 ## 快速上手 @@ -29,5 +25,3 @@ WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JS | `mqtt.md` | MQTT 传输层补充说明 | | `example.jsonc` | 完整示例消息，含字段注释 | | `README.md` | 当前文件，项目概览 | - - diff --git a/example.jsonc b/example.jsonc index 2d3333e..c122d20 100644 --- a/example.jsonc +++ b/example.jsonc @@ -8,11 +8,11 @@ // // for descriptive mode, everything should self contained (like unit, sample interval, etc.) "mode": "descriptive", - "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7", // uuid-v4, unique for each device + "dev_id": "2B1oj2S5k7kS8mL_QaCs", // NanoID, unique for each device "dev_type": "device_type_name", // "dev_type field supports: // string: designated by a unique string - // {"type_id": "148413b4-c352-49a9-9c48-9d15276a99e7"} // uuid-v4, unique for each device type + // {"type_id": "2B1oj2S5k7kS8mL_QaCs"} // NanoID, unique for each device type // {"type_name": "device_type_name"} // unique string, same as the string above "timestamp": 1715145600, // UNIX timestamp in seconds // timestamp fields supports: diff --git a/mqtt.md b/mqtt.md index 6482fad..3a46180 100644 --- a/mqtt.md +++ b/mqtt.md @@ -24,11 +24,11 @@ ## 消息主题 -假设设备唯一标识 `dev_id = 148413b4-c352-49a9-9c48-9d15276a99e7`，则常用主题如下： +假设设备唯一标识 `dev_id = 2B1oj2S5k7kS8mL_QaCs`，则常用主题如下： -| 方向 | 主题模板 | 示例 | 说明 | -| ---- | ------------------- | ---------------------------------------------- | ------------------------------------ | -| 上行 | `/whtp/up/{dev_id}` | `whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7` | 发送遥测数据（Payload 为 WHTP JSON） | +| 方向 | 主题模板 | 示例 | 说明 | +| ---- | ------------------- | ------------------------------- | ------------------------------------ | +| 上行 | `/whtp/up/{dev_id}` | `/whtp/up/2B1oj2S5k7kS8mL_QaCs` | 发送遥测数据（Payload 为 WHTP JSON） | ## QoS 与重传策略 @@ -47,13 +47,13 @@ MQTT Payload **必须**为 UTF-8 编码的文本，遵循 [WHTP 主规范](schem ```jsonc // 示例：设备侧发布 -Topic : /whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7 +Topic : /whtp/up/2B1oj2S5k7kS8mL_QaCs QoS : 1 Retained: false Payload : { "version": 1, "msg_type": "telemetry", - "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7", + "dev_id": "2B1oj2S5k7kS8mL_QaCs", "dev_type": "device_type_name", "timestamp": 1715145600, "fields": [ diff --git a/schema.json b/schema.json index 3e21a44..069f0d4 100644 --- a/schema.json +++ b/schema.json @@ -34,8 +34,9 @@ }, "dev_id": { "type": "string", - "format": "uuid", - "description": "Device unique identifier (UUID v4)." + "format": "nanoid", + "description": "Device unique identifier (NanoID).", + "pattern": "^[A-Za-z0-9_-]{21}$" }, "dev_type": { "description": "Device model identifier.", @@ -53,7 +54,8 @@ "properties": { "type_id": { "type": "string", - "format": "uuid" + "format": "nanoid", + "pattern": "^[A-Za-z0-9_-]{21}$" } }, "additionalProperties": false diff --git a/schema.md b/schema.md index b47555f..61732bc 100644 --- a/schema.md +++ b/schema.md @@ -11,7 +11,7 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描 | version | 是 | number | 协议主版本号 | | msg_type | 是 | string | 消息类别，目前仅 `"telemetry"` | | mode | 否 | string | 工作模式，`"descriptive"`（默认）或 `"strict"` | -| dev_id | 是 | string | 设备唯一标识（UUID v4） | +| dev_id | 是 | string | 设备唯一标识（NanoID） | | dev_type | 是 | string / object | 设备型号标识 | | timestamp | 是 | Timestamp | 消息生成时刻 | | fields | 是 | Field[] | 采集字段数组 | @@ -36,7 +36,7 @@ WHTP 消息由根级字段与 `fields` 数组两部分组成。根级字段描 ### 设备 ID (`dev_id`) -必填。设备唯一标识，采用 UUID v4 格式（如 `148413b4-c352-49a9-9c48-9d15276a99e7`），在设备生命周期内保持不变。 +必填。设备唯一标识，采用 [NanoID](https://github.com/ai/nanoid) 格式（如 `2B1oj2S5k7kS8mL_QaCs`），在设备生命周期内保持不变。 ### 设备类型 (`dev_type`) @@ -47,14 +47,14 @@ type DeviceType = string | { type_id: string } | { type_name: string } 必选。用于标识设备类别或型号。支持三种写法： 1. **字符串**：例如 `"device_type_name"`；与 `{ "type_name": string }` 等价 -2. **对象** `{ "type_id": UUID }`；UUID 为设备型号的唯一标识, 由平台分配 +2. **对象** `{ "type_id": NanoID }`；NanoID 为设备型号的唯一标识, 由平台分配 3. **对象** `{ "type_name": string }`。 > [!NOTE] > > 以上三种写法在语义上等价, 由数据生产方按需选择 > -> - 对于长期稳定的系统, 推荐使用 `{ "type_id": UUID }` 格式, 作为稳定的唯一标识符 +> - 对于长期稳定的系统, 推荐使用 `{ "type_id": NanoID }` 格式, 作为稳定的唯一标识符 > - 对于临时场景, 可以使用 `string` 或 `{ "type_name": string }` 格式 ### 根级时间戳 (`timestamp`)