docs(protocol): 脱机事件日志命令规范 — MQTT V1.06 + TCP JSON V1.02
新增 3 命令 (两协议同步): - log_stat: 日志统计/分页定位 (stream/boot_seq/count/capacity/seq_first/seq_last) - log_query: 按全局序号分页拉取, count≤4 (受 500B 发布限制) - log_clear: 清除+审计留痕 (log_clear 事件不可清除) 日志时间戳语义 (§2.3 补充): 每条记录 ts_ms(相对) + unix_ts(已同步, 0=未同步), 锚点回算规则; 10 类事件类型表 (boot/iot_*/evt_*/coil/ time_anchor/log_clear) 带 data 字段解析。 同步: README/CHANGELOG/产品手册/技术规格书 协议矩阵 (MQTT V1.05→V1.06, TCP JSON V1.01→V1.02) 注: 固件命令分发 (log_stat/log_query/log_clear 处理) 待 P1.3 实现, 本文档为协议先行
This commit is contained in:
wangfq
@@ -119,6 +119,9 @@ Client Device (DLD960)
|
||||
| `loop_param_set` | 设置车检器多路参数 | 是 | 0x63 |
|
||||
| `loop_param_query` | 读取车检器多路参数 | 是 | 0x64 |
|
||||
| `report_config` | 设置主动上报 | 是 | 0xC5 |
|
||||
| `log_stat` | 查询脱机事件日志统计 | 是 | — |
|
||||
| `log_query` | 分页拉取脱机事件日志 | 是 | — |
|
||||
| `log_clear` | 清除脱机事件日志（审计留痕） | 是 | — |
|
||||
| 主动推送 | | | |
|
||||
| `loop_data` | 线圈传感数据（设备→客户端） | — | 0xC0 |
|
||||
| `event_report` | 事件上报（设备→客户端，**客户端须应答**，见 §5.2） | — | — |
|
||||
@@ -342,6 +345,99 @@ Client Device (DLD960)
|
||||
|
||||
---
|
||||
|
||||
## 4.16 查询脱机事件日志统计 `log_stat`
|
||||
|
||||
> 设备本地 W25Q32 环形事件日志（256KB / 8064 条，掉电不丢）。用于日志拉取前的分页定位。
|
||||
|
||||
**请求：**
|
||||
|
||||
```json
|
||||
{"msg_id":16,"cmd":"log_stat","ts":1719000000,"data":{}}
|
||||
```
|
||||
|
||||
**响应 data：**
|
||||
|
||||
```json
|
||||
{"stream":"event","enabled":true,"boot_seq":2,"count":1234,"capacity":8064,"seq_first":100,"seq_last":1333}
|
||||
```
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `stream` | string | 日志流，当前仅 `event`（快照流预留） |
|
||||
| `enabled` | bool | 日志功能是否启用（Flash 初始化成功） |
|
||||
| `boot_seq` | uint16 | 当前启动序号（每次上电 +1，区分复位段） |
|
||||
| `count` | uint16 | 有效记录条数（0~8064） |
|
||||
| `capacity` | uint16 | 容量上限（8064） |
|
||||
| `seq_first` | uint32 | 逻辑首条记录全局序号（`seq_last - count + 1`） |
|
||||
| `seq_last` | uint32 | 最新一条记录全局序号（跨 boot 单调递增） |
|
||||
|
||||
---
|
||||
|
||||
## 4.17 分页拉取脱机事件日志 `log_query`
|
||||
|
||||
> **分页按全局序号，不按时间**（未同步段时间不可靠）。`count` 上限 **4**（受响应帧 ≤800B 限制）。
|
||||
|
||||
**请求：**
|
||||
|
||||
```json
|
||||
{"msg_id":17,"cmd":"log_query","ts":1719000000,"data":{"start_seq":1330,"count":4}}
|
||||
```
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `start_seq` | uint32 | 起始全局序号（含）；越界（< `seq_first` 或 > `seq_last`）返回空 `records` |
|
||||
| `count` | uint8 | 拉取条数，**上限 4**，超限按 4 处理 |
|
||||
|
||||
**响应 data：**
|
||||
|
||||
```json
|
||||
{"start_seq":1330,"records":[{"seq":1330,"boot_seq":2,"ts_ms":456789,"unix_ts":1784768575,"type":"iot_ready","data":null}]}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `seq` | uint32 | 全局序号 |
|
||||
| `boot_seq` | uint16 | 所属启动段 |
|
||||
| `ts_ms` | uint32 | boot 内相对时间（ms，断电归零） |
|
||||
| `unix_ts` | uint32 | 已同步 Unix 秒；**0 = 未同步**（回算见 §2.3） |
|
||||
| `type` | string | 事件类型名（下表） |
|
||||
| `data` | object/null | 类型相关参数 |
|
||||
|
||||
**事件类型表：**
|
||||
|
||||
| type | 含义 | data 字段 |
|
||||
|------|------|-----------|
|
||||
| `boot` | 上电/复位 | `{"rst": 复位原因寄存器原始值}`，位解析：bit31=IWDG(看门狗) bit30=WWDG bit29=LPWR bit26=NRST引脚 bit25=POR(真断电) bit24=软件复位 |
|
||||
| `iot_connect` | MQTT TCP 连接成功 | null |
|
||||
| `iot_ready` | MQTT 订阅完成 → 发 initialize | null |
|
||||
| `iot_disconnect` | MQTT 断连 | `{"reason": N}`，1=断开 2=超时 3=CONNACK拒绝 4=连接超时 |
|
||||
| `iot_reconn` | 重连退避 | `{"backoff_ms": 5000}` |
|
||||
| `evt_retry` | event_report ACK 超时重发 | `{"msg_id":5,"retry":2}` |
|
||||
| `evt_giveup` | event_report 重试耗尽挂起 | `{"msg_id":5}` |
|
||||
| `coil` | 线圈事件 | `{"sub":"car_enter","ch":1,"value":97}`；sub: car_enter/car_leave/loop_cut/loop_restore，value 为 50ms 单位时间量 |
|
||||
| `time_anchor` | 时钟同步锚点 | null（`unix_ts` 即平台下发值，严格一致） |
|
||||
| `log_clear` | 日志清除（审计） | null |
|
||||
|
||||
---
|
||||
|
||||
## 4.18 清除脱机事件日志 `log_clear`
|
||||
|
||||
> ⚠ **高风险操作**：清除动作本身写入事件流（`log_clear` 审计——谁在何时清了日志，留痕不可清除）。客户端应做权限控制。
|
||||
|
||||
**请求：**
|
||||
|
||||
```json
|
||||
{"msg_id":18,"cmd":"log_clear","ts":1719000000,"data":{"stream":"event"}}
|
||||
```
|
||||
|
||||
| data 字段 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `stream` | string | 日志流，当前仅 `event`；缺省等同 `event` |
|
||||
|
||||
**响应：** 标准成功/失败。成功后 `log_stat` 的 `count` 归 1（仅剩审计记录），`seq_last` 继续递增（序号不复位）。
|
||||
|
||||
---
|
||||
|
||||
# 5 设备主动推送
|
||||
|
||||
主动推送帧与请求-响应共用同一条 TCP 连接，由设备在任意时刻发出。
|
||||
@@ -457,3 +553,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 |
|
||||
|
||||
Reference in New Issue
Block a user