Files

T

wandering1 6b90fa0581 文档：补充主机侧单元测试（L0.5）的环境要求

新增 L0.5 主机侧单测需 MSVC（cl.exe）离线编译真实源码，此前环境
文档未覆盖该依赖。本次补齐环境侧全部引用点：

- 项目部署环境要求.md：
  · §2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元
    测试）"，明确同一套 VS 的 cl.exe 同时服务两者，MSVC 由"仅模拟器
    需要"升级为"提交门禁需要"
  · §2.7 pre-commit 表补 watchdog-unit-test 钩子 + "未装 VS 会被拦截"
  · 总览拓扑图加 MSVC 节点；第 3 步 / 第 10 步冒烟 / 搭建清单 /
    §2.10 下载表（补 VS2022/2026）/ 速查表（补 cl.exe 缺失、
    C1083 stdio.h 两条）/ 相关文档 / 变更记录同步
- 测试开发标准流程.md：
  · §4.2 补 L0.5 环境要求表（cl.exe / SDK / 纯标准库 Python / 缺失时
    退出码 2 且钩子拦截）+ "不调 vcvars64.bat（reg.exe 受限）"原因
  · §4.1 工具清单标注该运行器需 VS

2026-10-01 07:03:53 +08:00

40 KiB

Raw Blame History

项目部署环境要求

版本：v1.0　日期：2026-09-13 适用工程：STM32F4-Base（STM32F407ZGTx + CH395F 以太网 / LVGL UI / FreeRTOS）用途：新机器搭建、环境交接、现场部署时的一站式环境核对清单——开发机软件环境、目标板硬件与资源预算、网络/服务现场部署、远端客户端环境、验收步骤与常见环境问题。文中所有版本/参数/数值均取自仓库内配置或本机实测（AGENTS.md、MDK-ARM/*.bat、 simulator/README.md、docs/内存管理/、docs/子系统设计/网络配置说明.md、docs/测试说明/ 等），换机器时以仓库文件为准逐项核对。

一、环境总览

本项目涉及三类环境，部署前按 §二~§五逐一核对：

flowchart LR
    subgraph DEV["① 开发机（Windows PC）"]
        K[Keil MDK-ARM v5<br/>MCU 编译/烧录]
        X[STM32CubeMX 6.17.0<br/>外设配置/代码再生成]
        S[CMake + VS2019/2026<br/>LVGL PC 模拟器]
        P[Python .venv<br/>字体/回归脚本]
        T[Python 串口助手 serial_tool<br/>串口调试/自动测试]
        U[MSVC (VS2022 生成工具)<br/>主机侧单元测试 cl.exe]
        G[Graphviz<br/>引用关系图渲染（可选）]
    end
    subgraph TGT["② 目标板（DTU 硬件）"]
        M[STM32F407ZGTx @168MHz<br/>1MB Flash / 192KB SRAM]
        H[CH395F / GD5F2GQ5UE<br/>TPAFE5160 / RS-485 / LED×6]
    end
    subgraph RMT["③ 远端客户端（PC/浏览器）"]
        C[DTU-RemoteLCD<br/>或任意 TCP 客户端]
    end

    DEV -- "USB：下载器（ST-Link 等）" --> TGT
    DEV -- "USB 串口 USART1<br/>COMx @115200 调试日志" --> TGT
    TGT -- "以太网（CH395F）<br/>FTP:21 / 对时:8888 / 显示:7003" --> RMT

环境	角色	必需性
① 开发机	MCU 编译/烧录、UI 模拟器、脚本工具链	开发/测试必需
② 目标板	运行固件的 DTU 硬件	上机必需
③ 远端客户端	远程看图/按键、对时推送、FTP 文件操作	现场使用必需

二、开发机环境（Windows）

2.1 操作系统与基础

项	要求	说明
系统	Windows 10/11 x64	全部工具链均为 Windows 形态（Keil / VS / SDL / COM 口）；本机实测 Win11
终端	PowerShell 5.1+	构建/测试脚本均为 `.bat` / `.ps1`
版本控制	git	提交受 pre-commit 钩子门禁（§2.7）
磁盘	≥10 GB 空闲	Keil 工程 + VS 模拟器 `build/` + 工具链

2.2 MCU 构建工具链（必需）

项	要求	说明
Keil MDK-ARM	v5.x（须含 ARMCC v5 编译器）	工程锁定 `uAC6=0`（仅 ARMCC v5，不支持 armclang）；仅支持此工具链，无其他工具链
安装路径	`C:\Keil_v5\`	`MDK-ARM/build.bat`、`download.bat` 硬编码 `C:\Keil_v5\UV4\UV4.exe`；换机器须装到同路径，或修改两个 bat 的 `UV4=` 行
设备支持	STM32F407ZGTx + CMSIS Flash 算法	工程引用 `STM32F4xx_1024.FLM`（1MB 片内 Flash，0x08000000），由 CMSIS STM32F4 设备包提供
STM32CubeMX	6.17.0（工程 `STM32F407-Demo.ioc` 记录的版本）	修改外设/引脚/时钟配置并再生成 CubeMX 文件；固件包须 STM32Cube FW_F4 V1.28.3
命令行构建	`& "MDK-ARM\build.bat"`（即 `@build`）	退出码 0 = 0 错 0 警；失败看 `MDK-ARM/build_log.txt`
命令行烧录	`& "MDK-ARM\download.bat"`（即 `@download`）	flash + Reset & Run；日志出现 `Application running` 判成功

⚠ 版本一致性关键：.ioc 记录 MxCube.Version=6.17.0 + FirmwarePackage=STM32Cube FW_F4 V1.28.3，再生成代码必须用此组合——用更新版本的 CubeMX 会把仓库内 HAL 驱动升级、产生大量无关 diff（见 §六速查）。自定义代码只写 USER CODE BEGIN/END 区域内（再生成时保留，KeepUserCode=true），勿手改生成文件的非 USER CODE 区域。

Keil 初始化配置（机器侧项，非项目自带）：

项	配置方法	说明
License	首次启动 UV4 自动生成 90 天评估 license；长期使用需购买正式 license	license 绑定机器、不在仓库；`Options for Target → License` 查看/输入
Device Pack	Pack Installer 安装 `Keil::CMSIS`、`Keil::STM32F4xx_DFP`（pack 源 https://www.keil.com/pack/ ）	工程引用的 Flash 算法 `STM32F4xx_1024.FLM` 就来自此 pack（.uvoptx 的 `$$Device:STM32F407ZGTx$` 变量解析到 pack 目录 `C:\Keil_v5\PACK\Keil\STM32F4xx_DFP\<ver>\CMSIS\Flash\`）；pack 缺失则下载失败
下载器驱动	工程已配 UL2CM3 调试驱动 + Flash 算法参数（.uvoptx 自带，调试时钟 10 MHz）	物理下载器（ST-Link 等）需装 USB 驱动（见第 8 步）；现场换其他下载器在 Keil `Options for Target → Debug → Settings` 切换

项目自带、新机器无需重配（随仓库同步）：编译器与目标选项（.uvprojx：ARMCC v5 / 设备 STM32F407ZGTx / Cortex-M4+FPU）、调试与下载参数（.uvoptx）、Run-Time Environment（MDK-ARM/RTE/）、启动文件 startup_stm32f407xx.s、构建/下载 bat、 RAM/Flash 链接布局（见下）。

RAM / Flash 链接布局（项目自带，自动同步，新机器无需在 Keil 里重设）：

链接器使用手动 scatter 文件 MDK-ARM/STM32F407-Demo/STM32F407-Demo.sct（在仓库，.uvprojx 已启用 useFile=1）：
- ER_IROM1 0x08000000，1 MB（代码 + 只读数据）
- RW_IRAM1 0x20000000，128 KB（SRAM1 112K + SRAM2 16K 连续；SRAM3/CCM 故意未映射——克隆芯片可能无 SRAM3）
Keil Options for Target → Target 页显示的片上内存来自 .uvprojx 的 <Cpu> 行（IRAM 112 KB / IRAM2 16 KB / IROM 1 MB，同样在仓库）+ Device Pack
⚠ 新机器不要在 GUI 里重填 RAM 区，也勿改 Target 页（会回写共享的 .uvprojx 影响他人）；确需调整内存布局（如日后启用 SRAM3/CCM）时修改 .sct 并提交

2.3 PC 侧编译环境（模拟器 + 主机侧单元测试，必需）

⚠ 本节涵盖两类都要 MSVC 的 PC 侧构建：① LVGL 模拟器（C++，产物 lvgl_sim.exe）； ② 主机侧单元测试（C，批量离线编译真实生产源码，见 §2.10 与 docs/测试说明/看门狗单元测试说明.md）。两者共用同一套 VS 安装，无需装两次。

项	要求	说明
CMake	≥ 3.15	本机实测 4.3.0-rc1；仅模拟器需要，单元测试不用 CMake
编译器	VS2019 / 2022 / 2026 任一（C++ x64 工作负载）	`build_sim.ps1` 按本机 VS 大版本自动选生成器（16=2019 / 17=2022 / 18=2026）、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警
MSVC C 工具链	同上（`cl.exe`）	主机侧单元测试的必需项：`test/host/<模块>/run_unit_test.py` 用 `cl.exe` 离线编译真实源码。只要装了 VS 就有（`VC\Tools\MSVC\<ver>\bin\Hostx64\x64\cl.exe`），不额外装东西
Windows SDK	10.0.19041 及以上	CMake 配置与 `cl.exe` 编译（`stdio.h` 等）都从这里取；随 VS 工作负载勾选安装
SDL2	2.32.10（预编译，无需系统安装）	不在仓库（`simulator/SDL2/` 目录 gitignore，fresh clone/换机须本地下载一次）；缺失时的下载/解压/校验步骤见第 3 步。仅模拟器需要
产物	`simulator/build/Debug/lvgl_sim.exe`	`build/` 为生成物（gitignore），可整体删除重建

& "simulator\build_sim.bat"                          # 一键构建（自动探测 VS 版本；首次自动配置，改 CMakeLists.txt 后需重跑）
.\simulator\build\Debug\lvgl_sim.exe                 # 运行（纯键盘导航 ↑↓←→ / Enter / Esc）

# 主机侧单元测试（示例：看门狗判定状态机；纯逻辑、零硬件、秒级）
& '.venv\Scripts\python.exe' test/host/watchdog/run_unit_test.py   # 退出码 0=PASS / 1=FAIL / 2=环境错误

模拟器与 MCU 共用 UI 源码（Drivers/BSP/UI/），无硬件业务（网络推流除外，Winsock 版）。详见 simulator/README.md、docs/UI设计/LVGL模拟器部署与使用说明.md。

2.4 Python 环境（脚本工具链）

项	要求	说明
统一入口	仓库 `.venv\Scripts\python.exe`	一切依赖第三方库的脚本（字体生成、截图转 PNG、RemoDispBus 回归）都用它
解释器版本	Python ≥ 3.10（任意发行版）	种子解释器仅用于建 venv 一次；本机为 3.12.4
依赖	`fonttools==4.51.0`、`pillow==10.3.0`、`pyserial==3.5`	清单 = 仓库根 `requirements.txt`（必须保持纯 ASCII：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError）
入库情况	`.venv/` 已 gitignore	换机/首次必须重建

# 重建（<种子python> 换成本机任一 python ≥3.10）
& <种子python> -m venv .venv
& '.venv\Scripts\python.exe' -m pip install -r requirements.txt

⚠ PATH 里默认 python 可能是 msys64 的（无第三方库）——禁止用它跑字体生成 / Pillow 脚本；纯标准库脚本（UI 回归测试、extract_cn.py）任意 python3 均可。

2.5 中文字体生成依赖

项	要求	说明
Node.js + npm	任意近期版本	一次性：`npm i -g lv_font_conv`（字体位图转换）
fontTools	仓库 `.venv`（§2.4）	`make_font.py` 依赖

python tools/font_gen/extract_cn.py                        # 任意 python3：扫 UI 源码 → ui_cn_chars.txt
& '.venv\Scripts\python.exe' tools/font_gen/make_font.py   # 宋体 12px 1bpp + 字符集 → ui_font_cn_12.c

任何 UI 文案新增汉字后必须走此流程（缺字 = 屏幕空白块），详见 docs/UI设计/UI_中文字体生成与配置.md。

2.6 串口调试 / 自动化测试工具

项	要求	说明
Python 串口助手	`tools/serial_tool/serial_tool.py`（仓库内置，.venv + pyserial）	常驻 daemon + 薄 CLI + 全量日志文件；无需单独安装，`pip install -r requirements.txt` 即就绪
调试串口	USART1（PA9 TX / PA10 RX），115200 8N1	端口单一配置源 `.opencode/serial_config.json`（本机 COM6）；换端口只改这个文件
一键测试	`test\run_boot_test.py`（即 `@test`，`& '.venv\Scripts\python.exe' test/host/run_boot_test.py`）	开串口 + 清日志 → 烧录 → wait-idle（静默 8s/超时 30s）→ 提取 → 标记校验；默认端口取 `serial_config.json` / 115200，退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法错误

采集 = 端口常开 + daemon 全量日志（tools/serial_tool/state/serial.log），无采集窗口/first-byte/EOF 重试仪式。命令契约与陷阱见 docs/测试说明/串口助手设计说明.md、docs/测试说明/自动化测试流程.md。

2.7 代码审查钩子（pre-commit）

项	要求	说明
pre-commit	已安装并 `pre-commit install`	提交门禁（pre-commit + commit-msg 两类钩子）
cppcheck	在 PATH 中	本地钩子直接调 `cppcheck --enable=warning,performance,portability,style`（`language: system`）
python	在 PATH 中	本地钩子调 `scripts/check_mojibake.py`（U+FFFD 乱码）、`scripts/check_coding_standard.py`（规范 V1.0，纯标准库）
MSVC `cl.exe`	装了 VS 即有（§2.3）	`watchdog-unit-test` 钩子必需：改 `App/util/task_watchdog.` 或 `test/host/watchdog/` 时触发，用 `cl.exe` 离线编译真实源码跑单测。未装 VS 时该钩子报环境错误（退出码 2）→ 拦截提交*
gitlint	随 pre-commit 自动拉取	commit message 格式（宽松规则，兼容中文标题）

检查范围仅项目自有代码；Lib/、Middlewares/、Drivers/BSP/UI、lftpd、dhara、test/ 等被排除。全库扫描：pre-commit run --all-files。详见 docs/代码规范/pre-commit使用说明.md、docs/代码规范/cppcheck使用说明.md。

⚠ 新增 L0.5 单测钩子（2026-10-01）后，"装了 VS"从"仅模拟器需要"升级为"提交门禁需要"：只要装了 VS（§2.3）就自动具备，无需额外安装；但完全未装 VS 的机器在改动看门狗相关文件时会被钩子拦截。

2.8 引用关系图渲染（Graphviz，可选）

项	要求	说明
Graphviz	`winget install Graphviz.Graphviz`（本机实测 16.1.0）	`tools/refgraph` 引用关系图生成器的渲染引擎；`dot` 在 `C:\Program Files\Graphviz\bin\`，工具自动定位，无需配置 PATH
必需性	可选	未装时工具自动跳过渲染（仍产出 `.dot`/`.json`，装好后重跑即出图）；不影响编译/测试/审查门禁
产物	`docs/images/引用关系图.*`	文件级 + 模块级 `.svg`/`.dot`/`.json`（随工具提交入库）；PNG 仅本地预览（`docs/images/*.png` 已 gitignore）

winget install Graphviz.Graphviz
& 'tools\refgraph\gen_refgraph.bat'    # → docs/images/引用关系图.*（.dot/.svg/.png/.json）+ 生成报告

图例、语义（文本层引用/未解析归外部）、更新流程与已知限制见 docs/架构设计/引用关系图说明.md。 Keil 工程包含路径解析自 MDK-ARM/*.uvprojx（自动跟随）；模拟器包含路径变化需同步脚本 SIM_INCLUDE_DIRS。

2.9 开发机一次性搭建（分步安装命令）

以下命令在 PowerShell 中直接执行（新机器从零搭建，全程约 1~2 小时），逐步对照文末清单打勾。

第 1 步：git

winget install Git.Git

手动下载：https://git-scm.com/download/win （Git for Windows）

第 2 步：Keil MDK-ARM v5 + STM32CubeMX（GUI 安装，无命令行方式）

下载页：https://www.keil.com/arm/mdk.htm（MDK-ARM v5.x；90 天评估 license 可先开发；必须含 ARMCC v5 编译器——工程锁 uAC6=0，armclang 不行）
安装目录设为 C:\Keil_v5（build.bat / download.bat 的 UV4= 行硬编码该路径；装别处就改这两个 bat）
装完打开 Pack Installer → 安装 Keil::CMSIS 和 Keil::STM32F4xx_DFP（提供 STM32F407ZGTx 设备 + STM32F4xx_1024.FLM Flash 算法；pack 源 https://www.keil.com/pack/ ，Pack Installer 自动拉取）——必装，否则烧录失败（FLM 从 pack 目录解析，不在仓库）
License：首次启动 UV4 自动生成 90 天评估 license（长期使用需购买正式 license；license 绑定机器、不在仓库）
STM32CubeMX 6.17.0：下载页 https://www.st.com/en/tools/stm32cubemx.html （直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe ）
- 用途：打开仓库 STM32F407-Demo.ioc → 改外设/引脚/时钟 → 生成代码（仅重写 CubeMX 区域，USER CODE 区域保留）
- 固件包须 STM32Cube FW_F4 V1.28.3（与仓库 HAL 驱动一致；若未随附，在 CubeMX 帮助 → 管理 下载对应包）
- ⚠ 更新版本的 CubeMX 会升级 HAL 驱动、产生大量无关 diff，勿随意用最新版

第 3 步：VS（2019/2022/2026 任一）+ CMake（模拟器工具链 + 主机侧单元测试编译器 MSVC）

winget install Kitware.CMake        # ≥3.15（仅模拟器用；单元测试不用 CMake）

VS 版本不固定：构建入口 simulator\build_sim.bat 自动探测本机 VS 大版本选生成器（16=2019 / 17=2022 / 18=2026），装任一即可
这一个 VS 同时提供两样东西：① 模拟器的 C++ 工具链 + CMake 生成器；② 主机侧单元测试的 cl.exe（§2.3 / §2.10）——装一次即可，不需要为单测另装编译器
新装选 VS2019 的注意：Community 已下架主站，从存档页下载：https://visualstudio.microsoft.com/zh-hans/vs/archives/（直链：https://aka.ms/vs/16/release/vs_community.exe）；装 VS2022/VS2026 走主站下载
- 工作负载勾选 “使用 C++ 的桌面开发”；单个组件勾对应 Windows 10/11 SDK（cl.exe 编 stdio.h 等标准头也依赖此处安装的 SDK）

SDL2 无需系统安装（用预编译 SDK），但不在仓库——simulator/SDL2/ 被 gitignore，git clone 后本地没有；目录不存在时按下面步骤补一次

补 SDL2 SDK（仅当 simulator/SDL2/ 缺失）

# 1) 下载官方 2.32.10 VC 预编译包（GitHub Releases，约 7 MB）
New-Item -ItemType Directory -Force simulator\SDL2 | Out-Null
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri "https://github.com/libsdl-org/SDL/releases/download/release-2.32.10/SDL2-devel-2.32.10-VC.zip" `
    -OutFile simulator\SDL2\SDL2-devel-2.32.10-VC.zip -UseBasicParsing

# 2) 解压到 simulator/SDL2/；顶层目录名须为 SDL2-2.32.10
#    （若解压出 SDL2-devel-2.32.10/，改名为 SDL2-2.32.10/）
Expand-Archive simulator\SDL2\SDL2-devel-2.32.10-VC.zip -DestinationPath simulator\SDL2 -Force

# 3) 头文件复制到 include/SDL2/ 子目录（必做：LVGL SDL 驱动写死 #include "SDL2/SDL.h"）
$inc = "simulator\SDL2\SDL2-2.32.10\include"
New-Item -ItemType Directory -Path "$inc\SDL2" -Force | Out-Null
Copy-Item "$inc\*.h" "$inc\SDL2\"

# 4) 校验 5 个必备文件（全 True = 就绪），然后删 zip
foreach ($f in @("include\SDL.h", "include\SDL2\SDL.h", "lib\x64\SDL2.lib",
                 "lib\x64\SDL2main.lib", "lib\x64\SDL2.dll")) {
    "{0} : {1}" -f $f, (Test-Path "simulator\SDL2\SDL2-2.32.10\$f")
}
Remove-Item simulator\SDL2\SDL2-devel-2.32.10-VC.zip

目标目录结构：

simulator/SDL2/SDL2-2.32.10/
├── include/            ← SDL.h 及各头文件
│   └── SDL2/           ← 头文件副本（第 3 步；缺它编译报 C1083: cannot open include file "SDL2/SDL.h"）
└── lib/x64/            ← SDL2.lib / SDL2main.lib / SDL2.dll（构建与运行均从此取）

内网机器连不上 GitHub：在任一台有网的机器下载 zip（release 页：https://github.com/libsdl-org/SDL/releases/tag/release-2.32.10）拷过去，再走上面第 2~4 步。

第 4 步：Python（.venv 脚本工具链）

winget install Python.Python.3.12   # 或任一 ≥3.10；手动：https://www.python.org/downloads/windows/
# 仓库根目录建 venv（种子解释器用刚装的 python 即可）
python -m venv .venv
& '.venv\Scripts\python.exe' -m pip install -r requirements.txt

python 不可用时改用完整路径 & "$env:LOCALAPPDATA\Programs\Python\Python312\python.exe" -m venv .venv。 requirements.txt 必须保持纯 ASCII；之后一切依赖第三方库的脚本只用 .venv\Scripts\python.exe。

第 5 步：Node.js + 字体工具

winget install OpenJS.NodeJS.LTS     # 手动：https://nodejs.org/ （选 LTS）
npm i -g lv_font_conv                # 手动：https://www.npmjs.com/package/lv_font_conv

第 6 步：pre-commit + cppcheck（提交门禁）

winget install astral-sh.uv
uv tool install pre-commit
winget install cppcheck             # 2.21.0 → C:\Program Files\Cppcheck
# ★ 重开终端（PATH 才生效），然后：
pre-commit install
pre-commit run --all-files          # 首次全库基线扫描

手动下载：uv → https://astral.sh/uv/ （一行安装 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"）· pre-commit → https://pre-commit.com/ · cppcheck 2.21.0 → https://github.com/CppQA/cppcheck/releases （2.21.0 tag 的 Windows x64 zip，解压至 C:\Program Files\Cppcheck 并加入 PATH）

第 7 步：Python 串口助手（串口调试 / 自动测试，仓库内置）

无需单独安装：tools/serial_tool/ 随仓库提供，依赖 pyserial（已入 requirements.txt，第 4 步建 .venv 时一并安装）。建成后验证：

& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py selftest   # → SELFTEST PASS
& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py ports      # 枚举 COM 口

第 8 步：下载器驱动（ST-Link）

ST 官网下载 STM32CubeProgrammer 运行一次（自动安装 ST-Link USB 驱动）：https://www.st.com/en/development-tools/stm32cubeprog.html
仅需要 ST-Link V2 驱动时：https://www.st.com/en/development-tools/stm321025.html （ST-LinkV2-USB-Driver 包）
Keil Options for Target → Debug 确认驱动与实物一致（工程已配 UL2CM3 框架）

第 9 步：串口配置

& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py ports   # 查 COM 号

把查到的端口写入 .opencode\serial_config.json 的 portName（唯一配置源，换口只改这里）。

第 10 步：冒烟验证（全过 = 环境就绪）

& "MDK-ARM\build.bat"                                            # → BUILD_OK: 0 errors, 0 warnings
& "simulator\build_sim.bat"                                      # 模拟器一键构建（自动探测 VS 版本），0 警告
.\simulator\build\Debug\lvgl_sim.exe                             # 出 160×160 单色菜单画面
& '.venv\Scripts\python.exe' simulator\tests\check_menu_rows.py           # PASS
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py --update  # 首次生成参考图
& '.venv\Scripts\python.exe' simulator\tests\check_content_pages.py       # 再跑 → PASS
& '.venv\Scripts\python.exe' tools\serial_tool\serial_tool.py selftest     # → SELFTEST PASS
& '.venv\Scripts\python.exe' test\host\watchdog\run_unit_test.py            # 主机侧单测 → 39/39 PASSED（退出码 0）
pre-commit run --all-files

搭建清单汇总（随步骤逐项打勾）：

Windows 10/11 x64 + PowerShell 5.1+
Keil MDK-ARM v5.x 装到 C:\Keil_v5\（或已同步修改两个 bat）+ CMSIS / STM32F4 DFP 包
STM32CubeMX 6.17.0 已装（与 .ioc 版本一致；含/可装 STM32Cube FW_F4 V1.28.3 固件包）
VS2019 / 2022 / 2026 任一（C++ x64 工作负载）+ Windows 10/11 SDK + CMake ≥3.15（模拟器构建脚本自动适配 VS 版本；同一 VS 提供主机侧单测所需的 cl.exe，见 §2.3 / §2.10）
git clone 仓库 → pre-commit install；cppcheck 入 PATH
建 .venv 并 pip install -r requirements.txt
npm i -g lv_font_conv
写好 .opencode/serial_config.json（本机 COM 口），serial_tool selftest PASS
下载器（ST-Link 等）USB 驱动已装，Keil Options for Target → Debug 驱动一致
第 10 步冒烟验证全部通过（含 test/host/watchdog/run_unit_test.py → PASSED）
（可选）Graphviz 已装（引用关系图渲染：winget install Graphviz.Graphviz，见 §2.8）

2.10 手动下载来源速查

§2.9 中需下载组件的官方下载地址汇总（正文的 winget / 命令行方式优先；网络受限时按本表手动下载）：

组件	官方下载页	版本 / 说明
Git for Windows	https://git-scm.com/download/win	最新稳定版
Keil MDK-ARM	https://www.keil.com/arm/mdk.htm	v5.x，须含 ARMCC v5；安装目录 `C:\Keil_v5`
CMSIS / STM32F4xx DFP	https://www.keil.com/pack/	在 Keil Pack Installer 内装 `Keil::CMSIS`、`Keil::STM32F4xx_DFP`
STM32CubeMX	https://www.st.com/en/tools/stm32cubemx.html	6.17.0（与 .ioc 一致）；直链 https://www.st.com/resource/en/software_stm32cubemx/stm32cubemx_setup.exe
STM32Cube FW_F4（固件包）	https://www.st.com/en/embedded-software/stm32cube-f4.html	V1.28.3（与仓库 HAL 驱动一致）
Visual Studio 2019	https://visualstudio.microsoft.com/zh-hans/vs/archives/	直链：https://aka.ms/vs/16/release/vs_community.exe
Visual Studio 2022 / 2026	https://visualstudio.microsoft.com/zh-hans/downloads/	任一版本均可（模拟器构建 + 主机侧单测 `cl.exe`，二者共用）
CMake	https://cmake.org/download/	≥ 3.15
Python	https://www.python.org/downloads/windows/	≥ 3.10，推荐 3.12
Node.js	https://nodejs.org/	LTS
lv_font_conv	https://www.npmjs.com/package/lv_font_conv	一般 `npm i -g lv_font_conv`
uv	https://astral.sh/uv/	`powershell -c "irm https://astral.sh/uv/install.ps1 \| iex"`
pre-commit	https://pre-commit.com/	一般 `uv tool install pre-commit`
cppcheck	https://github.com/CppQA/cppcheck/releases	2.21.0 的 Windows x64 zip（`cppcheck-2.21.0-windows-x64.zip` 形式），解压入 PATH
STM32CubeProgrammer	https://www.st.com/en/development-tools/stm32cubeprog.html	含 ST-Link USB 驱动
ST-Link V2 驱动	https://www.st.com/en/development-tools/stm321025.html	`ST-LinkV2-USB-Driver` 包
SDL2（仅仓库预编译库缺失时）	https://github.com/libsdl-org/SDL/releases	2.32.10，一般不需要
Graphviz	https://graphviz.org/download/	一般 `winget install Graphviz.Graphviz`；未装时引用关系图工具跳过渲染（§2.8），不阻塞其他工具链

获取渠道优先级：① winget（自动校验、免手动）→ ② 上表官方页 → ③ 网络受限时自行选可信镜像； Keil / ST 官网访问受限时可走代理。

三、目标板环境（DTU 硬件）

3.1 主芯片

项	值	说明
MCU	STM32F407ZGTx	Cortex-M4（双精度 FPU / TrustZone），LQFP144
主频	168 MHz	HSE 8 MHz → PLL M=4 / N=168 / P=2（`Inc/stm32f4xx_hal_conf.h`）
Flash	1 MB（0x08000000）	片内
SRAM	192 KB（128 KB 主 + 64 KB CCM）	当前仅用主 SRAM 128 KB；SRAM3/CCM 未映射（§3.3）
RTOS	FreeRTOS V10.3.1（CMSIS-RTOS V2）	HAL 时基 TIM7，tick = 1 ms；NVIC 4 位抢占，外设中断优先级 ≥5

3.2 外设硬件要求（引脚级）

外设	接口	引脚	备注
CH395F 以太网	SPI2	PB12 CS / PB13 SCK / PB14 SDO / PB15 SDI	PHY 强制 100M 全双工；SPI 分频系数必须为 8（PCB 设计约束，速度受限）
GD5F2GQ5UE NAND（2 Gbit）	SPI1	PE0 CS / PB3 SCK / PB4 MISO / PB5 MOSI / PB8 WP / PE1 HOLD	FatFS（FAT32）+ dhara FTL；上电无卷自动 `f_mkfs`
TPAFE5160 ADC	并行 16 位	PG0~PG15 数据 / PD3 RD / PD4 CONVST / PD7 BUSY	`APP_ADC_ENABLE` 开关
USART1（调试串口）	UART	PA9 TX / PA10 RX	115200 8N1；printf 日志 + `@test` 采集通道
UART5（RS-485）	UART	PC12 TX / PD2 RX / PD0 DE	半双工；`APP_RS485_ENABLE` 开关
状态 LED ×6	GPIO	PC4 / PC5 / PB1 / PB2 / PF11 / PF12	低电平点亮

3.3 资源预算（部署红线）

实测（2026-09-11 快照口径，现汇总于 docs/内存管理/RAM使用分析与优化方案.md）：

资源	已用	总量	利用率	余量	红线说明
Flash	232,000 B（226.6 KB）	1 MB	22.1%	~798 KB	充裕
主 SRAM（静态区+堆）	125,104 B（122.2 KB）	128 KB	95.4%	5.8 KB	极度紧张：新增任何静态缓冲/任务栈前必须先核算 RAM 余量

LVGL 内存池 40 KB（静态占用）；FreeRTOS 堆 48 KB
任务栈预算（words，1 word = 4 B）：

任务	栈大小	优先级
defaultTask	2048	Normal
netTask	4096	Normal
ftpTask	4096	Normal
testTask	4096	BelowNormal
uiTask	16384	BelowNormal
timeSyncTask	2048	Normal

挖潜方向（未实施）：SRAM3 64 KB / CCM 64 KB 未映射——详见 docs/内存管理/。部署侧含义：不要做任何需要额外 RAM 的固件定制，新增功能先过内存预算。

3.4 下载与调试

项	说明
下载方式	`& "MDK-ARM\download.bat"`（Keil 命令行：烧写 + Reset & Run）
下载器	工程已配 `UL2CM3` 调试驱动 + `STM32F4xx_1024` Flash 算法；物理下载器按现场选择（本机为 ST-Link——不占 COM 口，可与串口调试并存）；新机器在 Keil `Options for Target → Debug → Settings` 选择与硬件一致的驱动
调试日志	USART1 115200；抓开机日志必须先武装采集再复位（`test/host/run_boot_test.py --flash-cmd` 已保证顺序）

3.5 功能配置开关

开关	位置	当前值	说明
`APP_NET_ENABLE`	`App/app/app_cfg.h`	开	网络（CH395F + 全部 TCP 服务）
`APP_ADC_ENABLE`	同上	开	TPAFE5160 采样
`APP_RS485_ENABLE`	同上	开	RS-485 通信
`TEST_SUITE_*`	`test/board/test_config.h`	全注释（产品构建）	测试套件互斥：一次构建只开一个（CH395F / 存储 / GD5F / RTC）；全注释 = 正常产品固件

四、网络与现场部署

4.1 网络参数

参数	工厂默认	修改方式
IP	192.168.1.100（静态，无 DHCP）	屏幕 `通讯参数 → 网口设置`（修改密码 `123`）保存后立即生效（网络重建约 1~3 s）；或预置 `/config.ini`（INI；旧版 `/cfg/netcfg.bin` 首启自动迁移）
子网掩码	255.255.255.0（/24）	同上
默认网关	192.168.1.1	同上
MAC	全零 = 芯片内置 MAC	同上（全零是"使用芯片内置 MAC"的哨兵，不是"MAC 为 0"）
PHY	强制 100M 全双工	固件固定，不可配

配置持久化：NAND 上通用配置文件 /config.ini（INI [network] 段；缺失/损坏回退工厂默认并重建模板，不带崩网络）
立即生效机制：保存 → netTask 重建网络 → 代次号递增 → 三个 TCP 服务自动重建监听（既有连接会断开，属预期）

4.2 服务端口（现场连通性核对）

服务	协议/端口	用途	核对方法
远程显示（RemoDispBus）	TCP 7003	远端看图（160×160 1bpp，3200 B/帧，客户端 LCDMEM 拉取）+ 远端导航按键	DTU-RemoteLCD 或任意 TCP 客户端连 7003 收帧
墙钟对时	TCP 8888	PC 主动推送时间到设备	对时推送后核对设备时间 / 日志时间戳
FTP	TCP 21	文件上传/下载（根目录 `/`，NAND 存储）	任意 FTP 客户端列目录/读写

现场组网要求：设备与客户端同网段（默认 .100/24、网关 .1）；跨网段部署先按 §4.1 改 IP 再上线。

4.3 存储与运行时

文件系统：FatFS（FAT32）挂 NAND；上电无卷自动格式化（f_mkfs）；格式化会清除卷上全部文件（含网口配置 /config.ini）
RTC：SD2506 芯片（驱动 Drivers/BSP/SD2506/）提供墙钟基准与日志时间戳；首次使用建议先经 8888 对时
启动时序：app_main_init（存储 → 时钟 → RS485 → NAND → ADC → 启动转换）→ 就绪屏障（STORAGE / NET / FTP / TIMESYNC 事件）→ 六任务运行；详见 docs/架构设计/项目启动顺序管理.md、docs/架构设计/项目架构总览.md

4.4 现场验收清单

#	项目	方法	通过标准
1	上电自启动	断电上电 + 串口采集	`@test` PASS：Required `App init OK;Network Init;net init: OK;PHY: 100M FULL`，无 `FAIL/ERROR/HardFault`
2	网络连通	PC ping 192.168.1.100	通（PHY 100M FULL）
3	远程显示	DTU-RemoteLCD 连 7003	出图（160×160 1bpp）+ 远端菜单导航可用
4	FTP	FTP 客户端连 :21	列目录 / 读写 `/` 下文件
5	UI 功能	屏幕 / 远端操作	菜单 7 项导航、内容页、密码（查看 `000` / 修改 `123`）、网口设置保存后立即生效
6	对时	PC 推送 8888	设备墙钟更新、日志时间戳正确
7	掉电保持	写文件 / 改网口配置 → 重启	数据仍在（`/config.ini` 按新值生效）
8	LED 状态	目检	6 路 LED 随系统状态变化（低电平点亮）

五、远端客户端环境

项	要求	说明
操作系统	任意（Windows / Linux / macOS，有浏览器或 Python 即可）	与设备同网段
远程显示客户端	DTU-RemoteLCD（独立项目：Flask + WebSocket 参考实现）或任意符合 RemoDispBus 协议的 TCP 客户端	连设备 TCP 7003；协议见 `docs/UI设计/RemoDispBus协议与接收设计说明.md`
对时工具	任意可 TCP 推送的工具/脚本	向设备 8888 推送
FTP 客户端	任意（资源管理器 / FileZilla 等）	设备端 lftpd，端口 21
浏览器	Chrome / Edge	查看参考客户端 Web 页；开发期浏览文档 SVG 图

客户端侧无强制版本依赖——协议是纯 TCP 字节流（[TAG][CMD][LEN][DATA][CRC] 帧），任何语言均可实现；单连接模型（同一时刻一个客户端）。

六、常见环境问题速查

现象	原因	处理
`build.bat` 找不到 UV4 / 闪退	Keil 未装在 `C:\Keil_v5\`	装到该路径，或改 `build.bat` / `download.bat` 的 `UV4=` 行
Keil 编译报编译器不识别	新装 MDK 只有 armclang	工程锁 `uAC6=0`，必须用带 ARMCC v5 的 MDK v5.x
CubeMX 再生成后出现大量 diff / 新告警	用了比工程记录更新的 CubeMX / 固件包版本	用 git 还原生成文件，按 .ioc 记录的 CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3 重新生成
CMake 配置失败：找不到生成器	本机 VS 大版本与生成器不匹配	统一走 `simulator\build_sim.bat`（自动探测 VS 版本选生成器）；手动 cmake 时 `-G` 号须与本机 VS 一致（16=2019 / 17=2022 / 18=2026）
模拟器构建报 `SDL2/SDL.h` 找不到	`simulator/SDL2/` SDK 缺失（不入库）或头文件副本没做	按第 3 步"补 SDL2 SDK"完整走一遍（下载 → 解压 → 头文件复制到 `include/SDL2/` → 5 文件校验）
`run_unit_test.py` 退出码 2 / 报"找不到 MSVC cl.exe"	本机未装 VS（C++ 工作负载）	按 §2.3 装 VS2019/2022/2026（勾"使用 C++ 的桌面开发"），装完即有 `cl.exe`；提交看门狗相关改动时该钩子会拦截，必须装
`run_unit_test.py` 编译报 `C1083: 无法打开包括文件 "stdio.h"`	VS 未勾选 Windows SDK，或 `cl.exe` 路径异常	在 VS Installer 里补勾 Windows 10/11 SDK；脚本已按本机 VS/SDK 目录自动拼 `INCLUDE`/`LIB`，无需手动 `vcvars64.bat`（其内部 `reg.exe` 在受限机器上会被安全策略拦截）
`.venv` 不存在 / 脚本 ModuleNotFound	venv 未建（不入库）	按 §2.4 重建 + `pip install -r requirements.txt`
pip 装依赖报 UnicodeDecodeError	`requirements.txt` 含中文注释	保持该文件纯 ASCII（pip 按 GBK 代码页解码）
字体生成 / 转 PNG 报缺模块	误用 PATH 里的 msys64 python	一律用 `.venv\Scripts\python.exe`
内容页回归 exit 2（参考缺失）	`tests/ref/` 是本地生成物、不入库	先 `check_content_pages.py --update` 生成参考，再跑回归
串口采集不到 / 端口占用	COM 号变化 / 上一进程未释放	改 `.opencode/serial_config.json`；`serial_tool.py ports` 查实际端口，`open` 占用 ≤1s 报 `port busy`
烧录失败	下载器未选 / USB 驱动缺失	Keil `Options for Target → Debug` 选对驱动；安装下载器 USB 驱动
下载报 Flash 算法 / FLM 文件找不到	未安装 `Keil::STM32F4xx_DFP` pack（FLM 来自 pack 目录，不在仓库）	Pack Installer 安装该 pack 后重新下载
UV4 启动弹 license 窗口 / 无法编译	90 天评估 license 过期或未激活	`Options for Target → License` 查看/输入；长期使用购买正式 license
提交被钩子拦截	cppcheck / 规范 / 乱码 / gitlint 任一失败	按 pre-commit 输出逐项修复；禁止 `--no-verify` 跳过门禁
改代码后"没生效"	新 `.c` 漏双端注册 / 模拟器缓存	走 `new-source-file` 双端注册流程；`cmake --build` 增量或删 `simulator/build/` 重建

七、相关文档

主题	文档
项目全景架构	`docs/架构设计/项目架构总览.md`
启动顺序 / 就绪屏障	`docs/架构设计/项目启动顺序管理.md`
内存预算详析 / 优化方案 / 栈观测	`docs/内存管理/RAM使用分析与优化方案.md`（主文档）· `docs/内存管理/内存内容分配策略.md`（区域与 DMA 规则）
网口配置 / 生效链路	`docs/子系统设计/网络配置说明.md`
远程显示协议	`docs/UI设计/RemoDispBus协议与接收设计说明.md`
LVGL 模拟器部署	`docs/UI设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md`
串口调试 / 自动化测试	`docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md`
测试分层 / L0.5 主机侧单测	`docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（L0.5 范式：MSVC 离线编译 + 平台桩）
pre-commit / cppcheck	`docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md`
引用关系图（文件引用）	`docs/架构设计/引用关系图说明.md`（生成工具 `tools/refgraph`；渲染依赖 Graphviz，§2.8）
各模块测试指南	`docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md`
已知硬件陷阱	`docs/问题记录/CH395F_Trap_Records.md` 等

变更记录

日期	变更
2026-10-01	补主机侧单元测试（L0.5）环境要求：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确同一套 VS 的 `cl.exe` 同时服务模拟器与单测，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点
2026-09-21	更正 SDL2 描述：`simulator/SDL2/` 并不入库（gitignore，fresh clone 缺失），原"随仓库提供/不用装"表述有误；第 3 步补全官方预编译包下载（直链 + 内网中转）、解压、`include/SDL2/` 头文件复制、5 文件校验步骤；§2.3 表格与速查表同步修正
2026-09-21	模拟器构建改为自适应：新增 `simulator/build_sim.bat/.ps1`（vswhere 自动探测本机 VS 大版本 → 生成器 16=2019 / 17=2022 / 18=2026；`build/` 生成器不符自动删除重建，删除带重试抗文件锁）；VS 版本不再固定，2019/2022/2026 兼容：总览图、§2.3、第 3 步、第 10 步冒烟、搭建清单、速查表同步更新
2026-09-16	补 Graphviz（引用关系图渲染，可选）：新增 §2.8，原 §2.8/§2.9 顺延为 §2.9/§2.10（章节内步骤号不变）；总览图、搭建清单、§2.10 下载表、相关文档各补一项
2026-09-13	初版：汇总开发机（Keil / VS2019+SDL2 / Python venv / 字体 / 串口工具 / pre-commit）、目标板（引脚 / 资源预算 / 下载 / 功能开关）、网络现场部署（默认参数 / 端口 / 验收清单）、远端客户端四类环境要求，附一次性搭建清单（含分步安装命令与冒烟验证）与常见环境问题速查
2026-09-13	§2.8 各组件补手动下载网址；新增 §2.9 手动下载来源速查表
2026-09-15	串口调试/自动测试工具由 serial-mcp-server 切换为仓库内置 Python 串口助手（serial_tool，.venv + pyserial，免安装）：§2.4 依赖清单、§2.6、§2.8 第 7/9/10 步、搭建清单、§2.9 下载表（去 Rust/serial-mcp-server）、速查表、相关文档同步
2026-09-13	补 STM32CubeMX 6.17.0 + STM32Cube FW_F4 V1.28.3（与 .ioc 一致）：拓扑图 / §2.2 / 第 2 步 / §2.9 / 搭建清单，常见问题速查增加再生成版本不匹配条目
2026-09-13	新增"Keil 初始化配置（机器侧项，非项目自带）"：license / Device Pack（含 FLM 来源解析路径）/ 下载器驱动，并列出项目自带免配置项；§六速查补 FLM 缺失、license 过期两条
2026-09-13	补 RAM/Flash 链接布局说明：手动 scatter 文件 `STM32F407-Demo.sct`（在仓库）为链接依据（128KB = SRAM1+SRAM2，SRAM3/CCM 未映射），新机器无需重设、勿改 GUI Target 页

40 KiB Raw Blame History Unescape Escape