Update embedded app debugging workflow

references/device-protocols.md

@@ -11,43 +11,65 @@
 - `C:\Users\ZK\Downloads\设备端TCP文件传输类协议.md`
 - `C:\Users\ZK\Downloads\工厂协议V1.md`
 - `E:\CodeSpace\git-pro\eapil_qt_player_v2\EpProtocolDemo`
+- `E:\CodeSpace\git-pro\eapil_public_library\EapilPanoC\src`（V1 命令、端口、数据结构和 Qt 客户端实现；以当前源码为实现依据，部署设备仍需实测）
 
-## 协议资料总览
+## V1 协议（EapilPanoC）
 
-本技能覆盖的协议资料不止设备搜索和升级。按当前本机资料，范围包括：
+V1 与 V2 使用不同端口和帧格式，不能把 `EPBP/EPTP/EPFP` 的 V2 帧头套用到 V1 通用配置接口。
 
-| 协议族 | 资料范围 | 本技能的使用方式 |
+| 功能 | 传输与端口 | 请求/响应格式 |
 |---|---|---|
-| V1 工厂协议 | 66 条工厂/产测命令；UDP 搜索与 TCP 控制 | `scripts/v1_discover.py` 搜索；`scripts/v1_command.py` 对文档中任意 CMD 发送 JSON 请求 |
-| V2 广播发现 | EPBC/EPBD、UDP 8941/8951、cmd 60000 | `scripts/v2_discover.py` |
-| V2 统一配置 | cmd 30101 起，覆盖基本信息、网络、音视频、音频、设备操作、SD 卡、夜视、时间、OSD、IO 等文档章节 | TCP 8942；当前脚本仅做身份查询，其他命令按文档单独实现/调用；不得把语义协议误当作固定传输协议 |
-| V2 产测 | cmd 1–26，LED、按键、老化、带宽、PCBA、屏幕、MIC、SD、芯片、镜头等 | 文档定义命令语义；需使用匹配固件提供的传输封装 |
-| TCP 文件传输 | EPFP，2001/2002/3001/4001，端口 8943 | `scripts/device_upgrade.py` 实现 4001 固件升级；其余命令保留文档语义，不由该脚本执行 |
-| TCP 音视频播放 | 端口 8944，cmd 0x01–0x05 | 长连接心跳、解码器列表、播放控制及媒体帧；不是设备发现或升级通道 |
-| V2 工厂整合协议 | 工厂扩展命令及设备信息接口 | 按资料版本与设备支持情况使用；与 V1 工厂命令空间不能混用 |
+| 局域网搜索 | UDP `4942`，向广播地址 `4942` 发送并在本地 `4942` 接收 | `uint32 cmd + uint32 JSON长度 + UTF-8 JSON` |
+| 通用配置获取/查询 | TCP 设备端 `4941` | `uint32 cmd + uint32 payload长度 + payload`；常见无参读取长度为 0；响应为 `uint32 cmd + uint32 JSON/数据长度 + payload` |
+| 固件升级 | TCP 设备端 `4941` | `uint32 cmd + uint32 长度 + 32字节ASCII小写MD5十六进制文本 + ROM原始字节`；长度是 MD5 文本与 ROM 字节数之和 |
 
-“覆盖”指协议字段、命令范围、边界和现有脚本能力都在参考文档中可查；不代表每种协议都有通用执行器，也不代表所有固件都启用了每条命令。新增写操作前须逐条查对应协议的请求、响应和副作用。
+V1 多字节整数由源码中的 `QDataStream` 默认网络字节序编码（大端）。TCP 是字节流，必须先累积完整 8 字节响应头，再按头内长度读取完整 payload；不能假定一次 `recv` 返回一整帧。JSON 请求/响应的长度不包含 8 字节头。搜索响应也必须校验命令、长度和请求 `session`。
 
-## V1 工厂协议
+### V1 搜索
 
-V1 使用独立于 V2 的报文，不带 `EPBP`/`EPTP`/`EPFP` 同步字：
+源码：`EpSearchPanocsInLan.cpp`、`json/SerachCameraRequest.cpp`、`json/SerachCameraResponse.cpp`。
 
-```text
-uint32 CMD (network byte order)
-+ uint32 Data length (network byte order)
-+ Data bytes (normally UTF-8 JSON; optional)
+请求命令 `0x5a0eff00`，响应命令 `0x5a0eff01`。请求 JSON 至少带随机 `session`：
+
+```json
+{"session":12345}
 ```
 
-| 功能 | 传输 | 端口 | 命令 |
-|---|---|---:|---|
-| 设备发现请求/响应 | UDP 广播 | 设备 4942 | `0x5A0EFF00` / `0x5A0EFF01` |
-| 工厂/产测控制 | TCP | 4941 | 按 V1 文档中各接口的 CMD |
+响应常见字段：`session`、`ip`、`dev_type`、`sn`、`mac`、`firmware`、`hardware`、`dev_id`、`dev_ver`，部分设备另有 `ipv6`、`wifi_ssid`、`wifi_quality`。按回显 session 过滤本轮响应。搜索会列出广播域中的多台设备；不得把第一个响应当目标。升级或其他写操作仍要求完整 SN 与型号核验。若设备 SN 为空，只能将搜索结果用于只读信息查询；SN 空值不构成设备身份核验，不能据此绕过写操作的身份保护。
 
-搜索请求 Data 为 `{"session":<随机整数>}`。只接受 `0x5A0EFF01` 且回显本次 session 的响应。设备响应 JSON 保留原始字段；协议版本之间字段可能不同，型号、SN、IP、MAC 等信息必须根据实际响应展示，缺失即标为不可用。多网卡或设备搜索工具已占用 UDP 4942 时，先确定本机接口/端口状态；不结束占用进程。V1 搜索用 `scripts/v1_discover.py`，对单个接口显式指定 `--interface <本机IPv4>`。
+### V1 通用配置读取命令
 
-`scripts/v1_command.py` 是通用 TCP 请求器：指定 IP、CMD 和 JSON Data；默认仅显示预检，不建立连接。只有显式 `--execute` 才发送。它校验 TCP 响应头、长度和响应 CMD，但不解释各命令的业务成功字段、不判断写操作安全性，也不执行设备身份核验。因此必须先将发现的设备与完整 SN/型号人工核对；对写配置、复位、格式化、烧号或其他有副作用命令，先核实请求字段及后果并取得本次操作确认。不得用该通用脚本发送 ROM。
+以下命令来自 `EapilPanoCHead.h` 的 V1 `MessageCMDType`，对应 `EpPanoCConfigure.cpp` 的 getter/query 实现。大部分请求使用空 payload；按返回命令和 JSON `code` 判定设备是否支持，`code=0` 表示设备成功应答，不代表每个可选字段都存在。
 
-V1 工厂协议文档列出的 66 条命令及字段定义是命令语义来源。传输层客户端可承载这些 CMD，但各命令是否被具体型号/固件实现，仍需用对应版本文档或设备响应确认。V1 示例工程只实现了搜索和前五个 TCP 示例命令，不代表其它 V1 命令已在设备上验证。
+| 项目 | 命令 |
+|---|---:|
+| 获取 SN | `0x5a0e2100` |
+| 获取模板 | `0x5a0e2102` |
+| 获取基本信息 | `0x5a0e2104` |
+| 获取圆心坐标 | `0x5a0e2110` |
+| 查询视频参数范围 / 获取视频参数 | `0x5a0e2120` / `0x5a0e2121` |
+| 查询音频参数范围 / 获取音频参数 | `0x5a0e2130` / `0x5a0e2131` |
+| 查询 ISP 参数范围 / 获取 ISP 参数 | `0x5a0e2140` / `0x5a0e2141` |
+| 获取缩略图 | `0x5a0e2150`（二进制 JPEG，不按 JSON 解析）|
+| 获取 SD 卡信息 | `0x5a0e21a0` |
+| 获取网络信息 | `0x5a0e21b0` |
+| 获取 Wi-Fi 信息 | `0x5a0e21c0` |
+| 获取时间信息 | `0x5a0e21d0` |
+| 获取夜视信息 | `0x5a0e21e0` |
+| 获取浪涛兼容 ID | `0x5a0e3100` |
+| 获取大拿兼容 ID / danale.conf | `0x5a0e3200` / `0x5a0e3210` |
+
+兼容平台接口可能返回“不支持平台/命令”；要记录为设备能力结果，不要当作传输层故障。`0x5a0e3210` 返回配置内容，可能包含敏感字段；仅在用户任务确需时调用，控制原始结果的保存、展示和转发范围。V1 还定义工厂/扩展类读命令（如 PTZ、MAC、IMEI、老化测试、设备密码等），不属于上述通用配置接口；有的需要特定参数，有的会暴露敏感信息。不要用零参数盲发或把它们当作通用 getter。先从目标型号对应实现核对参数、返回结构和敏感性，再按明确任务范围调用。绝不调用 SET 命令来“探测”支持能力。
+
+### V1 固件升级
+
+V1 升级命令为 `0x5a0e2170`，TCP 端口 `4941`。实现依据 `EpConnection::sendTcpFile`：计算 ROM MD5 并转为 32 字节 ASCII 十六进制文本，帧长度字段等于 `32 + ROM字节数`，随后发送 MD5 文本及 ROM 内容。响应仍按 V1 `cmd + length + payload` 解析，成功 JSON 示例为 `{"code":0,"desc":"update success"}`。这不是 V2 `EPFP/4001` 的状态轮询协议；不得把 V2 的 `status=2` 要求硬套到 V1。V1 成功应答后仍须检查串口重启、网络恢复、重新搜索与目标版本回查；缺项必须明确标为未验证。
+
+执行升级前仍遵守本文“升级前保护”与主技能的用户确认要求。已有工具若只支持 V2，不能改参数伪装成 V1；应使用明确实现 V1 的客户端，并保留 ROM 路径、大小、MD5、SHA-256、目标 IP、型号、升级响应及升级后版本证据。完整 SN 缺失时不得以型号/IP 替代身份核验，也不得执行写操作。
+
+### V1 现场验证样例（C4662）
+
+2026-10-21 对一台 C4662 的实测仅作为该设备/固件的实例，不代表所有 V1 设备字段恒定：V1 搜索和基本信息返回 `dev_ver=2.0.20261021.1`、`firmware=1.0.4`、`dev_type=C4662`，但 SN 为空。常见 getter 中视频、音频、ISP、SD、网络、时间、夜视、缩略图和大拿 ID 接口有成功响应；模板、浪涛兼容接口和 danale.conf 在该设备返回失败或不支持。成功但无数据字段的响应（例如 Wi-Fi 信息）应如实记录，不推测配置值。
 
 ## V2 协议矩阵
 
@@ -74,7 +96,7 @@ V2 发现请求 JSON：
 - `outer.type`
 - `hardware.type`
 
-非关键网络字段允许缺失。完整 SN 是升级身份核对的首要依据。V1 的端口与帧格式必须从 V1 文档或已验证的 `EpProtocolDemo/V1` 获取，不能套用 V2。
+非关键网络字段允许缺失。完整 SN 是升级身份核对的首要依据。V1 的端口与帧格式见上文 V1 章节，并以目标设备对应的 V1 文档或源码复核；不能套用 V2。
 
 执行发现时使用 `scripts/v2_discover.py`，并遵守以下规则：
 
@@ -137,6 +159,8 @@ uint8 status
 - 多个 ROM 或设备候选时等待选择。搜索端口被占用或没有完成完整 SN 核对时不得升级。
 - 确认后调用 `scripts/device_upgrade.py --execute`，不绕过其保护参数。
 
+串口登录可以确认现场设备、读取版本并恢复网络，但不能替代升级前的 `30101` 身份响应。即使 COM 口已由用户确认且串口内的 SN、型号看似匹配，`30101` 超时、返回不完整或不匹配时仍不得发送 ROM。先检查设备端端口监听、接口 MAC、关联、DHCP、PC 多网卡选路和二层可达性；恢复后重新运行标准预检。
+
 ## 已知协议歧义
 
 - 状态章节没有明确说明每次状态是否带 EPFP 外层头，因此客户端兼容完整帧和裸状态。