109 lines
6.0 KiB
Markdown
109 lines
6.0 KiB
Markdown
# 设备发现、基础信息与升级协议
|
||
|
||
仅在任务涉及设备网络发现、版本查询或 ROM 传输时读取本文件。优先使用用户提供的最新协议、现有已验证实现和抓包；文档歧义不得伪装成确定事实。
|
||
|
||
## 本机参考资料
|
||
|
||
存在时优先核对：
|
||
|
||
- `C:\Users\ZK\Documents\ChatGPT\日常开发\调试资料\设备端协议V2-工厂整合版本.md`
|
||
- `C:\Users\ZK\Documents\ChatGPT\日常开发\调试资料\设备端统一配置协议V2.md`
|
||
- `C:\Users\ZK\Downloads\设备端TCP文件传输类协议.md`
|
||
- `C:\Users\ZK\Downloads\工厂协议V1.md`
|
||
- `E:\CodeSpace\git-pro\eapil_qt_player_v2\EpProtocolDemo`
|
||
|
||
## V2 协议矩阵
|
||
|
||
| 功能 | 传输与端口 | 帧格式 |
|
||
|---|---|---|
|
||
| 设备发现请求 | UDP，客户端从本地 `8951` 向设备 `8941` 广播 | `EPBP + uint32长度 + UTF-8 JSON` |
|
||
| 设备发现响应 | UDP，客户端 `8951` 接收 | 同上，完整帧在一个数据报内 |
|
||
| 统一配置 | TCP，设备 `8942` | `EPTP + uint32长度 + UTF-8 JSON` |
|
||
| 固件升级 | TCP，设备 `8943` | `EPFP + uint32命令 + uint32长度 + 二进制数据` |
|
||
|
||
多字节整数使用网络字节序。配置 TCP 长度端序在整合文档中没有单独声明，但现有设备和客户端验证采用网络序。
|
||
|
||
## 发现与身份
|
||
|
||
V2 发现请求 JSON：
|
||
|
||
```json
|
||
{"cmd":60000,"session":12345}
|
||
```
|
||
|
||
响应必须回显相同 `cmd/session`。身份字段包括 `sn`、顶层烧录 `mac`、`inner`、`outer`、`hardware` 和 `net`。顶层 `mac` 与 `net.mac` 可能不同。型号判断同时展示：
|
||
|
||
- `inner.type`
|
||
- `outer.type`
|
||
- `hardware.type`
|
||
|
||
非关键网络字段允许缺失。完整 SN 是升级身份核对的首要依据。V1 的端口与帧格式必须从 V1 文档或已验证的 `EpProtocolDemo/V1` 获取，不能套用 V2。
|
||
|
||
执行发现时使用 `scripts/v2_discover.py`，并遵守以下规则：
|
||
|
||
1. 默认枚举已启用、已连接且具有有效 IPv4 的物理网卡；回环、断开、APIPA、VPN、VMware、Npcap 等接口要列出并注明排除原因。用户明确要求所有活动接口时才加入虚拟接口。
|
||
2. 每个接口分别绑定其本地 IPv4 和客户端端口 `8951`，同时发送有限广播 `255.255.255.255` 和按前缀计算的定向广播。不能把 `/22` 的广播地址按 `/24` 猜测。
|
||
3. 如果 UDP `8951` 被 EapilCameraConfigurer 或其他进程占用，报告占用者，不结束进程；请用户释放端口，或使用已有工具明确支持的搜索结果。
|
||
4. 从临时源端口发包只可作为诊断。设备可能只向 `8951` 回复，因此临时端口无响应不能证明设备离线。
|
||
5. 打印所有合法候选并按完整 SN 精确匹配；不得选择第一台。响应需校验 `EPBP`、长度、`cmd/session`。只有 SN、源 IP、MAC 和型号都一致的重复响应可以合并；同一 SN 对应不同身份信息时报告冲突并禁止自动选择。
|
||
6. 未提供完整 `--expected-sn` 时脚本只是列表模式，即使退出码为 0 也不代表身份核验成功。Telnet、升级及其他设备写操作必须提供完整 SN，并根据任务要求同时传入型号。
|
||
|
||
## 基础信息
|
||
|
||
通过 TCP `8942` 发送 `cmd=30101`。响应必须满足：同步头正确、长度合理、`cmd/session` 匹配且 `code=0`。读取：
|
||
|
||
- `sn`、`mac`
|
||
- `inner.type/version`
|
||
- `outer.type/version`
|
||
- `hardware.type/version`
|
||
|
||
`hardware.version` 不是固件版本。升级后应根据 ROM 类型比较 `inner.version` 或 `outer.version`。如果无法从 ROM 或构建记录确定应变化的字段，必须明确说明并让用户确认预期。
|
||
|
||
`30102` 可能返回密码和密钥，只在调试任务确实需要时调用。用户选择保留原始调试数据，因此响应可原样写入本次任务日志，但不得写入 skill 本体。
|
||
|
||
## 固件升级 4001
|
||
|
||
请求：
|
||
|
||
```text
|
||
EPFP
|
||
+ uint32 4001
|
||
+ uint32 ROM字节数
|
||
+ ROM原始字节
|
||
```
|
||
|
||
ROM 前没有 MD5 或目标路径业务前缀。不要把普通文件写入 `2001` 的 MD5 机制声称为升级 `4001` 自带校验。
|
||
|
||
状态业务数据为 21 字节：
|
||
|
||
```text
|
||
uint8 status
|
||
+ uint32 sessionId
|
||
+ uint32 downloadTotal
|
||
+ uint32 downloaded
|
||
+ uint32 flashTotal
|
||
+ uint32 flashed
|
||
```
|
||
|
||
状态：`0` 空闲、`1` 开始、`2` 完成、`3` 失败。`sessionId` 不等同于配置 JSON session，不要求匹配。解析器要兼容完整 `EPFP/cmd/length` 状态帧与设备实测出现的裸 21 字节状态，但完整帧必须校验响应命令为 `4001`。
|
||
|
||
只有 `status=2` 是协议成功终态；下载或 Flash 计数达到总量不能替代它。`status=3` 立即失败。连续 60 秒没有下载或 Flash 进度变化视为停滞，值允许覆盖。没有依据时不自动续传或重试。
|
||
|
||
设备报告的 `downloadTotal`、`flashTotal` 可能与 ROM 文件字节数不同，不能因为这种封装头、元数据或分区差异单独判失败。`status=2` 是协议成功终态；如果此时 `downloaded/flashed` 仍小于设备各自报告的非零总量，记录协议计数异常警告并纳入验证报告，但不自行推翻设备的成功终态。
|
||
|
||
## 升级前保护
|
||
|
||
- ROM 必须是普通文件，大小大于 0 且不超过无符号 32 位长度。
|
||
- 计算并记录 SHA-256；协议本身没有 ROM 签名或来源认证，不能声称 SHA-256 提供设备侧认证。
|
||
- 精确核对设备 SN。
|
||
- 同时展示当前型号和 ROM 目标型号。ROM 元数据无法解析时显示“无法验证型号”，并重新取得用户确认。
|
||
- 多个 ROM 或设备候选时等待选择。搜索端口被占用或没有完成完整 SN 核对时不得升级。
|
||
- 确认后调用 `scripts/device_upgrade.py --execute`，不绕过其保护参数。
|
||
|
||
## 已知协议歧义
|
||
|
||
- 状态章节没有明确说明每次状态是否带 EPFP 外层头，因此客户端兼容完整帧和裸状态。
|
||
- 没有规定分块大小、连接关闭方、断线恢复或统一总超时；使用可配置值并保存最后进度。
|
||
- 没有定义 ROM 与型号的自动匹配机制。
|
||
- TCP 是字节流，必须累积并按长度解析，不能把单次 `recv` 当作完整帧。
|