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 补字段
2026-08-20 22:18:08 +08:00
parent 51298693da
commit 3be9e504da
5 changed files with 68 additions and 9 deletions
@@ -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 | 硬件版本，格式 `"主.次"` |
-| `soft_ver` | string | 软件版本，格式 `"主.次"` |
+| `hard_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.soft_ver` | string | 固件版本 |
+| `data.hard_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 |