hulk/HW-Debug-Tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 8 Wiki Activity
Files
51b560d840f309a743e8f7558470f7b1ffa64579
HW-Debug-Tools/agent.md
T

10 KiB
Raw Blame History

agent.md — 仓库交接档案（供后续 Agent 接手）

成文方式：2026-09-20 由一次会话从 git 全部 40 次提交（6243b8c…e354423）、 DLPilot/AGENTS.md、各级 README、.zcode/plans/ 计划文件还原整理；不含任何口头 讨论内容，一切以仓库工件为准。

分工：本文管"宏观脉络、决策史、待办"；工程约定/不变量/构建规程在 DLPilot/AGENTS.md（改代码前必读）；使用说明在根与各工具 README。

1. 项目定位

  • 本仓库是 LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板的调试上位机工具集， 服务上游固件仓 hulk/LT8619C_DLPC3421_HDMI（本机路径 E:\Hulk-Coding\LT8619C_DLPC3421_HDMI，同 Gitea 实例 gitea.hulk.wang）。 光机 RS485 协议唯一权威是上游仓 protocols.md，本仓不维护协议副本。
  • 两个工具：
    • DLPilot（原 HDMI-Tool）＝"3D 光固化光机调试台"：HDMI 源端（EDID/分辨率/ 测试图案投屏）+ 光机控制（RS485→板上 GD32E230 网关→DLPC3421）+ 电源检查 （PD 自检/FPDO 挡位判定/功率检测）。
    • I2C-Inject：RP2040 固件 + PC GUI，在 demo 板 I2C 总线上择机注入读写 LT8619C 寄存器（避让主控 500ms 轮询，写后读回校验）。

2. 当前状态快照（2026-09-24，v0.4.0）

  • 当前入口为 DLPilot/src/app_fluent.py，APP_VERSION = "0.4.0"；使用 PySide6-Fluent-Widgets。旧 app_gui.py 保留作历史对照，不再由入口加载。
  • 本次发布为 DLPilot-v0.4.0，源码、文档与 release/DLPilot.exe 合并为一个提交； zip 只上传 Gitea Release，不入库。远端完成状态以标签和附件查询为准。
  • 支持的模式、EDID 信息默认折叠；修复标题栏图标与 PD 成功状态绿色显示。
  • Light 显式同步 Qt 调色板、容器背景与 Windows 标题栏，浅灰主背景、白色卡片、深色文字； 保留 Dark/System 切换。主题不写入用户的 pattern_slots.json。
  • Qt 单文件打包收集 qfluentwidgets 资源与系统 icuuc.dll，启动注册并预加载 Qt/Shiboken DLL，避免 QtCore 导入失败。
  • 已完成源码编译、无硬件 RS485 自测（ALL PASS）、Qt 离屏浅色渲染检查和正式 EXE 定时启动退出（exit=0）。本次原生桌面自动化接口不可用，未完成成品 Light 截图； 不应将离屏截图等同于成品完整视觉或硬件验收。
  • 本机 release/pattern_slots.json 的 COM5 运行配置与 EDID-viewer/ 未跟踪目录 不属于本次发布；保留本地文件，提交及发布使用仓库预置配置。

3. 开发方向主线（时间线）

阶段 0 · 寄存器语义实测期（09-03） I2C-Inject + HDMI-Tool 首版落库。核心成果：0x606E 位交换 / 0x606D 整组顺序两个 寄存器语义经 demo 板逻辑分析仪双色交叉实测确立（LA 波形判读脚本 la_wave_analyzer*.py 即为该过程产物，配套 I2C-Inject 固件内置总线嗅探）。

阶段 1 · 工程化与发布流水线（09-10） 确立三区目录（src 人写 / assets 可再生 / release 交付）+ 双文档（README 给人 / AGENTS.md 给 Agent）；打通 build_exe → package_release → publish_gitea 流水线， 发布 HDMI-Tool v0.1.0。同期收录启动强制扩展显示拓扑与波形/注入脚本。

阶段 2 · 光机 RS485 控制集成（09-11，v0.2.0） 新增 dlpc_rs485.py：帧构造 D5 01 LEN <ASCII> CRC / 响应 B5 TYPE LEN <payload> CRC （累加和校验）、增量解析、译码表、DLPC485 链路类（daemon 线程+队列+回调， 模式照搬 I2C-Inject 的 Injector）。启动拓扑从"无条件扩展"改为智能判定。 串口下拉显示设备描述（CH344 多口可辨）。计划文件 .zcode/plans/plan-sess_a1d8*.md 即此阶段方案，已完整执行。

阶段 3 · GUI 重构与产品化（09-12，v0.3.0） feature/ctk-ui 分支完成 CustomTkinter 双栏仪表盘重构（规格：UI参考布局.svg）； 产品更名 HDMI-Tool → DLPilot（3D 光固化光机调试台）；光机串口参数化（默认 8-N-1）+ TEC 控制（M7/M8）与温度实时显示；DLP/Pilot 双行图标。

阶段 4 · 体验打磨（09-14，v0.3.1/0.3.2/0.3.3） 投屏退出语义两轮更名（"恢复桌面"→"停止投屏"→"停止测试图像"）；标题栏版本号； 清理残余 HDMI-Tool 引用与目录更名；修复 USB 拔出后同参数重连失效（掉线分支 清 _open_key）。

阶段 5 · 电源检查卡（09-1718，v0.3.40.3.6）

  • 电源自检：M301(协议)→M302(挡位电流)→M303(实测电压) 三步帧驱动状态机， FPDO 判定＝电压就近 PD 固定挡（5/9/12/15/20/28V ±5%）+ 挡位电流；12V 且 ≥3A 绿底，挡位不符红底，无匹配 ERR（CH224Q 电压配置寄存器只写不可读，只能实测判定）。
  • 功率检测：M303+M304+M305 三步序列 → 电压 V / 电流 mA / 功率 W（两位小数）。
  • M30x 载荷是二进制例外（SQ52205 实测）：大端原始值非 ASCII，必须走 payload_bytes()；M303=u16 mV、M304=s16 补码 mA、M305=u32 mW（LEN=4）。 封装在 payload_u16_be/payload_s16_be/payload_u32_be/format_power。
  • 伴随一串稳定性修复（详见 §4）。

阶段 6 · Fluent UI 重写（09-24，v0.4.0） PySide6-Fluent-Widgets 替换 CustomTkinter 主界面，延续 EDID、测试图案、RS485、 PD/功率/温度/电流及自定义槽位功能；GUI 图案窗口使用 Qt，CLI 图案仍走 tkinter。 补齐模式/EDID 折叠、PD 成功状态颜色、图标、Light 调色板与 Qt 单文件 DLL 加载。

4. 尝试过 / 推翻过 / 反复调过的思路（勿重蹈）

# 问题 最初做法 → 最终做法 / 教训
1 电源自检成功判定 先按 ASCII ok 前缀判成功 → 实机 M301 回包 payload=PD 无前缀被误判错误（9772a2b）→ 改按帧 TYPE=0xF0 译码分类。教训：M30x 系列回包不能按文本判
2 功率值来源 先用 M303×M304 计算 P=UI 占位显示（2b7d103，"待固件功率命令"）→ 固件提供 M305 直读 u32 mW 后改为三步序列直读（9b29b6a）
3 二进制载荷三连坑 ① Frame.payload 解出乱码 → 用 payload_bytes() 取原始字节；② M305 是 LEN=4，复用双字节解析会错 → 按 kind 校验长度；③ 日志行含 NUL 导致复制被截断 → 二进制载荷日志行以 hex 展示（e354423）
4 "串口断不开" 表象是断开逻辑 bug，实际根源是双实例互抢串口 → 单实例锁 + 串口占用提示（e87bf14）
5 窗口最大化卡顿 EDID 信息区 CTkScrollableFrame+40 余个逐行 Label，最大化时逐控件重绘 → 换 CTkTextbox 整体重排，开销低一个量级（30bc224）
6 启动强制扩展拓扑 无条件 SetDisplayConfig 扩展会打扰用户自选拓扑（如家里"仅第二屏幕"）→ 仅当未激活显示器 EDID 厂商字节为转接板签名 61 93("XLS") 时才拉回（d9ecff4）
7 GUI 框架 原生 tkinter → CustomTkinter 双栏仪表盘（84838e3）；v0.4.0 再迁移到 PySide6-Fluent-Widgets；旧 CTk 文件仅供历史对照
8 投屏退出按钮文案 "恢复桌面"→"停止投屏"→"停止测试图像"（3f35ad2→b167ce3）：最终语义是关测试图窗口，与显示拓扑恢复无关
9 USB 拔出后重连失效 掉线分支未清 _open_key，同参数重连被"参数未变"逻辑跳过 → 掉线同步清缓存（51e2f1c）
10 电源自检卡死 帧路由引用未定义变量 payload（3f36ead），改名/重构时注意帧回调的作用域
11 Gitea 发布 python urllib 访问该实例间歇 SSL: UNEXPECTED_EOF → 必须 --insecure；GET /releases/tags/{tag} 的 assets 是纯数组而 GET /releases/{id} 是 {items:[...]}，publish_gitea.py 已兼容两种形状，勿"简化"；请求自动重试已加（f0f8073）

5. 未实操 / 待办清单（接手者从这里挑活）

5.1 v0.4.0 发布交接

v0.4.0 已覆盖未单独发布的 v0.3.6 功能与本次 Fluent UI 改动，无需另发 v0.3.6。 发布时先推送代码与同提交标签，再上传 DLPilot-v0.4.0-win64.zip； 核对远端标签提交、附件名称/大小，并记录验证结果。若需补传，先查询资产，避免重复上传。

5.2 【待硬件】0x606E 的 0x40/0x80 两组位交换

demo 板仅实测了 bit5(0x20)=镜像 D[7:0]；0x40/0x80 对另外两组未单独实测， 等自板（转接板）点亮时用 I2C-Inject 验证（见 I2C-Inject/README §3）。

5.3 【待素材】校准图案槽位预置为空

测试图案卡第二排 5 个槽位 UI 标注"校准图案(齿轮改图)"，为 3D 光固化测试/校准图 预留；release/pattern_slots.json 中这些槽位 file: null。拿到校准图素材后： 放 assets/ → 生成脚本入库 → 更新预置 slots → 重新打包。

5.4 【待真机帧】M305 回归向量是算法推演帧

selftest_rs485.py 中 M303/M304 用真机帧，M305 向量是按协议推演的；拿到真机 M305 回包后替换向量，使回归更实。

5.5 README 已同步

本次已将根 README 与 DLPilot/README 的安装依赖、界面描述和日期更新到 v0.4.0。

5.6 【明确"不做"，非待办】

  • TI 原始 I2C 命令透传不做：GD32 网关固件只收 ASCII M 命令集（v0.2.0 计划的 显式决策）。
  • 不引入 pyserial 硬依赖：保持 try-import + HAS_* 标志 + 缺失降级的可选依赖 模式（Pillow 同理）。

6. 快速上手（完整规程见 DLPilot/AGENTS.md §5/§7）

cd DLPilot/src
python -m compileall -q .            # 编译检查
python selftest_rs485.py             # 光机协议回归（改 dlpc_rs485.py 后必跑）
python hdmi_gui.py --seconds 5       # GUI 冒烟
python build_exe.py                  # 打包 → ../release/DLPilot.exe
python package_release.py 0.4.0      # 组装当前版本 zip；新版本先更新 APP_VERSION
python publish_gitea.py ../release/DLPilot-v0.4.0-win64.zip --replace --insecure

上游协议/寄存器语义问题先查上游仓 protocols.md 与 doc/architecture/； 本仓改动约束（目录契约、12 条代码不变量、领域测试值含义）以 DLPilot/AGENTS.md 为准，其中领域语义的测试值（55/AA/FF、640x360、800x600@60）有明确用途，勿顺手改。

Reference in New Issue View Git Blame Copy Permalink