71 lines
7.5 KiB
Markdown
71 lines
7.5 KiB
Markdown
---
|
||
name: embedded-app-pc-debug
|
||
description: 用于 Windows 电脑端的嵌入式应用调试，包括远程编译、NFS 模块部署、开机进程与加密参数调试，以及设备发现、ROM 升级、串口监测和故障诊断。适用于 Eapil/CamTells 工作流；普通代码开发或仅查看已有日志时不要自动触发。
|
||
---
|
||
|
||
# Windows电脑端调试
|
||
|
||
完成从远程工程构建到设备升级验证的闭环，并保留足够证据判断失败发生在哪个阶段。
|
||
|
||
## 按需读取
|
||
|
||
- 涉及远程编译、工程定位、软链接、下载产物时，读取 [references/build-workflow.md](references/build-workflow.md)。
|
||
- 涉及 NFS 模块部署、`DxMain`、开机启动脚本、工厂模式或加密 param 时，读取 [references/application-debugging.md](references/application-debugging.md)。
|
||
- 涉及广播搜索、基础信息、EPFP 文件传输或升级时，读取 [references/device-protocols.md](references/device-protocols.md)。
|
||
- 涉及串口监测、升级成功判据或故障定位时，读取 [references/validation-and-diagnostics.md](references/validation-and-diagnostics.md)。
|
||
- 涉及 Linux 打包任务与 Windows 设备任务之间交接时，读取 [references/cross-host-coordination.md](references/cross-host-coordination.md)。
|
||
|
||
只读取当前任务需要的参考文件。不要因为用户仅要求串口查看而加载远程打包流程。
|
||
|
||
## 默认环境
|
||
|
||
- SSH 配置主机：`emb.eapil.com`
|
||
- 远程工程搜索根：优先现有工作区、`~/work/develop/gitcode` 和实际挂载点；`/CamTells` 仅是兼容候选
|
||
- 默认 Public 来源：`~/work/develop/gitcode/EMX2.1`
|
||
- 本地归档根目录：`F:\tmp\embedded-app-pc-debug`
|
||
- 串口默认值：`115200`、`8N1`、无流控
|
||
|
||
这些都是可覆盖的默认值。不要硬编码项目、SN、IP、COM 口或 ROM 文件。
|
||
|
||
## 工作方式
|
||
|
||
1. 根据用户请求确定需要执行的阶段；不强迫每次都完成整条链路。
|
||
2. 自己调查文件、脚本参数、网卡和设备响应等可查事实，只向用户询问真正需要选择的事项。新设备调试开始前先枚举串口并让用户选择串口或 Telnet；即使只有一个 USB 串口也不自动打开。串口必须取得本次用户确认的 COM 口；Telnet 必须先取得完整 SN 和型号。
|
||
3. 将每次完整任务归档到 `<根目录>\<项目>\<YYYYMMDD-HHmmss>`，分别保存 `firmware` 和 `logs`。
|
||
4. 搜索可以按型号、IP 或唯一响应列出候选，但这些条件都不能替代完整 SN。Telnet、升级及其他设备写操作必须以用户给出的完整 SN 精确匹配目标，并核对型号；多个候选或同一 SN 出现冲突时停止，不能默认第一台。
|
||
5. 先启动串口监测，再执行设备升级；串口输出同时实时显示并保存日志。需要在网页中查看日志或向设备输入命令时，使用单进程串口网页控制台，避免采集进程和发送进程争用同一个 COM 口。网页首次打开显示最新日志，所有发送内容都写入文本日志，空输入也必须发送真实 `CR`。刷新网页不能中断采集；多个页面共用服务时仅关闭最后一个页面才触发停止。最后页面关闭后，即使处于升级期间，也要在约 `5` 秒内结束采集、保留日志并释放 COM 口；之后必须重新启动控制台才能再次连接。
|
||
6. 在 ROM 传输前集中显示目标 SN、型号、IP、当前版本、ROM 绝对路径、大小、SHA-256、可解析的目标版本、串口状态和所有无法验证的项目。
|
||
7. 只有用户在看到上述信息后明确确认升级，才能传输 ROM、烧录或触发重启。之前对搜索、编译或诊断的授权不能替代这次确认。
|
||
8. 升级失败后先诊断并保留证据，不自动重试；再次升级需要新的明确确认。
|
||
|
||
串口优先不等于自动选择。用户选择串口后，只有端口打不开、无数据、乱码或无法登录时才建议回退 Telnet；切换前告知用户，Telnet 连接前重新广播核对完整 SN、型号和当前 IP。网络异常但串口可用时可以在用户确认 COM 口后做只读检查；设备写入、停止进程、修改启动项或重启前还需确认该串口对应的目标 SN 和型号。固件升级不得绕过协议身份核验。
|
||
|
||
用户如果只要求“显示串口”或“实时看日志”，仅打开只读串口监测；用户希望在页面持续查看时可以使用本地串口网页控制台，但不自动发送命令、搜索设备、登录、打包、传输文件或升级。
|
||
|
||
## Git 与构建边界
|
||
|
||
- 不执行编译前 `git status` 检查，不因未提交修改阻止打包。
|
||
- 不自动提交、推送、暂存、还原或清理任何仓库修改。
|
||
- 默认执行 `EmxGitInfo` 并保存输出作为版本凭证；失败时记录原因。临时验证包可继续，正式发布是否继续由用户决定。
|
||
- 不使用旧 ROM 冒充本次产物。构建脚本若明确宣告 ROM 目标成功并验证了本次 ROM，之后仅辅助全量镜像步骤失败时，可以交付“仅供局域网升级的 ROM”，但不能声称完整发布包成功。
|
||
|
||
## 工具脚本
|
||
|
||
- `scripts/device_upgrade.py`：V2 `30101` 身份预检与 `EPFP/4001` 升级。缺少 `--execute` 时绝不发送 ROM。
|
||
- `scripts/serial_monitor.ps1`：无第三方依赖的 Windows 串口实时输出、原始字节保存和带时间戳文本日志。
|
||
- `scripts/serial_web_console.ps1`：使用 Windows PowerShell 5.1 启动本地串口网页控制台；由单个进程独占 COM 口并同时负责接收、记录和发送，页面仅监听 `127.0.0.1`，写操作和关闭通知使用随机会话令牌。网页只提供用户主动输入和发送，不启动 U-Boot 持续按键或自动切换 A/B 分区。最后网页关闭后服务退出，不部署常驻管理进程或自动重连。必须用 `powershell.exe` 启动，不要改用 `pwsh.exe`。
|
||
- `scripts/v2_discover.py`：枚举适合广播的 Windows IPv4 网卡，从每个接口的本地 `8951` 向设备 `8941` 发送 V2 广播，并严格筛选完整 SN/型号。
|
||
- `scripts/module_debug.py`：应用模块部署预检和受保护执行；支持已打开的串口网页控制台或 Telnet，默认只读预检。`DxMain` 在线替换会检查 `daemon.sh`，关键系统服务默认拒绝替换。
|
||
|
||
运行脚本前先查看 `--help` 或 PowerShell 参数说明。不得绕过脚本的完整 SN、ROM 路径、日志目录和执行开关保护。
|
||
|
||
## 调试数据
|
||
|
||
这是设备调试 skill。用户已选择让终端和任务日志保留原始调试信息，不对 `30102`、串口或构建输出中的密码、密钥、Token 做自动脱敏；但不得把某台设备的真实凭据写入本 skill、脚本默认值或参考文档。
|
||
|
||
## 完成条件
|
||
|
||
不要把连接建立、ROM 发送结束、下载进度达到 100% 或 Flash 计数达到总量单独称为升级成功。至少需要明确的协议成功终态，并继续核对同一 SN 的重启、重发现、网络恢复和目标版本；无法取得某项证据时明确说明，不补造结论。
|
||
|
||
串口网页控制台发生变更时，还要验证服务代码能编译、Skill 结构有效、COM 口由单一进程占用、服务实际连接、接收字节或日志文件持续增长、普通发送与空回车都有 TX 记录，并确认页面首次打开定位到最新日志。还必须完成生命周期验收：刷新不中断、两个页面关闭一个仍运行、关闭最后页面后约 `5` 秒内进程退出且状态接口离线、日志具有结束标记、原日志与原始字节文件仍在原路径，并且下一次服务能重新打开同一 COM 口。仅看到服务进程或空白网页不算验证通过。
|