docs(vd960DBN): MQTT 协议 V1.10 — 网络上报携带地感版本 (配合远程 OTA 版本核对)

需求: 能通过网络 OTA 地感固件后, 网络上报设备信息需带地感固件版本号,
供平台升级前后版本核对/归档。

现状基础 (复用, 零新协议原语):
- Loop 0x4A 版本查询已实现 (lup_build_get_version/lup_parse_version)
- TCP JSON 已有 loop_version_query 先例 (tcp_json_srv.c)
- MQTT 回包 topic 固定 dld960/{sn}/dev → 异步回包只需存 msg_id

协议 V1.10 变更:
- §4.2 dev_info_query 响应 + §5.1 initialize 上报: 新增 loop_ver/
  loop_hw_ver (地感固件/硬件版本, 主.次.次, 0x4A 缓存, 尽力携带可为空)
- 新增 §4.25 loop_version_query (srv→dev): 实时查询, 设备经 UART2
  0x4A 异步查询后回包 (loop_ver/loop_hw_ver/version_str), 超时回 code=5
- §3 命令表补 loop_version_query (对应串口 0x4A)
- 版本语义区分: soft_ver=整机 DBN 固件(主.次), loop_ver=地感 Loop 固件(主.次.次)
- 修订记录 V1.10; 设计稿/README/技术规格书同步; 工具 sample initialize 补字段

DBNMQTTool/main.py

@@ -881,6 +881,8 @@ class MainWindow(QMainWindow):
                 "model": "DLD960",
                 "hard_ver": "1.0",
                 "soft_ver": "1.0",
+                "loop_ver": "1.2.3",
+                "loop_hw_ver": "1.0.0",
                 "extra_info": {
                     "code": "869756049404948",
                     "csq": "21",

README.md

@@ -59,7 +59,7 @@ DLD960 是一款基于环形线圈检测原理的四通道车辆检测器，支
 | [DLD960Loop_串口通信协议.md](docs/DLD960Loop_串口通信协议.md) | V1.05 | Loop MCU ↔ DBN MCU | 0x7F 帧、0xC0 传感主动上报、variation 3B 有符号 |
 | [DLD960_串口通信协议.md](docs/DLD960_串口通信协议.md) | V1.01 | 整机 TTL 串口 | 设备管理、参数配置、数据上报 |
 | [DLD960_TCP_JSON协议.md](docs/DLD960_TCP_JSON协议.md) | V1.03 | 以太网 TCP :5960 | 鉴权 + 命令 + event_report 客户端必答 + 脱机日志（事件/快照流） |
-| [DLD960_IoT_MQTT协议.md](docs/DLD960_IoT_MQTT协议.md) | V1.09 | 云平台 MQTT | 双主题 `{sn}/srv`+`{sn}/dev`、initialize、event_report 平台必答、设备时钟同步、脱机日志（事件/快照流）、Loop 远程 OTA（ota_* 命令，先存后刷） |
+| [DLD960_IoT_MQTT协议.md](docs/DLD960_IoT_MQTT协议.md) | V1.10 | 云平台 MQTT | 双主题 `{sn}/srv`+`{sn}/dev`、initialize、event_report 平台必答、设备时钟同步、脱机日志（事件/快照流）、Loop 远程 OTA（ota_* 命令，先存后刷） |
 | [DLD960_BLE协议.md](docs/DLD960_BLE协议.md) | V1.02 | 蓝牙 BLE | 帧格式 + 分包 + 脱机日志（OFFLOG_STAT/QUERY/CLEAR）+ 传感快照（SNAP_STAT/QUERY/CLEAR，0x28/0x29/0x2A），与 MQTT/TCP 同语义 |
 | [DLD960硬件资源.md](docs/DLD960硬件资源.md) | — | 硬件 | 双 MCU IO 分配、继电器、指示灯、拨码 |
 

docs/DLD960_IoT_MQTT协议.md

@@ -159,6 +159,7 @@ dld960/{dev_serial}/{direction}
 | `ota_abort` | 中止 OTA 会话，释放暂存 | srv→dev | — |
 | `ota_flash` | 触发本地 ISP 刷写（仅 ready 态） | srv→dev | — |
 | `ota_status` | 查询 OTA 状态（含进度） | srv→dev | — |
+| `loop_version_query` | 实时查询地感 Loop MCU 版本（V1.10） | srv→dev | 0x4A |
 | `initialize` | 设备上电初始化登陆  | dev→srv | — |
 | `loop_data` | 线圈传感数据上报 | dev→srv | 0xC0 |
 | `event_report` | 事件上报（**平台须应答**，见 §5.3） | dev→srv | — |
@@ -225,6 +226,8 @@ dld960/{dev_serial}/{direction}
     "dev_serial": "A1B2C3D4E5F6",
     "hard_ver": "1.1",
     "soft_ver": "1.1",
+    "loop_ver": "1.2.3",
+    "loop_hw_ver": "1.0.0",
     "model": "DLD960",
     "product_code": "960001",
     "sub_code": {
@@ -244,14 +247,18 @@ dld960/{dev_serial}/{direction}
 | data 字段 | 类型 | 说明 |
 |-----------|------|------|
 | `dev_serial` | string | 12 位十六进制序列码 |
-| `hard_ver` | string | 硬件版本，格式 `"主.次"` |
+| `hard_ver` | string | 硬件版本（整机），格式 `"主.次"` |
-| `soft_ver` | string | 软件版本，格式 `"主.次"` |
+| `soft_ver` | string | 软件版本（整机 DBN MCU 固件），格式 `"主.次"` |
+| `loop_ver` | string | **地感 Loop MCU 固件版本**（V1.10），格式 `"主.次.次"`（如 `1.2.3`）；来自 Loop 0x4A 查询缓存，**查询未完成/失败则为空字符串** |
+| `loop_hw_ver` | string | **地感 Loop MCU 硬件版本**（V1.10），格式 `"主.次.次"`；同上，可为空 |
 | `model` | string | 产品型号，1~10 字符 |
 | `product_code` | string | 产品编码，6 位数字字符串 |
 | `sub_code.net` | bool | 网络功能是否启用 |
 | `sub_code.iot` | bool | IoT/MQTT 功能是否启用 |
 | `bus.bus1~4` | uint8 | 各总线探头数 |
 
+> **loop_ver 语义（V1.10）**：`loop_ver`/`loop_hw_ver` 是**缓存值**（设备上电后自动经 Loop `0x4A` 查询一次，OTA 刷写成功后刷新）；MQTT 命令处理为同步回包，不等 0x4A 异步响应，故查询未完成/失败时回空。平台需最新版本时用 `loop_version_query`（§4.25）实时查询。
+
 ## 4.3 设置 SSC 网络配置 `ssc_net_set`
 
 > Topic: `dld960/{sn}/srv`
@@ -1067,6 +1074,49 @@ dld960/{dev_serial}/{direction}
 
 ---
 
+## 4.25 查询地感版本 `loop_version_query`
+
+> Topic: `dld960/{sn}/srv`
+> 用途：实时查询地感 Loop MCU 固件/硬件版本（V1.10，配合远程 OTA 做升级前后版本核对）。
+
+**请求：**
+
+```json
+{ "msg_id": 407, "cmd": "loop_version_query", "ts": 1719000007 }
+```
+
+**设备行为（异步）：**
+1. 经 UART2 向 Loop MCU 发 `0x4A` 查询帧（`7F 00 01 4A ...`，见 `DLD960Loop_串口通信协议.md` §3.01）
+2. 收到 Loop 响应后解析（Soft/Hard 各三段）→ 更新本地缓存 → 立即回包
+3. Loop 无响应/超时 → 回 `code=5`，`loop_ver` 保持缓存值（可为空）
+
+**响应：**
+
+```json
+{
+  "msg_id": 407,
+  "cmd": "loop_version_query",
+  "ts": 1719000008,
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "loop_ver": "1.2.3",
+    "loop_hw_ver": "1.0.0",
+    "version_str": "V1.2.3 (HW:1.0.0)"
+  }
+}
+```
+
+| data 字段 | 类型 | 说明 |
+|-----------|------|------|
+| `loop_ver` | string | 地感固件版本，格式 `"主.次.次"`（Soft_Main.Sub.SSub） |
+| `loop_hw_ver` | string | 地感硬件版本，格式 `"主.次.次"`（Hard_Main.Sub.SSub） |
+| `version_str` | string | 人类可读串，`"V{soft} (HW:{hard})"`；Loop 无响应时可能为空 |
+
+> **时序与缓存**：设备上电后自动查询一次并缓存；`ota_report stage=done`（Loop 复位跑新固件）后自动刷新缓存。平台升级流程建议：`ota_flash` 前 `loop_version_query` 记录旧版本 → 刷写完成后再次查询核对新版本是否生效。
+
+---
+
 # 5 设备主动上报
 
 ## 5.1 设备上电登陆信息 `initialize`
@@ -1083,6 +1133,8 @@ dld960/{dev_serial}/{direction}
     "model": "DLD960",
     "hard_ver": "1.0",
     "soft_ver": "1.0",
+    "loop_ver": "1.2.3",
+    "loop_hw_ver": "1.0.0",
     "extra_info": {
       "code": "869756049404948",
       "csq": "21",
@@ -1096,12 +1148,16 @@ dld960/{dev_serial}/{direction}
 |------|------|------|
 | `data.dev_serial` | string | 设备序列码 |
 | `data.model` | string | 产品型号 |
-| `data.hard_ver` | string | 硬件版本 |
+| `data.hard_ver` | string | 硬件版本（整机） |
-| `data.soft_ver` | string | 固件版本 |
+| `data.soft_ver` | string | 固件版本（整机 DBN MCU） |
+| `data.loop_ver` | string | **地感 Loop MCU 固件版本**（V1.10），格式 `"主.次.次"`；来自 0x4A 缓存，查询未完成/失败则为空字符串 |
+| `data.loop_hw_ver` | string | **地感 Loop MCU 硬件版本**（V1.10），格式 `"主.次.次"`；同上可为空 |
 | `data.extra_info.code` | string | 可选，设备代码如IMSI/ICCID |
 | `data.extra_info.csq` | string | 可选，当前信号强度 |
 | `data.extra_info.location` | string | 可选，经纬度（经度,纬度） |
 
+> **V1.10 说明**：`loop_ver`/`loop_hw_ver` 为**尽力携带**（上电后异步 0x4A 查询，initialize 发出时可能未就绪 → 回空）；平台核对版本请用 `loop_version_query`（§4.25）。
+
 
 ## 5.2 线圈传感数据 `loop_data`
 
@@ -1359,6 +1415,7 @@ dld960/{dev_serial}/{direction}
 | V1.05 | 2026-07-15 | 增加**设备时钟同步**（§2.3，方案B）：设备无 RTC，`initialize` 上线后平台经 `report_config` 命令下发 Unix `ts`，设备据此校准，之后上行 `ts` 为真实 Unix 时间；校准前为上电秒数 | wangfq |
 | V1.06 | 2026-08-04 | 增加**脱机事件日志**命令：`log_stat`（统计/分页定位）、`log_query`（按全局序号分页，count≤4）、`log_clear`（清除+审计留痕）；§2.3 补充日志双时间戳语义（`ts_ms` 相对 + `unix_ts` 已同步，0=未同步，锚点回算规则） | wangfq |
 | V1.07 | 2026-08-18 | `log_stat` / `log_query` / `log_clear` 增加**快照流**支持（`stream=snapshot`，与 BLE 0x28/0x29/0x2A 同语义）：快照统计 capacity 随芯片动态（48064~449472）、快照分页 count≤1（4 通道记录 JSON ~810B 超发送缓冲，实测修正；BLE 原始通道仍 ≤2）、快照清除审计留痕；`capacity`/`count` 类型修正为 uint32（W25Q256 事件流 130944 超 16bit） | wangfq |
+| V1.10 | 2026-08-20 | **网络上报携带地感版本**（配合远程 OTA 升级前后版本核对）：`dev_info_query` 响应 + `initialize` 上报新增 `loop_ver`/`loop_hw_ver`（地感 Loop MCU 固件/硬件版本，格式 `"主.次.次"`，来自 0x4A 查询缓存，尽力携带可为空）；新增命令 `loop_version_query`（§4.25，srv→dev 实时查询，设备经 UART2 0x4A 异步查询后回包，含 `loop_ver`/`loop_hw_ver`/`version_str`）；版本语义：`soft_ver`=整机 DBN 固件（`主.次`），`loop_ver`=地感 Loop 固件（`主.次.次`），二者区分 | wangfq |
 | V1.09 | 2026-08-20 | **OTA 刷写结果判定修复**（现场：刷写物理成功但平台误判"刷写未启动"）：① 刷写成功后台侧状态回 `idle`（镜像保留：`size`/`crc32`/`version` 不变，`last_result=0`，可重刷），与"下载完成待刷 `ready`"严格区分；② `ota_report` 升级为刷写结果**主依据**（`stage=done`/`failed` 设备必报，重发 3 次×5s），`ota_status` 仅兜底；③ 明确平台判定指引——`idle+size>0+last_result=0`=成功，不得以轮询未见 `flashing` 或状态持续 `ready` 判"刷写未启动"（本地刷写 <1s，轮询大概率错过中间态）；④ `ota_begin` 兼容 `idle+size/crc32 一致` → 免下载直接可刷（重刷） | wangfq |
 | V1.08 | 2026-08-20 | 增加 **Loop MCU 远程 OTA**（ROADMAP P1.4 ①，先存后刷）：命令 `ota_begin` / `ota_data` / `ota_end` / `ota_abort` / `ota_flash` / `ota_status`（srv→dev）+ `ota_report`（dev→srv）；单片 256B + 单片/全镜像 CRC32（ISO-HDLC，§4.19.1）；断点续传（`ota_begin` 返回 offset）；Slot A/B 双槽回滚（镜像 ≤96KB）；`ota_flash` 安全窗口检查 + 非阻塞 tick 驱动刷写（刷写窗口内 MQTT 保活/IWDG 不受影响）；会话期间暂停 `event_report` 发送与脱机日志落盘；`event_report` 扩展 `type=ota_error` 失败告警；§2.2 补 OTA 细分错误码（err_code）；老固件兼容（`ota_*` 回 code=4） | wangfq |
 

docs/DLD960_MQTT_OTA协议.md

@@ -494,10 +494,10 @@ typedef struct {          /* 64B */
 
 | 协议文档 | 变更 |
 |----------|------|
-| `DLD960_IoT_MQTT协议.md` | 本设计并入后升 **V1.08**：§3 命令表 + §4.19~4.24（ota_* 详情）+ §5.5（ota_report）+ §5.3 事件类型表补 `ota_error` + §8 错误码补 err_code 约定 + 修订记录 |
+| `DLD960_IoT_MQTT协议.md` | 本设计并入后升 **V1.08**：§3 命令表 + §4.19~4.24（ota_* 详情）+ §5.5（ota_report）+ §5.3 事件类型表补 `ota_error` + §8 错误码补 err_code 约定 + 修订记录；**V1.10 补充版本核对**：`dev_info_query`/`initialize` 带 `loop_ver`/`loop_hw_ver`，新增 `loop_version_query`（§4.25）供平台升级前后核对地感版本 |
-| `DLD960_TCP_JSON协议.md` | 本版**不扩展**（ROADMAP 先走 MQTT）；后续按"复用命令 + stream/字段"模式补（与 log_* 扩展同套路） |
+| `DLD960_TCP_JSON协议.md` | 本版**不扩展**（ROADMAP 先走 MQTT）；后续按"复用命令 + stream/字段"模式补（与 log_* 扩展同套路）。注：TCP 侧 `loop_version_query` 代码已有（`tcp_json_srv.c`），文档待同步 |
 | `DLD960_BLE协议.md` | 不变（BLE OTA 维持流式透传现状；本地刷写状态机与 BLE 透传共用 `lup_feed_byte_ota`） |
-| `README.md` / `DLD960_技术规格书.md` | 协议矩阵同步 V1.08；规格书补 OTA 分区/安全约束（并入主文档时执行） |
+| `README.md` / `DLD960_技术规格书.md` | 协议矩阵同步 V1.10 |
 
 **固件代码落点（协议拍板后动）：**
 - `iot_mqtt_srv.c`：命令分发链加 6 个 ota_* 分支（现有 if-else 链）

docs/DLD960_技术规格书.md

@@ -106,7 +106,7 @@ DLD960 是一款基于环形线圈（LC 振荡）检测原理的四通道车辆
 |------|------|------|------|
 | DLD960 串口通信协议 | V1.01 | TTL | 设备管理、参数配置、数据上报 |
 | DLD960 TCP JSON 协议 | V1.03 | ETH :5960 | 密码鉴权 + 18 条命令；event_report 客户端必答（5s×3 重发）；脱机日志 log_stat/log_query/log_clear（事件/快照流，stream 区分） |
-| DLD960 IoT MQTT 协议 | V1.09 | ETH → Broker | 双主题 `dld960/{sn}/srv`+`/dev`；initialize 上线、loop_data 三档调度、event_report 平台必答、设备时钟同步、脱机日志 log_stat/log_query/log_clear（事件/快照流，stream 区分）；Loop 远程 OTA（ota_begin/ota_data/ota_end/ota_abort/ota_flash/ota_status + ota_report，256B/片 CRC32，先存后刷断点续传，Slot A/B 双槽回滚） |
+| DLD960 IoT MQTT 协议 | V1.10 | ETH → Broker | 双主题 `dld960/{sn}/srv`+`/dev`；initialize 上线、loop_data 三档调度、event_report 平台必答、设备时钟同步、脱机日志 log_stat/log_query/log_clear（事件/快照流，stream 区分）；Loop 远程 OTA（ota_begin/ota_data/ota_end/ota_abort/ota_flash/ota_status + ota_report，256B/片 CRC32，先存后刷断点续传，Slot A/B 双槽回滚） |
 | DLD960Loop 串口协议 | V1.05 | MCU 间（内部） | 0x7F 帧、0xC0 传感上报（variation 3B 有符号） |
 | DLD960 BLE 协议 | V1.02 | 蓝牙 BLE | 帧格式 + 分包；脱机日志 OFFLOG_STAT/QUERY/CLEAR + 传感快照 SNAP_STAT/QUERY/CLEAR（0x28/0x29/0x2A），与 MQTT/TCP 同语义 |