wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 29 Pull Requests 1 Actions Packages Projects 2 Releases Wiki Activity
Files
d64bbdc57fbe5354690c44560449a06da6d7af5e
STM32F4-Base/simulator/README.md
T
wandering1 d64bbdc57f feat(wave): 故障录波数据面、接线与单通道回放页（软件闭环交付） 
数据面（App/algo，纯逻辑，双端编译）
- wave_ring：8 路 × 320 点列优先环（1 kHz，预触发 160 + 后触发 160），adcTask
  唯一写者；触发/冻结/封存/冷却四态，冻结持续到落盘回执才解冻，滞留 2 s 自弃
  兜底——下一次真故障无波可录比丢一段更贵
- wave_store：段头编解码 + 拉模式打包游标 + 自带无表位运算 CRC-16/MODBUS（带
  锚点自检）+ 段名与整段长度等式；格式不依赖平台类型宽度
- 段头只存原始码值与封存瞬间生效系数，工程量只当单位标签、不进任何算式
- 三套主机单测（环 113 / 编解码 170 / 触发状态机 110），全部无桩、生产源原样
  纳入；新文件补 stddef 是 ARMCC 与主机差异，主机侧照不出这条分叉
- test/host/wave_read.py 是按 §6.2 的独立第二实现（dump/fft/shape/plot），92 条
  自洽断言；三份合成段互读双校验全过、哈希钉死，格式面双向闭合
- 三套新单测不加专属钩子，由覆盖率总闸全量真跑（沿用既有裁定）

接线（任务层）
- adc_cal：新增生效系数的 32 位定点原值入口（与既有浮点入口共用生效视图），
  段头按最低有效位精确记账，不经浮点回算
- adcTask：每拍压 8 路语义原始码值并推进状态机，封存那一拍同拍交棒封存瞬间事实；
  台架定周期自抓走双层编译门，产品镜像里零存在；串口新增一条 wave: 周期行
- defaultTask：卷空闲后一次心跳整段搬完（try 锁 + 256 字节分片 + 一次完整开档到
  关档），成败都回执；失败先删半成品再计错，段号只在成功时推进；持锁超 50 ms
  补一条告警并记历史峰值（喂狗余量可核）
- Lead 复核补第四道并发陷阱：采集任务优先级高于落盘道，搬段中途它可能正好把滞留
  超时的本段自弃、甚至封出下一段——数据区校验和是对「实际读到的字节」算的，
  半新半旧的段照样自洽，故关档后复检环侧身份判废：删文件、不补账、段号不推进
- Lead 复核抓到触发挂号不是原子操作（旧实现分三个字节写，消费者可在窗口里读到
  上一段的触发源与元件号）：已把载荷压进一个字节，越界当场拒且不记任何计数；
  段文件字节布局零改动，三份合成段哈希逐字节不变
- protectTask：保护启动上升沿同点请求录波，一拍一次、元件号取最低位；判据本体
  零改动

人机（160×160 单色屏）
- 菜单树节点 26「手动录波」绑页面 + 记录查询组末新增「录波回放」叶，重跑生成器
  得 43 节点 / 34 叶 / 30 已绑，页面映射 28 → 30
- 回放页一屏一路、触发点前后各一周波共 40 点、每点 3 像素阶梯线（只用水平与
  垂直两种线段——单色屏斜线会被阈值裁掉）；零点虚线、触发光标、窗口峰值、
  单位徽标与形状受限徽标；空态与坏段各一句显式文案，绝不用半截波形冒充数据
- ui_data 新增录波注入通道（六件操作表、三态返回）；执行侧胶水带段头缓存、
  手动请求后连缓存一起作废、逐点走全仓唯一的码值换算入口
- 模拟器接真实环与编解码合成两段（含坏段与空态旗标），6 张新黄金参考，既有
  60 张逐字节零漂移未用更新模式；字库 218 → 224 字 / 319 字形
- 两份图形配置里图表组件仍为关；零堆分配；页面池水位不变
- 回放读路径的 uiTask 阻塞上界按实码写清：一次渲染 = 段表刷新 + 未缓存段头最坏
  22 次小读；已验段只剩一次开窗读 + 40 点解码；无实测数不编，实测归台架、
  仪器用已在跑的单轮工作耗时探针，不新加埋点

台账与文档
- 内存台账：录波环与落盘/回放静态逐条入册，三档对照 81,536 → 88,296 → 89,936
  字节（62.2% → 68.6%），累计 +8,400；预估 5.9 KB 与实测 +6,760 的差额点名；
  散列文件头注释同步；任务栈表核对后无需抬栈；体积趋势行与同码凭证由权威构建
  重打（0 错误 0 警告，四项体积与上一轮相同——本轮改动只有注释与声明位置）
- 设计说明：§5 补第四条并发陷阱；§6.3 定字段口径（两份独立实现的共同依据）；
  §7 回填实测；§9 周期行写实；§10 台架判据改两段式且不比绝对相位；§12 补读路径
  风险行；抬头状态改成「代码面已交付、未做完的只有板级那一轮」
- 卡片：软件闭环一栏列证据；台架三条按用户裁定保持未完成，不做虚假销项
- 口径同步：数据可信、UI 补齐、页面补齐规划、产品需求、采集短板评测、任务规划
  索引与两份 README；陈旧现状句清扫 16 处（带日期戳的历史取数行一律不动）
- 门禁说明：nested-comment 记仓库根探测必须兼容 linked worktree 的 gitdir 文件
  形态（修前该钩子在任务树里恒报环境错、静默不可用）；coding-standard 记
  「函数头注释超过 24 行就把函数功能挤出回看窗口」这条机制与本次现场
- 覆盖率基线登记两个新覆盖模块（套件 41 → 44 套）；环单测重打后该文件有效行
  227 → 226、覆盖行 226 → 225，比率仍 99.6%，是分母变小不是覆盖率回退

为什么是单一提交：文档链接、双端注册、生成器幂等（菜单与字库）、内存数字与
体积事实源、编号门禁这五道整仓门禁要求代码、页面、菜单树、字库、文档与台账
同处一个提交才自洽，按数据面/接线/人机/台账拆成四笔必然红其中至少四道

编号门禁新增行 14 处命中已按语义改写：魔数常量按字符命名、段名样例改由格式串
生成、频谱表头改 f / 2x / 5x 并加一行图例；改写后自洽断言 92 条仍全过
2026-10-29 19:23:15 +08:00

300 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LVGL PC 模拟器（simulator/）
> 在 PC 上编译运行与 MCU **同一份** UI 源码（`Drivers/BSP/UI/ui_menu.c` + `ui_font_cn_12.c`），
> 实时预览 160×160 1bpp 单色菜单界面，**无需烧录 MCU**。
>
> 部署细节与完整 FAQ 见 `docs/UI设计/LVGL模拟器部署与使用说明.md`；本文聚焦**本目录的内容与架构**。
---
## 一、目录内容
```
simulator/
├── CMakeLists.txt # 构建脚本（CMake + MSVC，x64）
├── build_sim.bat / .ps1 # 一键构建入口（自动探测 VS2019/2022/2026 生成器，x64；.bat 绕过执行策略）
├── main.c # 入口：SDL 初始化 → LVGL → 菜单 → 主循环
├── sim/ # 平台层（PC 专用实现；MCU 端对应实现在各 BSP 目录）
│ ├── sim_port.c / .h # 显示/输入端口（SDL 窗口 + 键盘 + mono 主题），替代 MCU 端 ui_port.c
│ ├── net_socket_sim.c # 网络后端：Winsock 实现 net_* BSD API，替代 MCU 端 net_socket.c（CH395F）
│ ├── ui_net_sink_backend_sim.c # RemoDispBus 平台 backend：取帧/注键（配合共享 ui_net_sink.c）
│ └── cfg_file_store_sim.c # 配置文件存储后端：本地 sim_config.ini（旧档 sim_netcfg.bin 已废弃，不读不删）
├── lv_conf.h # 模拟器专用 LVGL 配置（与 MCU 端 Lib/lv_conf.h 相互独立）
├── i1_to_png.py # 截图转 PNG：把 --screenshot 的 I1(1bpp) 原始位图转成 PNG（见 §3.5）
├── tests/ # 无头回归脚本 + 本地黄金参考（见 §3.6，流程文档 docs/UI设计/UI_自动化测试流程.md）
│ ├── check_menu_rows.py # 菜单 8 状态像素回归 + 池基线门禁
│ ├── check_content_pages.py # 文本断言 + 内容页黄金参考回归 + 往返池门禁（--update 刷参考）
│ ├── check_remo_sink.py # RemoDispBus 远端推流协议回归（起窗口模拟器 + TCP 取帧 + 参考比对）
│ ├── regen_ref_png.py # 由 ref/*.bin 批量重生成目检 PNG（--scale 6 --invert）
│ └── ref/ # 黄金参考 shot_*.bin（**入库**，判据本体）+ 目检 *.png（本地派生物，不入库）
├── dbg_log.h # 调试日志 stub：DBG_* 映射到 printf（覆盖 MCU 版头文件）
├── SDL2/
│ └── SDL2-2.32.10/ # SDL2 预编译 SDK（随仓库提供，无需安装）
│ ├── include/ # SDL2 头文件
│ │ └── SDL2/ # ★ 头文件副本（LVGL SDL 驱动写死 #include "SDL2/SDL.h"）
│ └── lib/
│ ├── x64/ # SDL2.lib / SDL2main.lib / SDL2.dll（构建使用）
│ └── x86/ # 32 位库（当前未使用）
└── build/ # CMake 生成物（可整体删除重建，勿提交）
└── Debug/lvgl_sim.exe # 可执行文件（SDL2.dll 由 POST_BUILD 自动复制到同目录）
```
### 文件职责
| 文件 | 说明 |
|------|------|
| `main.c` | 程序入口。`SDL_Init(TIMER\|EVENTS)` → `lv_init()` → `sim_port_init(160,160)` → `ui_menu_init()`（共享代码）→ 主循环（SDL 事件 + `lv_timer_handler` + `lv_refr_now`） |
| `sim/sim_port.c` | 创建 SDL 窗口显示设备（`lv_sdl_window_create`）、初始化 **mono 主题**（`lv_theme_mono_init`，1bpp 必需）、创建键盘输入设备并挂默认输入组。**不创建鼠标**（纯键盘导航，与 MCU 端 keypad 一致）。`sim_port_get_screen_mono()` 经 `SDL_RenderReadPixels` 读回屏幕像素转 1bpp，供推流取帧 |
| `sim/net_socket_sim.c` | 网络后端：Winsock 实现 `net_*` BSD Socket API（`socket`/`bind`/`listen`/`accept`/`recv`/`send`/`close`），替代 MCU 端 `Drivers/BSP/NET/net_socket.c`（CH395F） |
| `sim/ui_net_sink_backend_sim.c` | RemoDispBus 平台 backend：`ui_net_sink_get_lcdmem`→`sim_port_get_screen_mono`、`ui_net_sink_inject_key`→`lv_group_send_data`；配合**共享** `Drivers/BSP/UI/ui_net_sink.c`（协议服务端，双端同一份，TCP 7003） |
| `sim/cfg_file_store_sim.c` | 通用配置文件存储后端：本地文件 `sim_config.ini`（`fopen`/`rename` 原子写），替代 MCU 端 `App/cfg/cfg_file_store_mcu.c`（FatFS）；旧档 `sim_netcfg.bin` **已废弃**——不读、不删、不迁移（2026-10-10） |
| `lv_conf.h` | 模拟器专用 LVGL 配置。与 MCU 端 `Lib/lv_conf.h` 的关键差异见 §3.3 |
| `dbg_log.h` | MCU 版 `dbg_log.h` 依赖 `sys_clock.h`（RTC 时间戳），PC 无法编译。此 stub 把 `DBG_INFO/ERROR/DEBUG` 映射到 `printf`；因 `simulator/` 在 include 路径最前，**优先生效**覆盖 MCU 版 |
| `build_sim.bat` / `build_sim.ps1` | 一键构建入口：vswhere 探测本机 VS 大版本（16=2019 / 17=2022 / 18=2026，取已装最高）→ 映射 CMake 生成器；`build/` 缓存生成器与本机不符（换机/升级 VS）时自动删除重建（带重试，抗文件锁）。**构建入口一律走它，文档/命令中勿写死生成器版本**；`.bat` 仅负责绕过 PowerShell 执行策略并转交 `.ps1` |
| `CMakeLists.txt` | 收集 LVGL 源码（`../Lib/lvgl`）+ 共享 UI 源码（`../Drivers/BSP/UI`）+ 通用配置文件引擎（`../App/cfg_file.c`、`../Drivers/BSP/NETCFG` 的 net_cfg；`net_cfg_legacy` 已于 2026-10-10 删除）+ `sim/` 平台层，链接预编译 SDL2，产出 `lvgl_sim.exe` |
| `i1_to_png.py` | 把 `--screenshot` 产出的 I1(1bpp) 原始位图转成 PNG，便于离线比对设计稿。详见 §3.5 |
| `tests/` | 无头回归脚本（菜单 8 状态像素回归 + 内容页 66 张：文本断言 / 反向断言 / 黄金参考逐字节比对）；`ref/shot_*.bin` **随仓库入库**（判据本体，改动等于改判据，评审须逐页过目），`ref/*.png` 是本地派生的目检图（`.gitignore` 挡掉）。详见 §3.6 |
> **共享代码不复制**：`ui_menu.c` / `ui_font_cn_12.c` / `ui_net_sink.c` 直接引用 `Drivers/BSP/UI/` 下的原件，
> MCU 与 PC 两端永远同步。**不要**在本目录内复制 UI 源码。
---
## 二、架构框架
### 2.1 运行架构
```
main.c
│
├─ SDL_Init(TIMER | EVENTS) # 仅初始化计时/事件，视频由 LVGL SDL 驱动内部接管
├─ lv_init() # LVGL v9.3.0 内核
├─ sim_port_init(160, 160)
│ ├─ lv_group_create + set_default # 默认输入组
│ ├─ lv_sdl_window_create(160,160) # SDL 窗口 = 显示设备（I1 单色）
│ ├─ lv_theme_mono_init(disp, true, # mono 主题（白字黑底），1bpp 下不初始化 = 黑屏
│ │ LV_FONT_DEFAULT)
│ └─ lv_sdl_keyboard_create # 键盘 → 默认输入组（方向键/Enter/Esc）
├─ ui_menu_init() # ★ 与 MCU 共用（Drivers/BSP/UI/ui_menu.c）
│ # 基元控件页面导航，节点表驱动
└─ 主循环
├─ SDL_PollEvent # SDL_QUIT → 退出
├─ lv_timer_handler() # 驱动 LVGL 定时器/重绘
├─ lv_refr_now(NULL) # 强制整屏刷新（PARTIAL 模式下保证首帧输出）
└─ Sleep(lv_timer_handler 返回值) # 自适应休眠
```
### 2.2 渲染链路（1bpp 单色）
```
LVGL 场景（基元控件页面/label，LV_COLOR_FORMAT_I1）
→ SW 渲染器（仅启用 I1，LV_DRAW_SW_SUPPORT_I1=1）
→ SDL 窗口 blit（LV_SDL_RENDER_MODE_PARTIAL，1bpp 强制要求）
→ 屏幕（160×160 物理像素，Windows 高 DPI 可能放大显示，属正常）
```
对照 MCU 端链路（`ui_port.c`）：
```
LVGL 场景（同一份 ui_menu.c）
→ SW 渲染器（I1）
→ flush 回调 memcpy 到内存帧缓冲 g_ui_fbuf（3200 B）
→ RemoDispBus 协议（TCP 7003）按需推给远端客户端显示
```
两端**场景层完全相同**，只有"渲染结果去向"不同：模拟器进 SDL 窗口，MCU 进内存帧缓冲再走网络。
### 2.3 MCU 端 vs 模拟器 对照
| 项 | MCU（Keil MDK） | 模拟器（CMake + MSVC） |
|----|----------------|------------------------|
| LVGL 编译 | `.uvprojx` 工程添加 `Lib/lvgl` 源文件 | `Lib/lvgl/CMakeLists.txt`（最小 CMake，**仅模拟器用**，不影响 Keil 编译） |
| lv_conf.h | `Lib/lv_conf.h` | `simulator/lv_conf.h`（独立，互不影响） |
| 显示端口 | `ui_port.c`（离屏 framebuffer + flush 回调） | `sim_port.c`（SDL 窗口） |
| 输入 | 远端 keypad（`ui_port_queue_key`，网络回传键码） | SDL 键盘（`lv_sdl_keyboard_create`） |
| 主题 | 无主题（`LV_USE_THEME_* = 0`），控件用内置基础样式 | **mono 主题必须开启**（否则 1bpp 黑底黑字） |
| 日志 | `Drivers/BSP/dbg_log.h`（USART1 + RTC 时间戳） | `simulator/dbg_log.h`（printf stub） |
| 业务任务 | netTask / ftpTask / timeSyncTask 等 | 无（仅编译纯软件部分的配置文件引擎 net_cfg/cfg_file，可离线验证配置加载/保存） |
| 时钟 | `lv_tick_inc` 由 ui_task 手动喂（10ms 周期） | SDL 驱动内部 `lv_tick_set_cb(SDL_GetTicks)`，**不可再手动喂** |
| UI 数据来源 | `App/app/ui_data_feed.c` 每轮从 phasor / prot_set / 104 点表…装配并发布三帧 | `main.c` 一次性发布**固定帧**（定值不手抄数字，取链进来的 `App/algo/prot_set.c` 出厂默认）；口径 `docs/UI设计/UI_数据供给设计说明.md` §9.2 |
| 定值写路径（保存） | `ui_data_feed_tick()` 里 `ui_data_param_drain()` 落定 → 置脏 → defaultTask 写 `/prot_set.bin` | `sim_param_pump()` 用**同一份** `g_prot_set_meta` 上下限预检后落值到 RAM，**到此为止**：模拟器无 NAND，"重启值保持 / 主站 C_RD 读到同值"只能上板验（差距登记 `docs/测试说明/模拟器差距清单.md`） |
### 2.4 关键设计决策
1. **SDL2**：LVGL 官方 PC 端口同款显示方案；使用仓库内预编译 SDK（`SDL2/SDL2-2.32.10/`），无需系统安装
2. **CMake + MSVC**：`build_sim.ps1` 按本机 VS 版本自动选生成器（16=2019 / 17=2022 / 18=2026；不同机器版本不同，**勿写死**），`-A x64`；MSVC 下加 `/utf-8` 消除中文注释的 C4819 警告
3. **共享 UI 源码**：`ui_menu.c` / `ui_font_cn_12.c` 直接编译 `Drivers/BSP/UI/` 原件，改一处两端同时生效
4. **纯键盘导航**：不创建鼠标/触摸设备，与 MCU 端 keypad 操作语义一致（↑↓←→ / Enter / Esc）
5. **UI 为主**：不含 CH395F 网络 / NAND 存储 / ADC 等硬件业务；通用配置文件引擎（`cfg_file`）与 `net_cfg` 核心为纯软件，配置加载/保存可在模拟器离线验证（`sim_config.ini`；旧档 `sim_netcfg.bin` 已废弃、不参与）
---
## 三、构建与运行
### 3.1 环境要求
| 依赖 | 版本 | 说明 |
|------|------|------|
| CMake | ≥ 3.15 | 本机验证 4.3.0-rc1 |
| MSVC | VS2019 / 2022 / 2026 任一 | `build_sim.ps1` 自动探测生成器（16=2019 / 17=2022 / 18=2026，取已装最高），Hostx64/x64 |
| SDL2 | 2.32.10 | 已内置于 `SDL2/`，无需安装 |
| 操作系统 | Windows | 已验证 win32 |
### 3.2 构建命令
```powershell
# 一键构建（仓库根目录执行；自动探测本机 VS2019/2022/2026 生成器，
# build/ 缓存生成器与本机不符时自动删除重建）
& "simulator\build_sim.bat"
# 运行
.\simulator\build\Debug\lvgl_sim.exe
# 或：cmake --build simulator\build --config Debug --target run
# 全量重建
& "simulator\build_sim.bat" -Clean
```
> 改 `CMakeLists.txt` 后再跑一次 `build_sim.bat` 即可（缓存不匹配会自动重建）；遇到奇怪问题加 `-Clean` 全量重建。
> 手动 CMake 等效：`cd simulator; cmake -B build -G "Visual Studio <NN> <YYYY>" -A x64; cmake --build build --config Debug`，生成器号须与本机 VS 大版本一致（16=2019 / 17=2022 / 18=2026）。
### 3.3 `lv_conf.h` 与 MCU 端的关键差异
| 配置 | MCU 端（`Lib/lv_conf.h`） | 模拟器（本目录） | 原因 |
|------|--------------------------|------------------|------|
| `LV_USE_SDL` | 0 | **1** | SDL 显示/键盘驱动 |
| `LV_SDL_RENDER_MODE` | — | **`PARTIAL`** | 1bpp + SDL 非 PARTIAL 会 `#error` |
| `LV_SDL_INCLUDE_PATH` | — | `"SDL2/SDL.h"` | 对应 `include/SDL2/` 头文件副本 |
| `LV_USE_THEME_MONO` | 0 | **1** | 1bpp 无主题 = 黑底黑字不可见 |
| `LV_DRAW_SW_SUPPORT_I1` | 1 | 1 | 仅启用 I1 渲染，裁掉其余色深 |
| `LV_MEM_SIZE` | 16 KB | 16 KB | **必须一致**（`lv-conf-sync` 比对生效值；2026-10-15 由 40 KB 同步收缩，PC 侧不再"放宽"） |
| `LV_FONT_DEFAULT` | `&ui_font_cn_12` | 同 | 共用同一字体 |
| 其余控件/驱动 | 裁剪 | 基本一致（另开 `LV_USE_TEXTAREA/KEYBOARD/BUTTONMATRIX`） | 模拟器略宽松，便于调试 |
### 3.4 键盘操作
| 按键 | 功能 |
|------|------|
| ↑ / ↓ | 菜单项上下移动 |
| → | 进入子页 |
| Enter | 确认 / 进入子页 |
| ← / Escape | 返回上级 |
### 3.5 截图比对设计稿（离线出图）
窗口模式只适合人工目检。要把渲染结果存成 PNG 与设计参考（`docs/UI设计/mockups/` 下的原始参考图）做目视比对，用离屏截图 + 转 PNG：
```powershell
cd simulator
# 1) 离屏渲染首帧，输出 I1(1bpp) 原始位图（已剥离 8 字节调色板，纯像素数据）
.\build\Debug\lvgl_sim.exe --screenshot shot.bin
# 2) 转 PNG（默认 160x160；--scale 放大便于查看；python 统一用仓库 .venv，见 AGENTS.md「Python 环境」）
..\.venv\Scripts\python.exe i1_to_png.py shot.bin # -> shot.png
..\.venv\Scripts\python.exe i1_to_png.py shot.bin -o 预览.png --scale 6
```
**I1 位图格式**（`i1_to_png.py` 据此解析）：1 位/像素，每字节 MSB 在左（bit7 = 该行最左像素），`bit=1` 前景 / `bit=0` 背景，每行 `宽/8` 字节、行内无填充。
`i1_to_png.py` 常用参数：
| 参数 | 说明 |
|------|------|
| `-o, --output` | 输出 PNG 路径（默认与输入同名 `.png`） |
| `-W, -H` | 宽高（默认 160/160，非默认分辨率时必填） |
| `--scale N` | 最近邻放大 N 倍，便于查看小图 |
| `--invert` | 前/背景互换 |
| `--fg / --bg` | 自定义前/背景色 `R,G,B`（默认黑白） |
| `--no-auto-palette` | 关闭调色板自动识别（按纯像素解析） |
> 依赖 Pillow（已含于仓库 `.venv`，见 `requirements.txt`）。`shot.bin`/`shot*.png` 均已列入 `.gitignore`，可随时删除重生成。
### 3.6 无头回归测试（tests/）
UI 改动的自动化门禁脚本（完整流程见 `docs/UI设计/UI_自动化测试流程.md`）。除 `check_remo_sink.py`（需 Pillow，`.venv` 已含）外均为纯标准库、任意 python3 均可；为环境统一，一律用仓库 `.venv` 运行：
```powershell
# 仓库根目录执行（前置：本目录已构建出 build/Debug/lvgl_sim.exe）
.venv\Scripts\python.exe simulator/tests/check_menu_rows.py # 菜单 8 状态像素回归 + 池基线门禁
.venv\Scripts\python.exe simulator/tests/check_content_pages.py # 文本断言 + 内容页黄金参考回归 + 往返池门禁
.venv\Scripts\python.exe simulator/tests/check_remo_sink.py # RemoDispBus 远端推流协议回归（起窗口模拟器 + TCP 取帧 + 参考比对）
```
| 脚本 | 原理 | 失败输出 |
|------|------|----------|
| `check_menu_rows.py` | 键序注入（u/d/e/s）跑 8 个菜单状态，断言选中行白带、非选行黑底白字、框体边框、往返状态逐像素一致；MENU-STATE-00 池水位须等于脚本内 `MENU_POOL_BASELINE` | 未过断言清单 + 保留临时截图 |
| `check_content_pages.py` | ① 文本断言（解析字体字形，在截图 y 带内精确匹配期望串，不依赖 `ref/`）② **反向断言**（`ABSENT` 表：某串**不该**出现，如查看页/只读态不得出现「未标定」徽标与「保存」行——像素参考会被 `--update` 刷成"自证正确"，反向断言不依赖参考图）③ **60 张**无头截图与 `tests/ref/shot_*.bin` **逐字节**比对（含 2026-10-26 新增的整定 9 态：进页 / 保存行 / 只读态 / 编辑态 / 越界 / 保存 OK / 落定后可读 / 二态回绕）；另校验开页-关页往返池水位 = `POOL_AFTER_ROUNDTRIP` | 文本未命中项 / 反向断言被命中 / 差异像素数 + 双方 ink runs 对照 |
| `check_remo_sink.py` | 启动**窗口**模拟器（非无头，`CREATE_NEW_PROCESS_GROUP` 防管道阻塞），经 TCP 7003 发 LCDMEM 取 1bpp 帧；断言首帧=LCDMEM（无 INIT 污染）/位图 3200 字节/非平凡；复用 `i1_to_png` 出目检 PNG；与无头参考（`lvgl_sim --screenshot`）逐位比对 <2% 判 MATCH。守护"INIT 污染 / 快照卡死"两个历史缺陷 | 各判据失败原因 + `sim_err.txt` 尾部 + 保留 PNG（默认不删，`--clean` 才删） |
- **黄金参考与目检 PNG**（`ref/*.bin` **入库**、`ref/*.png` 本地派生不入库）：换机或想目检时——
`.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update` 出 `ref/*.bin`，
`.venv\Scripts\python.exe simulator/tests/regen_ref_png.py` 出目检 `ref/*.png`（默认 `--scale 6 --invert`）。
有意改视觉时先肉眼确认新效果正确再 `--update`（会先跑文本 + 反向断言防误刷），
并且**改完必须** `git diff --stat simulator/tests/ref` 逐页过目：出现在这份清单里的每一张
都是"判据被改了"，正常应当只有本次有意改动的那几张；`--update` 一把全刷等于把别的意外
一起签进仓库（`ref/*.bin` 是入库的，刷错就是提交了错判据）。
- **回归为什么是确定的（无头不跑 LVGL 定时器）**：`run_headless()` 只在注入键值时调
`lv_group_send_data()`，**从不调 `lv_timer_handler()`/`lv_refr_now()`**（I1 + FULL 刷新模式在
离屏渲染上会进死循环，见 §四 已知坑与 `main.c` 里 `shot_delay_cb` 的注释）。推论有两条：
① 界面侧任何**周期性 LVGL 定时器**（如定值视图为"落定/主站写值/标定完成"上屏而建的 100 ms
轮询）在回归里一次都不会触发 → 像素与它无关，只有窗口模式才用它；② 两次注键之间不发生
重绘，所以"数据就位"不能依赖"这一页画过没有"——判据连跑两次逐字节一致即为证据，设计口径见
`docs/UI设计/UI_数据供给设计说明.md` §9.2 注 6。
- **池水位常量漂移**：菜单/页面结构变更导致门禁失败时，确认新值合理后再更新脚本内常量并登记流程文档变更记录；无法解释的漂移 = 内存回归 bug。
- 退出码均为 0=PASS / 1=断言失败 / 2=环境错误（exe 缺失等）。
### 3.7 配置文件自检（--cfgtest）
配置引擎"加载 → 轮询 → 重载 → 保存"的进程内闭环验证（无需窗口 / LVGL，退出码 0=PASS / 非 0=FAIL）；自检期间在当前工作目录**临时**使用 `sim_config.ini`，**结束时无论成败一律删除**（2026-10-15 起，原因见下文 ⚠）：
```powershell
.\build\Debug\lvgl_sim.exe --cfgtest
```
验证链：`net_cfg_load`（旧档迁移已于 2026-10-10 删除，只走 INI）→ 第 1 次 poll 建基线 → 伪造"外部编辑"（原子写，等价 FTP 上传/文本编辑器）→ 2 次 poll 沉降（对应真机 4s 沉降）→ 断言 RAM 副本已更新为新值 → 对已存在文件做外科式保存、回读校验注释/值无损。
空目录运行 = 验证出厂模板生成；超限文件（>4096 B）= 判损坏并重建出厂模板；超限文档保存 = 拒绝且不动原文件。窗口模式主循环以与 MCU netTask 相同的 2s 周期调用 `cfg_file_poll()`：外部文件变更沉降后自动重载 `[network]` 段（模拟器无网络栈，变更回调为空操作，仅日志可见）。
⚠ **为什么必须删掉伪造档**：超限文档保存那条断言要求"拒写后原文件不动"（`size == 4000`），所以**连通过路径也会把这份 4000 B 纯注释档留在工作目录**。之后每一次运行都会加载它 → 外科式保存要在 4000 B 注释后补写受管段 → 输出必超 `CFG_FILE_MAX_LEN` → 引擎按设计拒写 → 网口设置页保存行显示 `ERR`，把 UI 像素回归带偏（2026-10-15 实测踩中）。故 `run_cfgtest()` 只是外壳，跑完一律删除；`simulator/tests/` 两套回归另以**空临时目录当工作目录**运行做双保险 → `docs/UI设计/UI_自动化测试流程.md` §五。
---
## 四、已知坑（构建/运行）
1. **`cannot open include file "SDL2/SDL.h"`**
LVGL SDL 驱动写死 `#include "SDL2/SDL.h"`，而原版 SDK 头文件平铺在 `include/` 下。
必须把头文件复制一份到 `include/SDL2/` 子目录（本仓库已做好）：
```powershell
$inc = "simulator\SDL2\SDL2-2.32.10\include"
New-Item -ItemType Directory -Path "$inc\SDL2" -Force
Copy-Item "$inc\*.h" "$inc\SDL2\"
```
2. **`cannot open include file "lv_conf.h"`**
`LV_CONF_DIR` / `SDL2_INCLUDE_DIR` 两个 CMake 变量必须在 `add_subdirectory(lvgl)` **之前**定义（见 `CMakeLists.txt` 中的顺序注释），勿随意调整。
3. **运行后窗口全黑**，按序排查：
- `LV_USE_THEME_MONO = 1` 且 `sim_port_init` 中调用了 `lv_theme_mono_init`
- 主循环调用了 `lv_refr_now(NULL)`（PARTIAL 模式保证首帧）
- 没有重复设置 tick（SDL 驱动内部已 `lv_tick_set_cb`，**不要**再 `SDL_AddTimer` + `lv_tick_inc`）
4. **中文显示空白**：字体 `ui_font_cn_12` 是子集字体（当前 224 汉字/符号 + ASCII，共 319 字形；2026-10-29 录波 UI 道 +6 字（放该读削域不），218/313→224/319；2026-10-28 UI 补齐批 +33 字，旧数 183/278 系未回填、改前实测 185/280），缺字渲染为空白。
补字流程见 `docs/UI设计/UI_中文字体生成与配置.md`（`tools/font_gen/` 两步脚本）。
5. **改了 UI 代码但模拟器没变化**：确认改的是 `Drivers/BSP/UI/ui_menu.c`（共享原件）而非本目录副本（本目录无副本），然后重新 `cmake --build`。
6. **编码**：UI 源码为 UTF-8（带 BOM），MSVC 已加 `/utf-8`。**不要**用 PowerShell `Set-Content` 等重写含中文的文件（编码铁律，见根目录 `AGENTS.md`）。
7. **键盘输入无响应（方向键/Enter 无效）**：`main.c` 主循环**不得**调用 `SDL_PollEvent`。
LVGL SDL 驱动内部有 5ms 定时器（`lv_sdl_window.c` 的 `sdl_event_handler`）统一轮询分发 SDL 事件；
主循环若先轮询会消费掉事件队列，键盘输入永远到不了 LVGL（现象：画面正常但按键全部无效）。
关窗退出由驱动 `LV_SDL_DIRECT_EXIT=1` 自动 `exit(0)`，主循环无需处理 SDL_QUIT。
---
## 五、边界说明
- 模拟器**跑 UI + 配置文件引擎**：不含 CH395F 网络、NAND 存储、ADC、RS-485 等硬件业务；`cfg_file` 引擎与 `net_cfg`（纯软件部分）在模拟器编译运行，可离线验证配置加载/保存
- 模拟器**含** `ui_net_sink`（Winsock 版 RemoDispBus 推流服务端，TCP 7003）——远端看图链路
可在模拟器上验证（`simulator/tests/check_remo_sink.py`）；CH395F 真实网络栈仍只在 MCU 上验证
- `build/` 为生成物，可随时删除重建（已在 `.gitignore` 中忽略）
- `Lib/lvgl/CMakeLists.txt` 仅被本模拟器引用，**不影响** Keil 的 MCU 编译
> **模拟器跑过 ≠ 真机跑过**：本目录与真机的**全部已知差异**（网络 pending 机制缺失、代次号恒 0、
> 日志/配置的 mtime 粒度与堆后端差异、IWDG/NAND/RTC 等硬件不可建模）统一登记在
> [`../docs/测试说明/模拟器差距清单.md`](../docs/测试说明/模拟器差距清单.md)——
> 改动触及 `sim/` 任何后端时，**必须同步在那里登记一行**；改动前先看 `docs/测试说明/模拟器差距清单.md` §3 判断是否必须回真机。
Reference in New Issue View Git Blame Copy Permalink