STM32F4-Base/simulator/README.md

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 状态像素回归、内容页文本断言 + 黄金参考回归）；ref/ 为本地生成物、不入库（首次 --update 生成）。详见 §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)，不可再手动喂

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 构建命令

# 一键构建（仓库根目录执行；自动探测本机 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：

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 运行：

# 仓库根目录执行（前置：本目录已构建出 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 个菜单状态，断言选中行白带、非选行黑底白字、框体边框、往返状态逐像素一致；S0 池水位须等于脚本内 MENU_POOL_BASELINE	未过断言清单 + 保留临时截图
check_content_pages.py	① 文本断言（解析字体字形，在截图内精确匹配期望串，不依赖 ref/）② 11 内容页无头截图与 tests/ref/shot_*.bin 逐字节比对；另校验开页-关页往返池水位 = 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/ 不入库）：首次/换机后先生成一次—— .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（会先跑文本断言防误刷）。
• 池水位常量漂移：菜单/页面结构变更导致门禁失败时，确认新值合理后再更新脚本内常量并登记流程文档变更记录；无法解释的漂移 = 内存回归 bug。
• 退出码均为 0=PASS / 1=断言失败 / 2=环境错误（exe 缺失等）。

3.7 配置文件自检（--cfgtest）

配置引擎"加载 → 轮询 → 重载 → 保存"的进程内闭环验证（无需窗口 / LVGL，退出码 0=PASS / 非 0=FAIL），在当前工作目录产生 sim_config.ini：

.\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] 段（模拟器无网络栈，变更回调为空操作，仅日志可见）。

---

四、已知坑（构建/运行）

1. cannot open include file "SDL2/SDL.h" LVGL SDL 驱动写死 #include "SDL2/SDL.h"，而原版 SDK 头文件平铺在 include/ 下。 必须把头文件复制一份到 include/SDL2/ 子目录（本仓库已做好）：

   $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 是子集字体（当前 122 汉字/符号 + ASCII，共 217 字形），缺字渲染为空白。 补字流程见 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—— 改动触及 sim/ 任何后端时，必须同步在那里登记一行；改动前先看 docs/测试说明/模拟器差距清单.md §3 判断是否必须回真机。