docs(协议): TCP JSON V1.03 + IoT MQTT V1.07 — log_* 命令完善传感快照流 (2026-08-18)
- log_stat/log_query/log_clear 复用 stream 字段区分 event/snapshot（与 BLE 0x28/0x2A 同语义） - 快照统计 capacity 随芯片动态（48064~449472）；快照分页 count≤2（SnapRec 64B 原始结构 JSON 化，channels 对齐 0xC0） - 快照清除审计留痕 + 阻塞时长说明（事件 2.8s / 快照 45ms） - capacity/count 类型 uint16→uint32 修正（W25Q256 事件流 130944 超 16bit） - README/技术规格书协议矩阵/产品手册相关文档表同步
This commit is contained in:
wangfq
+83
-31
@@ -119,9 +119,9 @@ Client Device (DLD960)
|
||||
| `loop_param_set` | 设置车检器多路参数 | 是 | 0x63 |
|
||||
| `loop_param_query` | 读取车检器多路参数 | 是 | 0x64 |
|
||||
| `report_config` | 设置主动上报 | 是 | 0xC5 |
|
||||
| `log_stat` | 查询脱机事件日志统计 | 是 | — |
|
||||
| `log_query` | 分页拉取脱机事件日志 | 是 | — |
|
||||
| `log_clear` | 清除脱机事件日志（审计留痕） | 是 | — |
|
||||
| `log_stat` | 查询脱机日志统计（事件/快照流） | 是 | — |
|
||||
| `log_query` | 分页拉取脱机日志（事件/快照流） | 是 | — |
|
||||
| `log_clear` | 清除脱机日志（事件/快照流，审计留痕） | 是 | — |
|
||||
| 主动推送 | | | |
|
||||
| `loop_data` | 线圈传感数据（设备→客户端） | — | 0xC0 |
|
||||
| `event_report` | 事件上报（设备→客户端，**客户端须应答**，见 §5.2） | — | — |
|
||||
@@ -345,50 +345,63 @@ Client Device (DLD960)
|
||||
|
||||
---
|
||||
|
||||
## 4.16 查询脱机事件日志统计 `log_stat`
|
||||
## 4.16 查询脱机日志统计 `log_stat`
|
||||
|
||||
> 设备本地 W25Qxx 环形事件日志（事件区动态：W25Q32=512KB/16256 条，掉电不丢）。用于日志拉取前的分页定位。
|
||||
> 设备本地 W25Qxx 环形日志（事件区/快照区容量随存储芯片动态，掉电不丢）。用于日志拉取前的分页定位。
|
||||
> 通过 `data.stream` 区分日志流：`event`（事件日志，缺省）/ `snapshot`（传感快照）。
|
||||
|
||||
**请求：**
|
||||
|
||||
```json
|
||||
{"msg_id":16,"cmd":"log_stat","ts":1719000000,"data":{}}
|
||||
{"msg_id":16,"cmd":"log_stat","ts":1719000000,"data":{"stream":"event"}}
|
||||
```
|
||||
|
||||
**响应 data：**
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `stream` | string | 日志流：`event`（缺省，可省略）或 `snapshot` |
|
||||
|
||||
**响应 data（stream=event）：**
|
||||
|
||||
```json
|
||||
{"stream":"event","enabled":true,"boot_seq":2,"count":1234,"capacity":16256,"seq_first":100,"seq_last":1333}
|
||||
```
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `stream` | string | 日志流，当前仅 `event`（快照流预留） |
|
||||
| `enabled` | bool | 日志功能是否启用（Flash 初始化成功） |
|
||||
| `boot_seq` | uint16 | 当前启动序号（每次上电 +1，区分复位段） |
|
||||
| `count` | uint16 | 有效记录条数（0~capacity） |
|
||||
| `capacity` | uint16 | 容量上限（**随存储芯片动态**：W25Q32=16256 / W25Q64=32640 / W25Q128=65408 / W25Q256=130944） |
|
||||
| `seq_first` | uint32 | 逻辑首条记录全局序号（`seq_last - count + 1`） |
|
||||
| `seq_last` | uint32 | 最新一条记录全局序号（跨 boot 单调递增） |
|
||||
|
||||
---
|
||||
|
||||
## 4.17 分页拉取脱机事件日志 `log_query`
|
||||
|
||||
> **分页按全局序号，不按时间**（未同步段时间不可靠）。`count` 上限 **4**（受响应帧 ≤800B 限制）。
|
||||
|
||||
**请求：**
|
||||
**响应 data（stream=snapshot）：**
|
||||
|
||||
```json
|
||||
{"msg_id":17,"cmd":"log_query","ts":1719000000,"data":{"start_seq":1330,"count":4}}
|
||||
{"stream":"snapshot","enabled":true,"boot_seq":2,"count":1234,"capacity":48064,"seq_first":100,"seq_last":1333}
|
||||
```
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `start_seq` | uint32 | 起始全局序号（含）；越界（< `seq_first` 或 > `seq_last`）返回空 `records` |
|
||||
| `count` | uint8 | 拉取条数，**上限 4**，超限按 4 处理 |
|
||||
| `stream` | string | 日志流：`event` / `snapshot` |
|
||||
| `enabled` | bool | 日志功能是否启用（Flash 初始化成功） |
|
||||
| `boot_seq` | uint16 | 当前启动序号（每次上电 +1，区分复位段） |
|
||||
| `count` | uint32 | 有效记录条数（0~capacity，环形覆盖后 < capacity） |
|
||||
| `capacity` | uint32 | 容量上限（**随存储芯片与流动态**）：事件流 W25Q32=16256 / Q64=32640 / Q128=65408 / Q256=130944；快照流 W25Q32=48064 / Q64=105408 / Q128=220096 / Q256=449472 |
|
||||
| `seq_first` | uint32 | 逻辑首条记录全局序号（`seq_last - count + 1`，count=0 时为 0） |
|
||||
| `seq_last` | uint32 | 最新一条记录全局序号（跨 boot 单调递增） |
|
||||
|
||||
**响应 data：**
|
||||
---
|
||||
|
||||
## 4.17 分页拉取脱机日志 `log_query`
|
||||
|
||||
> **分页按全局序号，不按时间**（未同步段时间不可靠）。`count` 上限按流区分：事件流 **4**（受响应帧 ≤800B 限制）/ 快照流 **2**（64B×2 记录）。
|
||||
> 通过 `data.stream` 区分日志流：`event`（缺省）/ `snapshot`。
|
||||
|
||||
**请求：**
|
||||
|
||||
```json
|
||||
{"msg_id":17,"cmd":"log_query","ts":1719000000,"data":{"stream":"event","start_seq":1330,"count":4}}
|
||||
```
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `stream` | string | 日志流：`event`（缺省，可省略）或 `snapshot` |
|
||||
| `start_seq` | uint32 | 起始全局序号（含）；越界（< `seq_first` 或 > `seq_last`）返回空 `records` |
|
||||
| `count` | uint8 | 拉取条数；事件流上限 **4**、快照流上限 **2**，超限按各自上限处理；0 按上限处理 |
|
||||
|
||||
**响应 data（stream=event）：**
|
||||
|
||||
```json
|
||||
{"start_seq":1330,"records":[{"seq":1330,"boot_seq":2,"ts_ms":456789,"unix_ts":1784768575,"type":"iot_ready","data":null}]}
|
||||
@@ -418,9 +431,44 @@ Client Device (DLD960)
|
||||
| `time_anchor` | 时钟同步锚点 | null（`unix_ts` 即平台下发值，严格一致） |
|
||||
| `log_clear` | 日志清除（审计） | null |
|
||||
|
||||
**响应 data（stream=snapshot）：**
|
||||
|
||||
```json
|
||||
{"start_seq":12345,"records":[{"seq":12345,"boot_seq":2,"ts_ms":456789,"coil_count":4,"channels":[{"ch":1,"freq_level":"high","direction":0,"freq_type":1,"sensitivity":2,"condition":0,"loop_ok":true,"has_car":false,"misc_type":"time","freq":69418,"variation":7,"misc":0}]}]}
|
||||
```
|
||||
|
||||
快照记录为 64B 定长原始结构 `SnapRec`（与 0xC0 线上线圈单元逐字节一致，见《DLD960Loop 串口通信协议》§3.07），JSON 化后字段：
|
||||
|
||||
| 记录字段 | 类型 | 说明 |
|
||||
|----------|------|------|
|
||||
| `seq` | uint32 | 全局序号（跨 boot 递增） |
|
||||
| `boot_seq` | uint16 | 所属启动段 |
|
||||
| `ts_ms` | uint32 | boot 内相对时间（ms，采集时刻） |
|
||||
| `coil_count` | uint8 | 本记录线圈数（SnapRec.len/12，1~4） |
|
||||
| `channels` | array | 线圈传感单元（每路 12B，与 0xC0 线上格式一致） |
|
||||
|
||||
`channels[]` 单元字段（与 0xC0 传感单元一致）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `ch` | uint8 | 通道号 1~4 |
|
||||
| `freq_level` | string | 频率档位：`"high"`(33nF) / `"mid_high"`(43nF) / `"mid_low"`(66nF) / `"low"`(76nF) |
|
||||
| `direction` | uint8 | 0=触发模式 1=方向判别 |
|
||||
| `freq_type` | uint8 | 0=初始频率 1=当前实时频率 |
|
||||
| `sensitivity` | uint8 | 灵敏度等级（cfg 低四位） |
|
||||
| `condition` | uint8 | 环境评估值（cond 高四位，值越大干扰越大） |
|
||||
| `loop_ok` | bool | 线圈正常（SnapRec loop_state bit：0=正常→true，1=断开→false） |
|
||||
| `has_car` | bool | 有车（SnapRec car_state bit：1=有车） |
|
||||
| `misc_type` | string | `"time"` / `"cut_count"` / `"flow_count"` / `"relay_count"`（00 时间量 / 01 线圈断开次数 / 10 车流量 / 11 继电器输出次数） |
|
||||
| `freq` | uint32 | 线圈频率（Hz，3B LE 无符号） |
|
||||
| `variation` | int32 | 变化量（3B LE 有符号补码，`Origin − CAPVD`；正=车/裕量，负=反向漂移） |
|
||||
| `misc` | uint32 | 杂项值（misc_type=time 时 = 通过时间/车间距，**50ms 单位**） |
|
||||
|
||||
> 绝对时间回算同事件流：用事件流 `time_anchor`（boot_seq ↔ unix_ts 映射）+ 本记录 `boot_seq`/`ts_ms`；未同步段仅相对时间。
|
||||
|
||||
---
|
||||
|
||||
## 4.18 清除脱机事件日志 `log_clear`
|
||||
## 4.18 清除脱机日志 `log_clear`
|
||||
|
||||
> ⚠ **高风险操作**：清除动作本身写入事件流（`log_clear` 审计——谁在何时清了日志，留痕不可清除）。客户端应做权限控制。
|
||||
|
||||
@@ -432,9 +480,12 @@ Client Device (DLD960)
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `stream` | string | 日志流，当前仅 `event`；缺省等同 `event` |
|
||||
| `stream` | string | 日志流：`event`（缺省，可省略）或 `snapshot` |
|
||||
|
||||
**响应：** 标准成功/失败。成功后 `log_stat` 的 `count` 归 1（仅剩审计记录），`seq_last` 继续递增（序号不复位）。
|
||||
**响应：** 标准成功/失败。
|
||||
|
||||
- `stream=event`：成功后 `log_stat` 的 `count` 归 1（仅剩审计记录），`seq_last` 继续递增（序号不复位）。**阻塞 ~2.8s**（63 个数据扇区 SPI 擦除），请勿高频调用。
|
||||
- `stream=snapshot`：成功后 `log_stat` 的 `count` 归 0，`seq_last` 继续递增；清除动作写入事件流审计（`log_clear`，payload 标记快照流）。**阻塞 ~45ms**（逻辑清除 + 当前写扇区擦除，其余扇区由环形写覆盖时自动擦）。
|
||||
|
||||
---
|
||||
|
||||
@@ -554,3 +605,4 @@ Client Device (DLD960)
|
||||
| V1.00 | 2026-06-22 | 初始版本，基于串口协议 V1.01 | wangfq |
|
||||
| V1.01 | 2026-07-15 | `event_report` 增加**客户端必答**机制：应答格式（回显 `msg_id`）、设备 5s 超时重发（同 `msg_id`/`ts`，最多 3 次）、待发队列合并上报、客户端去重与先落库后应答要求（与 MQTT 协议 V1.04 对称） | wangfq |
|
||||
| V1.02 | 2026-08-04 | 增加**脱机事件日志**命令：`log_stat`（统计/分页定位）、`log_query`（按全局序号分页，count≤4）、`log_clear`（清除+审计留痕）；事件类型表与 MQTT 协议 V1.06 对齐 | wangfq |
|
||||
| V1.03 | 2026-08-18 | `log_stat` / `log_query` / `log_clear` 增加**快照流**支持（`stream=snapshot`，与 BLE 0x28/0x29/0x2A 同语义）：快照统计 capacity 随芯片动态（48064~449472）、快照分页 count≤2（SnapRec 64B 原始结构 JSON 化）、快照清除审计留痕；`capacity`/`count` 类型修正为 uint32（W25Q256 事件流 130944 超 16bit） | wangfq |
|
||||
|
||||
Reference in New Issue
Block a user