From cb8cea38b280ea820e6c5bc6c1b7825cfcc1c6c2 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Sun, 13 Sep 2026 17:05:59 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E9=A1=B9=E7=9B=AE=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E7=8E=AF=E5=A2=83=E8=A6=81=E6=B1=82=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=8CREADME=20=E6=96=87=E6=A1=A3=E7=B4=A2=E5=BC=95=E5=90=8C?= =?UTF-8?q?=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 +- docs/项目部署环境要求.md | 490 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 492 insertions(+), 1 deletion(-) create mode 100644 docs/项目部署环境要求.md diff --git a/README.md b/README.md index a249738f..d0e2b3f1 100644 --- a/README.md +++ b/README.md @@ -374,13 +374,14 @@ pre-commit run --all-files | 文档 | 说明 | |------|------| | `docs/项目架构总览.md` | **项目全景架构**（六层分层 + 任务/就绪屏障 + 启动时序 + 存储/网络/UI 栈 + 目录组织） | +| `docs/项目部署环境要求.md` | **部署环境要求**（开发机 / 目标板 / 网络与现场 / 远端客户端）+ 分步安装命令 + 下载来源速查 + 验收清单 | | `docs/STM32F4-Base存储架构说明.md` | 三层存储软件栈详解（FatFS → dhara FTL → NAND） | | `docs/项目启动顺序管理.md` | Event Flags 就绪屏障设计 | | `docs/系统墙钟时间维护说明.md` | RTC + 墙钟时间子系统 | | `docs/网络配置说明.md` | 网口设置页配置（UI 可改的 IP/掩码/网关/MAC：持久化 + 立即生效 + 页面操作） | | `docs/UI 设计/UI_设计架构.md` | LVGL UI 系统架构（菜单 / 内容页 / 内存预算） | | `docs/UI 设计/菜单页面设计.md` | 菜单导航行为、数据流与内容页设计 | -| `docs/UI 设计/UI_界面制作流程.md` | 参考图 → HTML 样机 → LVGL 代码管线（P0~P5 门禁） | +| `docs/UI 设计/UI_界面制作流程.md` | 参考图 → 设计规格 → LVGL 代码管线（P0~P4 门禁） | | `docs/UI 设计/UI_中文字体生成与配置.md` | 中文字体生成与配置 | | `docs/UI 设计/LVGL模拟器部署与使用说明.md` | LVGL PC 模拟器部署 | | `docs/UI 设计/UI_自动化测试流程.md` | UI 回归门禁（脚本 + 池水位常量 + 黄金参考更新） | diff --git a/docs/项目部署环境要求.md b/docs/项目部署环境要求.md new file mode 100644 index 00000000..6e34bbdb --- /dev/null +++ b/docs/项目部署环境要求.md @@ -0,0 +1,490 @@ +# 项目部署环境要求 + +> 版本：v1.0　日期：2026-09-13 +> 适用工程：STM32F4-Base（STM32F407ZGTx + CH395F 以太网 / LVGL UI / FreeRTOS） +> 用途：新机器搭建、环境交接、现场部署时的**一站式环境核对清单**——开发机软件环境、 +> 目标板硬件与资源预算、网络/服务现场部署、远端客户端环境、验收步骤与常见环境问题。 +> 文中所有版本/参数/数值均取自仓库内配置或本机实测（`AGENTS.md`、`MDK-ARM/*.bat`、 +> `simulator/README.md`、`docs/内存管理/`、`docs/网络配置说明.md`、`docs/测试说明/` 等）， +> 换机器时以仓库文件为准逐项核对。 + +--- + +## 一、环境总览 + +本项目涉及三类环境，部署前按 §二~§五 逐一核对： + +```mermaid +flowchart LR + subgraph DEV["① 开发机（Windows PC）"] + K[Keil MDK-ARM v5
MCU 编译/烧录] + X[STM32CubeMX 6.17.0
外设配置/代码再生成] + S[CMake + VS2019
LVGL PC 模拟器] + P[Python .venv
字体/回归脚本] + T[serial-mcp-server
串口调试/自动测试] + end + subgraph TGT["② 目标板（DTU 硬件）"] + M[STM32F407ZGTx @168MHz
1MB Flash / 192KB SRAM] + H[CH395F / GD5F2GQ5UE
TPAFE5160 / RS-485 / LED×6] + end + subgraph RMT["③ 远端客户端（PC/浏览器）"] + C[DTU-RemoteLCD
或任意 TCP 客户端] + end + + DEV -- "USB：下载器（ST-Link 等）" --> TGT + DEV -- "USB 串口 USART1
COMx @115200 调试日志" --> TGT + TGT -- "以太网（CH395F）
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\\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` 的 `` 行（IRAM 112 KB / IRAM2 16 KB / IROM 1 MB，同样在仓库）+ Device Pack +- ⚠ 新机器**不要在 GUI 里重填 RAM 区**，也**勿改 Target 页**（会回写共享的 `.uvprojx` 影响他人）；确需调整内存布局（如日后启用 SRAM3/CCM）时修改 `.sct` 并提交 + +### 2.3 PC 模拟器环境（UI 开发/回归必需） + +| 项 | 要求 | 说明 | +|---|---|---| +| CMake | ≥ 3.15 | 本机实测 4.3.0-rc1 | +| 编译器 | **Visual Studio 16 2019**（C++ x64 工作负载） | 生成器固定 `"Visual Studio 16 2019"`、`-A x64`；CMakeLists 已加 `/utf-8` 消中文注释告警 | +| Windows SDK | 10.0.19041 及以上 | CMake 配置时自动选用已装版本 | +| SDL2 | 2.32.10 | **随仓库提供**（`simulator/SDL2/` 预编译 SDK，含 x64 库与头文件副本），无需系统安装 | +| 产物 | `simulator/build/Debug/lvgl_sim.exe` | `build/` 为生成物（gitignore），可整体删除重建 | + +```powershell +cd simulator +cmake -B build -G "Visual Studio 16 2019" -A x64 # 仅首次（改 CMakeLists.txt 后需重跑） +cmake --build build --config Debug # 日常增量 +.\build\Debug\lvgl_sim.exe # 运行（纯键盘导航 ↑↓←→ / Enter / Esc） +``` + +> 模拟器与 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` | 清单 = 仓库根 `requirements.txt`（**必须保持纯 ASCII**：Windows 下 pip 按 GBK 代码页解码，中文注释会 UnicodeDecodeError） | +| 入库情况 | `.venv/` 已 gitignore | **换机/首次必须重建** | + +```powershell +# 重建（<种子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` 依赖 | + +```powershell +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 串口调试 / 自动化测试工具 + +| 项 | 要求 | 说明 | +|---|---|---| +| serial-mcp-server | v0.3.0（Rust，自源码 `cargo build --release`） | 安装于 `%LOCALAPPDATA%\serial-mcp-server\`；MCP（AI 交互）与 CLI（脚本采集）两用 | +| 调试串口 | USART1（PA9 TX / PA10 RX），115200 8N1 | **端口单一配置源 `.opencode/serial_config.json`**（本机 COM6）；换端口只改这个文件 | +| 一键测试 | `test\run_boot_test.ps1`（即 `@test`） | 采集窗口武装 → 烧录 → 日志标记校验；默认 COM6 / 115200，退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 | + +> 关键顺序：**串口采集必须先于烧录复位武装**（`-FlashCmd` 分支已保证）。 +> 参数经验值与陷阱见 `docs/测试说明/serial-mcp-server_串口调试.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，纯标准库） | +| 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`。 + +### 2.8 开发机一次性搭建（分步安装命令） + +以下命令在 PowerShell 中直接执行（新机器从零搭建，全程约 1~2 小时），逐步对照文末清单打勾。 + +**第 1 步：git** + +```powershell +winget install Git.Git +``` + +> 手动下载：https://git-scm.com/download/win （Git for Windows） + +**第 2 步：Keil MDK-ARM v5 + STM32CubeMX**（GUI 安装，无命令行方式） + +- 下载页：（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 步：VS2019 + CMake**（模拟器工具链） + +```powershell +winget install Kitware.CMake # ≥3.15 +``` + +- VS2019 Community 已下架主站，从**存档页**下载：（直链：） + - 工作负载勾选 **“使用 C++ 的桌面开发”**；单个组件勾 **Windows 10 SDK (10.0.19041)** +- **SDL2 不用装**——仓库 `simulator/SDL2/` 已含 2.32.10 预编译 SDK（仅当缺失时补：https://github.com/libsdl-org/SDL/releases ） + +**第 4 步：Python**（`.venv` 脚本工具链） + +```powershell +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 + 字体工具** + +```powershell +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**（提交门禁） + +```powershell +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 步：serial-mcp-server**（串口调试 / 自动测试，Rust 源码编译） + +```powershell +winget install Rustlang.Rustup +git clone https://github.com/Adancurusul/serial-mcp-server +cd serial-mcp-server; cargo build --release +New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\serial-mcp-server" | Out-Null +Copy-Item target\release\serial-mcp-server.exe "$env:LOCALAPPDATA\serial-mcp-server\" +``` + +> 手动下载：Rust → https://www.rust-lang.org/tools/install （运行 `rustup-init.exe`）· serial-mcp-server 源码 → https://github.com/Adancurusul/serial-mcp-server + +**第 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 步：串口配置** + +```powershell +& "$env:LOCALAPPDATA\serial-mcp-server\serial-mcp-server.exe" serial_list_ports # 查 COM 号 +``` + +把查到的端口写入 `.opencode\serial_config.json` 的 `portName`（唯一配置源，换口只改这里）。 + +**第 10 步：冒烟验证**（全过 = 环境就绪） + +```powershell +& "MDK-ARM\build.bat" # → BUILD_OK: 0 errors, 0 warnings +cd simulator +cmake -B build -G "Visual Studio 16 2019" -A x64 +cmake --build build --config Debug # 0 警告 +.\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 +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（C++ x64 工作负载）+ Windows 10 SDK + CMake ≥3.15 +- [ ] `git clone` 仓库 → `pre-commit install`；cppcheck 入 PATH +- [ ] 建 `.venv` 并 `pip install -r requirements.txt` +- [ ] `npm i -g lv_font_conv` +- [ ] serial-mcp-server 编译放置，写好 `.opencode/serial_config.json`（本机 COM 口） +- [ ] 下载器（ST-Link 等）USB 驱动已装，Keil `Options for Target → Debug` 驱动一致 +- [ ] 第 10 步冒烟验证全部通过 + +### 2.9 手动下载来源速查 + +§2.8 中需下载组件的官方下载地址汇总（正文的 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 | +| 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 | +| Rust（rustup） | https://www.rust-lang.org/tools/install | 运行 `rustup-init.exe` | +| serial-mcp-server | https://github.com/Adancurusul/serial-mcp-server | 源码 `cargo build --release`（v0.3.0） | +| 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，一般不需要 | + +> 获取渠道优先级：① `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/内存管理/STM32F4-Base内存使用分析报告.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/run_boot_test.ps1 -FlashCmd` 已保证顺序） | + +### 3.5 功能配置开关 + +| 开关 | 位置 | 当前值 | 说明 | +|---|---|---|---| +| `APP_NET_ENABLE` | `App/app_cfg.h` | 开 | 网络（CH395F + 全部 TCP 服务） | +| `APP_ADC_ENABLE` | 同上 | 开 | TPAFE5160 采样 | +| `APP_RS485_ENABLE` | 同上 | 开 | RS-485 通信 | +| `TEST_SUITE_*` | `test/test_config.h` | 全注释（产品构建） | 测试套件**互斥**：一次构建只开一个（CH395F / 存储 / GD5F / RTC）；全注释 = 正常产品固件 | + +--- + +## 四、网络与现场部署 + +### 4.1 网络参数 + +| 参数 | 工厂默认 | 修改方式 | +|---|---|---| +| IP | **192.168.1.100**（静态，无 DHCP） | 屏幕 `通讯参数 → 网口设置`（修改密码 `123`）保存后**立即生效**（网络重建约 1~3 s）；或预置 `/cfg/netcfg.bin` | +| 子网掩码 | 255.255.255.0（/24） | 同上 | +| 默认网关 | 192.168.1.1 | 同上 | +| MAC | 全零 = 芯片内置 MAC | 同上（全零是"使用芯片内置 MAC"的哨兵，不是"MAC 为 0"） | +| PHY | 强制 100M 全双工 | 固件固定，不可配 | + +- 配置持久化：NAND 上 FatFS 文件 `/cfg/netcfg.bin`（magic `'NCFG'` + CRC-16/MODBUS；缺失/损坏回退工厂默认，不带崩网络） +- 立即生效机制：保存 → 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`）——格式化前 NAND 上无数据（含网口配置） +- 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 | 掉电保持 | 写文件 / 改网口配置 → 重启 | 数据仍在（`/cfg/netcfg.bin` 按新值生效） | +| 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 配置失败：找不到生成器 | 未装 VS2019 | 装 VS2019（C++ x64 工作负载）；勿改生成器（工程按 VS16 配置） | +| 模拟器构建报 `SDL2/SDL.h` 找不到 | 头文件副本缺失 | 按 `simulator/README.md` §四.1 把 SDK 头文件复制到 `include/SDL2/`（仓库已含，仅删过 SDK 目录才需要） | +| `.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_capture.ps1` 已带 EOF 自动重试 | +| 烧录失败 | 下载器未选 / 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/内存管理/STM32F4-Base内存使用分析报告.md` | +| 网口配置 / 生效链路 | `docs/网络配置说明.md` | +| 远程显示协议 | `docs/UI 设计/RemoDispBus协议与接收设计说明.md` | +| LVGL 模拟器部署 | `docs/UI 设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md` | +| 串口调试 / 自动化测试 | `docs/测试说明/serial-mcp-server_串口调试.md`、`docs/测试说明/自动化测试流程.md` | +| pre-commit / cppcheck | `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md` | +| 各模块测试指南 | `docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md` | +| 已知硬件陷阱 | `docs/问题记录/CH395F_Trap_Records.md` 等 | + +--- + +## 变更记录 + +| 日期 | 变更 | +|---|---| +| 2026-09-13 | 初版：汇总开发机（Keil / VS2019+SDL2 / Python venv / 字体 / 串口工具 / pre-commit）、目标板（引脚 / 资源预算 / 下载 / 功能开关）、网络现场部署（默认参数 / 端口 / 验收清单）、远端客户端四类环境要求，附一次性搭建清单（含分步安装命令与冒烟验证）与常见环境问题速查 | +| 2026-09-13 | §2.8 各组件补手动下载网址；新增 §2.9 手动下载来源速查表 | +| 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 页 |