feat(HDMI-Tool): v0.2.0 集成光机控制(RS485→GD32网关→DLPC3421) — 本地提交, 待验证后再推送发布

HDMI-Tool/AGENTS.md

@@ -7,9 +7,11 @@
 ## 1. 项目定位
 
 仓库 `LT8619C_Debug_Tools` 是 LT8619C（HDMI→RGB888）→ DLPC3421 投影转接板的**调试上位机工具集**，
-上游主仓库（固件）为 `hulk/LT8619C_DLPC3421_HDMI`（同 Gitea 实例 `gitea.hulk.wang`）。
-本工具工作在 HDMI **源端**（PC 显卡侧），与固件侧寄存器调试（I2C-Inject 工具）配合。
-寄存器语义判读基线（0x606E 位交换 / 0x606D 整组顺序）在上游仓库 `doc/architecture/`，不在本仓库。
+上游主仓库（固件）为 `hulk/LT8619C_DLPC3421_HDMI`（同 Gitea 实例 `gitea.hulk.wang`），
+本仓库本机路径 `E:\Hulk-Coding\LT8619C_DLPC3421_HDMI`。
+HDMI-Tool 工作在两端：HDMI **源端**（PC 显卡侧，EDID/分辨率/图案）与**光机控制端**
+（RS485 → 板载 GD32E230 网关 → DLPC3421）。寄存器语义判读基线（0x606E 位交换 /
+0x606D 整组顺序）与光机协议规程都在上游仓库 `doc/architecture/` 与 `protocols.md`，不在本仓库。
 
 ## 2. 目录契约（重要）
 
@@ -30,8 +32,10 @@ HDMI-Tool/
 
 | 文件 | 角色 |
 |---|---|
-| `src/hdmi_gui.py` | 单文件主程序：GUI(tkinter) + 命令行，约 1500 行，纯标准库 |
-| `src/build_exe.py` | PyInstaller 打包 → `release/HDMI-Tool.exe`（onefile/noconsole，内嵌图标） |
+| `src/hdmi_gui.py` | 单文件主程序：GUI(tkinter) + 命令行 + 光机控制区, 纯标准库 + 可选依赖 |
+| `src/dlpc_rs485.py` | 光机 RS485 协议模块: 帧构造/增量解析/译码表/预设命令/串口线程(DLPC485) |
+| `src/selftest_rs485.py` | 光机协议自检(对照上游实测帧向量, 无硬件回归, 改协议代码后必跑) |
+| `src/build_exe.py` | PyInstaller 打包 → `release/HDMI-Tool.exe`（onefile/noconsole，内嵌图标+pyserial） |
 | `src/package_release.py` | exe+图案+说明 → `release/HDMI-Tool-v<ver>-win64.zip`（校验栏位引用完整性） |
 | `src/publish_gitea.py` | 建/复用 Gitea Release 并上传 zip（tag 默认取 zip 文件名） |
 | `src/hdmi_source.ps1/.bat` | 独立 PowerShell 命令行工具（自包含，与 GUI 无代码共享） |
@@ -39,33 +43,49 @@ HDMI-Tool/
 | `src/gen_solid_colors.py` | 生成 `assets/solid_*.png` ×10（800x600 纯色，需 Pillow） |
 | `src/la_wave_analyzer*.py` | 逻辑分析仪 CSV 波形判读（2/3 通道，40MHz 像素时钟假设） |
 | `src/logos/make_ico.py` | svg/png → ico（写在其自身目录） |
-| `release/pattern_slots.json` | 预置栏位：西门子星/波带片/综合测试卡，area=640x360 |
+| `release/pattern_slots.json` | 预置栏位：西门子星/波带片/综合测试卡，area=640x360；`serial` 键记忆光机串口 |
 
 ## 3. 代码不变量（改 hdmi_gui.py 必须维持）
 
-1. **纯标准库**：hdmi_gui.py 只准 import 标准库（ctypes/winreg/tkinter/…）。Pillow 是
-   *可选*加速（仅扩展自定义图片格式 PNG/GIF 之外的 JPG/BMP/WebP），缺失时必须照常工作。
-2. **BASE_DIR 语义**：frozen（PyInstaller onefile）时 `BASE_DIR=exe 所在目录`（`sys.executable`），
+1. **纯标准库 + 可选依赖**：hdmi_gui.py 核心只准用标准库（ctypes/winreg/tkinter/…）。
+   可选依赖一律走"try-import + HAS_* 标志 + 缺失降级"模式：Pillow（自定义图片 JPG/BMP/WebP）、
+   pyserial（光机控制）。缺失时对应功能禁用/提示安装，其余功能必须照常工作。
+2. **pyserial 只准在 dlpc_rs485.py 里 import**：hdmi_gui.py 通过 `dlpc_rs485.HAS_SERIAL`
+   与 `DLPC485` 类间接使用，不得直接 import serial（协议与串口细节收敛在单一模块）。
+3. **BASE_DIR 语义**：frozen（PyInstaller onefile）时 `BASE_DIR=exe 所在目录`（`sys.executable`），
    源码运行时 `=hdmi_gui.py 所在目录`（`__file__`）。所有用户数据（pattern_slots.json、
    自定义图片）都写/读自 BASE_DIR **平铺**存放，不建子目录。
-3. **自定义栏位 `file` 字段是裸文件名**：加载时 `os.path.join(BASE_DIR, file)` 解析，
+4. **自定义栏位 `file` 字段是裸文件名**：加载时 `os.path.join(BASE_DIR, file)` 解析，
    因此 pattern_slots.json 引用的图片必须与 exe 同目录 —— package_release.py 正是按此平铺打包。
-4. **exe 自包含**：图标经 `--add-data` 内嵌（运行时从 `_MEIPASS` 读）；内置五种图案
+5. **exe 自包含**：图标经 `--add-data` 内嵌（运行时从 `_MEIPASS` 读）；内置五种图案
    （红/绿/蓝/棋盘格/网格线）由程序绘制，运行时**不依赖** assets/；solid/bw PNG 只服务自定义栏位。
-5. **DPI 感知**：进程启动即 `SetProcessDpiAwareness(2)`，图案窗口按物理像素定位，勿移除。
-6. **启动强制扩展拓扑**：`SetDisplayConfig(SDC_TOPOLOGY_EXTEND|SDC_APPLY)`，静默容错
+6. **DPI 感知**：进程启动即 `SetProcessDpiAwareness(2)`，图案窗口按物理像素定位，勿移除。
+7. **启动强制扩展拓扑**：`SetDisplayConfig(SDC_TOPOLOGY_EXTEND|SDC_APPLY)`，静默容错
    （失败不阻断启动）。动机：LT8619C 热插拔后 Windows 可能停留在"仅电脑屏幕"。
-7. **分辨率切换是临时的**：走 `CHANGEDISPLAYSETTINGS`（不写注册表），"恢复"用会话开始时快照。
-8. **EDID 来源是注册表**（`HKLM\SYSTEM\CurrentControlSet\Enum\DISPLAY\...\Device Parameters\EDID`），
+8. **分辨率切换是临时的**：走 `CHANGEDISPLAYSETTINGS`（不写注册表），"恢复"用会话开始时快照。
+9. **EDID 来源是注册表**（`HKLM\SYSTEM\CurrentControlSet\Enum\DISPLAY\...\Device Parameters\EDID`），
    不是 WMI/DDC；exe 的 noconsole 版无 stdout，`--dump/--edid-fields` 只在源码/控制台版可用。
+10. **光机串口线程回调不直接碰 GUI**：DLPC485 的 on_event/on_status 在后台线程触发，
+    必须经 `queue.Queue` + `root.after(80, …)` 轮询投递回主线程（现行 `_poll_dlpc` 模式，
+    与 I2C-Inject 的 Injector 同源）；退出路径（关窗与 `--seconds` 自动关）都会走到
+    `App.destroy()`，在那里 `dlpc.close()` 收线程。
+11. **pattern_slots.json 格式**：`{'area', 'slots', 'serial'}` 三键共存；load 兼容旧版
+    纯数组（无 area）与无 serial 键两种历史格式，save 永远写全三键。
 
 ## 4. 领域语义（测试值都有含义，勿"顺手改"）
 
 - 纯色值 55/AA/FF：55(01010101) 与 AA(10101010) 互为字节镜像对（检出位序颠倒/位交换），
   FF(11111111) 全高基准；R/G/B 三行对应 RGB888 三字节组（R=D[23:16]/G=D[15:8]/B=D[7:0]）。
-- 800x600@60：demo 板 shadow EDID 首选时序（solid 系列分辨率与之一致）。
+- 800x600@60：LT8619C **demo 板** shadow EDID 首选时序（solid 系列分辨率与之一致）。
 - 640x360：测试卡区域默认值（16:9 半分辨率，点对点检查用）；full=铺满所选屏。
+  **同时是转接板光机 DLPC3421 的 nHD 面板原生分辨率**（该板 shadow EDID 只声明 640x360@60），
+  投 640x360 图案 + RS485 开光机 = 整链路 1:1 验证。
 - bw 系列图案各自目的见 `src/gen_bw_patterns.py` 顶部清单注释。
+- 光机 RS485 命令集（M730/M731/M732/M201/M202/M737/M999/M888/M7/M8/M1）语义、
+  帧格式 `D5 01 LEN <ASCII> CRC`（累加和校验）、错误码与**就绪门禁**
+  （DLPC 未就绪时 M730/M731/M732 被拒回 0xFF）以上游 `protocols.md` 为唯一权威，
+  本仓不维护协议文档副本；注意 **M7S0 是"开启"TEC 自动控温**（方向反直觉）、
+  M737 在定时投光中延迟应答（CLI 等待上限 35s）。
 
 ## 5. 构建 / 发布流水线（全部在 src/ 下执行）
 
@@ -102,8 +122,10 @@ python publish_gitea.py HDMI-Tool-v<版本>-win64.zip --replace --insecure   #
 
 ## 7. 验证清单（改完代码后）
 
-1. `python hdmi_gui.py --seconds 5` —— GUI 冒烟（自动开关）；
-2. `python hdmi_gui.py --test-pattern Checker --area 800x600 --seconds 3` —— 投图链路；
-3. `python hdmi_gui.py --dump` —— EDID 解算不抛异常；
-4. `python build_exe.py` → 双击 release/HDMI-Tool.exe 确认图标/启动/投图；
-5. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。
+1. `python selftest_rs485.py` —— 光机协议回归（改 dlpc_rs485.py 后必跑，向量来自上游 protocols.md）；
+2. `python hdmi_gui.py --seconds 5` —— GUI 冒烟（自动开关）；
+3. `python hdmi_gui.py --test-pattern Checker --area 800x600 --seconds 3` —— 投图链路；
+4. `python hdmi_gui.py --dump` —— EDID 解算不抛异常；
+5. `python hdmi_gui.py --dlpc-cmd M999`（不带 --port）—— 应明确报错而非崩溃（无硬件时的优雅降级）；
+6. `python build_exe.py` → 双击 release/HDMI-Tool.exe 确认图标/启动/投图/光机区渲染；
+7. `python package_release.py <版本>` —— 不报"引用图片缺失"即栏位完整性 OK。