docs(MQTT): DLD960_IoT_MQTT协议 V1.10→V1.11 — 4G 通道适配(方案B hex透传)

方案 B(原始帧透传 + hex 封装)正式并入主协议:
- 新增 §6 4G 通道适配: 架构(0x7F帧透传)/命令面差异/上行 frame_report/下行 frame_cmd/不支持命令/link 对象/平台要求
- §3 命令详表加 frame_cmd + frame_report(4G 通道专用标注)
- 头部版本行 + 修订记录 V1.11
- 4G 通道: 不使用有线标准 JSON 业务命令;网络配置类命令回 code=4
- 实施主体: Air8781P(Air780EPM) vd960Air 工程;vd960DBN UART1 通道列入计划(固件未实现,如实标注)
- 同步: README 索引 V1.11 + devlog 置顶条目(协议先行)

docs/DLD960_IoT_MQTT协议.md

@@ -2,6 +2,7 @@
 
 > 基于《DLD960 串口通信协议》V1.01，将设备管理、参数配置、数据上报映射到 MQTT 协议。
 > 交互格式：JSON。
+> 版本：V1.11（2026-08-31，4G 通道适配）
 
 ---
 
@@ -160,11 +161,15 @@ dld960/{dev_serial}/{direction}
 | `ota_flash` | 触发本地 ISP 刷写（仅 ready 态） | srv→dev | — |
 | `ota_status` | 查询 OTA 状态（含进度） | srv→dev | — |
 | `loop_version_query` | 实时查询地感 Loop MCU 版本（V1.10） | srv→dev | 0x4A |
+| `frame_cmd` | 4G 通道原始帧透传下发（hex 封装，V1.11） | srv→dev | — |
 | `initialize` | 设备上电初始化登陆  | dev→srv | — |
 | `loop_data` | 线圈传感数据上报 | dev→srv | 0xC0 |
 | `event_report` | 事件上报（**平台须应答**，见 §5.3） | dev→srv | — |
 | `ota_report` | OTA 进度/结果主动上报 | dev→srv | — |
 | `heartbeat` | 设备心跳 | dev→srv | — |
+| `frame_report` | 4G 通道原始帧透传上报（hex 封装，V1.11） | dev→srv | — |
+
+> ⚠ `frame_cmd` / `frame_report` 为 **4G 通道专用**（方案 B：原始帧透传，见 §6），有线通道不使用。4G 通道不使用有线标准 JSON 业务命令（loop_data / event_report 等）。
 
 ---
 
@@ -1403,6 +1408,122 @@ dld960/{dev_serial}/{direction}
 
 ---
 
+# 6 4G 通道适配（方案 B：原始帧透传 + hex 封装，V1.11 新增）
+
+> 适用场景：vd960DBN 有线网络失效时，经 **Air8781P 整板（Air780EPM 4G 模组，LuatOS vd960Air 工程）** 兜底上报。
+> 4G 通道与有线通道**命令面不同**（见 §6.2），平台须按通道区分解析。
+
+## 6.1 通道架构
+
+```
+上行: vd960Loop --0x7F帧(UART2)--> vd960DBN --原样转发(UART1)--> Air780 --MQTT frame_report--> 平台
+下行: 平台 --MQTT frame_cmd--> Air780 --原样(UART1)--> vd960DBN --0x7F帧(UART2)--> vd960Loop
+```
+
+- **魔数分流（在 vd960DBN 侧）**：`0x7F` 帧 → 转发 UART2（vd960Loop 地感）；`0x8F` 帧 → DBN 本地处理（BLE/串口配置命令同源）
+- **Air780 职责**：0x7F 帧切包（Lua 状态机，只切包不懂内容）+ MQTT 收发 + hex 封装
+- **vd960DBN 职责**：UART2↔UART1 双向转发（复用 `manage_dbn_ble_transparent` 透传模式；列入 vd960DBN 开发计划，**固件未实现**）
+- **链路层（UART）**：数据面 0x7F 帧字节流透传（0x7F 帧自带 LEN/校验，Air780 按帧切包）；`0x7D` 帧仅用于 DBN↔Air780 配置同步下发/握手（详见 vd960Air 工程 readme §3）
+
+## 6.2 命令面差异
+
+| 通道 | 上行（dev→srv） | 下行（srv→dev） |
+|------|----------------|----------------|
+| 有线（ETH MQTT） | initialize / loop_data / event_report / heartbeat / ota_report（标准 JSON） | dev_serial_set / ssc_net_* / iot_net_* / loop_param_* / report_config / log_* / ota_* / loop_version_query（标准 JSON） |
+| 4G（Air780 透传） | **frame_report**（hex 帧，§6.3）+ initialize（JSON，§6.3.1） | **frame_cmd**（hex 帧，§6.4） |
+
+- 4G 通道**不使用**有线通道的标准 JSON 业务命令（loop_data / event_report 等）
+- 4G 通道**不适用**的网络配置类命令：`ssc_net_set` / `ssc_net_query` / `iot_net_set` / `iot_net_query` / `iot_topic_set` / `iot_topic_query`（4G 接入网是 SIM 运营商网络，APN/主题由 4G 侧管理；经 4G 通道下发返回 `code=4`）
+- 其余命令（loop_param_*、log_*、ota_*、pwd_*、report_config、device_reset 等）可由平台经 `frame_cmd` 下发 `0x8F` 帧由 DBN 本地处理，或 `0x7F` 帧转发 vd960Loop——设备侧指令面不变
+
+## 6.3 上行 `frame_report`
+
+> Topic: `dld960/{sn}/dev` · QoS 1 · 每个 0x7F 帧一条
+
+```json
+{
+  "msg_id": 123,
+  "cmd": "frame_report",
+  "ts": 1719000000,
+  "data": { "frame": "7f00c0060102030405aabb" },
+  "link": { "imei": "860012345678901", "iccid": "89860012345678901234", "imsi": "460001234567890", "msisdn": "", "csq": 23, "net": "4G" }
+}
+```
+
+| data 字段 | 类型 | 说明 |
+|-----------|------|------|
+| `frame` | string(hex) | **0x7F 帧完整字节 hex**（含魔数 0x7F/校验字节），小写；平台按《DLD960Loop_串口通信协议》解析（0xC0 传感 / 0x0C 响应 / 事件等） |
+
+- `link` 为 4G 特有字段（§6.6），每条上行携带
+- `msg_id` / `ts` 由 Air780 生成；`ts` 校准遵循 §2.3（见 §6.3.1）
+
+### 6.3.1 4G 通道 `initialize`（JSON）
+
+4G 通道的 `initialize` 由 **Air780** 在 MQTT 连接成功后发送（标准 JSON 形态 + `link`），用于：① 平台识别 4G 设备上线；② 平台下发 `report_config` 校准 `ts`（§2.3）。
+
+```json
+{
+  "msg_id": 1,
+  "cmd": "initialize",
+  "ts": 3,
+  "data": { "loop_ver": "1.0.5", "loop_hw_ver": "1.0" },
+  "link": { "imei": "860012345678901", "iccid": "89860012345678901234", "imsi": "460001234567890", "msisdn": "", "csq": 23, "net": "4G" }
+}
+```
+
+- `loop_ver` / `loop_hw_ver`：地感 Loop 版本（与 §4.25 同语义；vd960DBN 未实现 UART1 通道前可省略）
+- 后续传感/事件/响应数据一律经 `frame_report`
+
+## 6.4 下行 `frame_cmd`
+
+> Topic: `dld960/{sn}/srv` · QoS 1
+
+```json
+{
+  "msg_id": 456,
+  "cmd": "frame_cmd",
+  "ts": 1719000100,
+  "data": { "frame": "7f000809010203040506" }
+}
+```
+
+| data 字段 | 类型 | 说明 |
+|-----------|------|------|
+| `frame` | string(hex) | 0x7F 帧（→ vd960Loop 地感指令）或 0x8F 帧（→ vd960DBN 本地配置）hex |
+
+- Air780 收到 → hex 解码 → 原始字节 → UART1 → vd960DBN 魔数分流
+- 地感/设备响应经 `frame_report` 上行
+
+## 6.5 4G 通道不支持的命令
+
+| cmd | 说明 |
+|-----|------|
+| `ssc_net_set` / `ssc_net_query` | SSC 有线网络配置（4G 不适用） |
+| `iot_net_set` / `iot_net_query` | IoT 有线网络配置（4G 不适用） |
+| `iot_topic_set` / `iot_topic_query` | Topic 配置（4G 主题由 Air780 配置） |
+
+> 经 4G 通道下发以上命令：设备回 `code=4 unsupported`。
+
+## 6.6 link 对象（4G 特有字段）
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| `imei` | mobile.imei() | 4G 模块 IMEI，设备唯一标识 |
+| `iccid` | mobile.iccid() | **流量卡卡号**，物联网卡管理识别用（卡商未写入 → 空串） |
+| `imsi` | mobile.imsi() | IMSI（部分卡返回空） |
+| `msisdn` | mobile.msisdn() | 手机号（物联网卡通常拿不到 → 空串） |
+| `csq` | mobile.csq() | 信号强度 0-31（31 最强，99/255 无信号） |
+| `net` | 固定 "4G" | 网络制式（预留扩展） |
+
+## 6.7 平台侧要求
+
+1. **双通道区分**：有线通道按标准 JSON 业务命令解析；4G 通道按 `frame_report` / `frame_cmd` 解析（可依 `link.net` 或报文形态区分）
+2. **新增解析依赖**：《DLD960Loop_串口通信协议》（hex → 0x7F 帧 → 字段）
+3. **设备唯一标识**：`dev_serial` 与有线通道同一序列号（Topic 族一致，平台认同一台设备）；`link.imei` / `link.iccid` 辅助 4G 设备/流量卡管理
+4. **时钟校准**：Air780 上线发 `initialize`（JSON + link）后，平台照常下发 `report_config` 校准 `ts`（§2.3）
+
+---
+
 # 修订记录
 
 | 版本 | 修订时间 | 修订说明 | 修订人 |
@@ -1415,6 +1536,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.11 | 2026-08-31 | **4G 通道适配（方案 B：原始帧透传 + hex 封装）**：新增 `frame_report`（dev→srv，§6.3）/ `frame_cmd`（srv→dev，§6.4）两命令（4G 通道专用）；4G 通道**不使用**有线标准 JSON 业务命令（loop_data/event_report），不适用网络配置类命令（ssc_net_*/iot_net_*/iot_topic_*，4G 通道下发回 code=4）；上行附加 `link` 对象（IMEI/ICCID/IMSI/MSISDN/CSQ，§6.6）；链路层数据面 0x7F 帧字节流透传（魔数分流在 vd960DBN 侧），0x7D 帧仅 DBN↔Air780 配置同步/握手；平台双通道区分解析 + 新增《DLD960Loop_串口通信协议》解析依赖（§6.7）；实施主体：Air8781P（Air780EPM）vd960Air 工程，vd960DBN UART1 通道列入开发计划（固件未实现） | 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 |