STM32CubeMX + VS Code 从零搭建 STM32F429 开发环境（阿波罗开发板LCD实战）

本文记录了从零开始，在正点原子阿波罗 STM32F429IGT6 开发板上，使用 STM32CubeMX + VS Code + CMake + OpenOCD 搭建开发环境的完整过程。包含每一个自己踩过的坑和解决方法，根据硬件的差别，一些参数可能略有不同的配置。

一、环境准备清单

软件	版本建议	说明
STM32CubeMX	6.11.0 及以上	低版本没有 CMake 选项！
STM32CubeCLT	1.15.0 及以上	包含 CMake、Ninja、ARM 工具链
VS Code	最新版	建议单独建一个 Profile
STM32Cube for VS Code	预发布版	ST 官方扩展
Cortex-Debug	最新版	用于 DAP 调试
OpenOCD (xPack)	0.12.0+	DAP 调试器必须，ST-Link 不用
STM32CubeProgrammer	最新版	备用烧录工具

硬件：阿波罗 F429IGT6 开发板、DAP 调试器、ST-Link（可选）

---

二、坑 1：CubeMX 版本太低，没有 CMake 选项

现象

在 Project Manager → Toolchain / IDE 下拉框里，只有 EWARM、MDK-ARM、Makefile 等，找不到 CMake。

原因

CMake 选项是 STM32CubeMX 6.10 才加入的。

解决

去 ST 官网下载最新版 CubeMX（6.11+），安装路径不要有中文和空格。

---

三、坑 2：工程迁移固件包

现象

升级 CubeMX 后打开旧工程，弹窗提示：
This project was setup with STM32CubeMX V6.3.0 using STM32Cube FW_F4 V1.26.2.
STM32CubeMX V6.18.1 can work with STM32Cube FW_F4 V1.28.3.

解决

1. 点击 Migrate（迁移）。
2. 提示下载固件包时，点击 Yes。
3. 许可协议页面选第一个"同意"，点 Finish。
4. ST 的邮件通知服务点 Don't ask me again。

---

四、时钟树配置：HSE + 180MHz

关键概念

• HSE = 外部高速晶振。阿波罗板载 25MHz 晶振。
• Crystal/Ceramic Resonator = 使用外部晶振模式。

配置步骤

1. System Core → RCC → High Speed Clock (HSE) 选 Crystal/Ceramic Resonator。
2. 切到 Clock Configuration 标签页：
   • 确认 HSE = 25 MHz
   • PLL Source 选 HSE
   • 在 HCLK (MHz) 输入框填 180，回车
   • CubeMX 会自动算好 PLLM=15、PLLN=216、PLLP=2

验证

时钟树底部应显示：
HCLK = 180 MHz
APB1 = 45 MHz (上限 45MHz)
APB2 = 90 MHz (上限 90MHz)

---

五、坑 3：FMC 配置（最容易配错的地方）

关键参数

参数	正确值	说明
Chip Select	NE1	阿波罗 LCD 片选接在 NE1
Memory type	LCD Interface	不是 SRAM！
LCD Register Select	A18	LCD 的 RS 引脚接在 A18
Data	16 bits	ILI9341/ST7789 并口数据宽度
Address	16 bits	默认

常见错误

把 Memory type 选成 SRAM，导致下面没有 LCD Register Select 选项，Data 只有 8 bits。

正确操作

把 Memory type 改成 LCD Interface 后，LCD Register Select 才会出现，选 A18。

---

六、坑 4：FreeRTOS 与 HAL 库的时基冲突

现象

勾选 FreeRTOS 后生成代码，CubeMX 弹出警告：
When RTOS is used, it is strongly recommended to use a HAL timebase source other than the Systick.

此时一定要点 No！

原因

• HAL 库默认用 SysTick 做 HAL_Delay() 的时基。
• FreeRTOS 也需要 SysTick 做任务调度。
• 两者冲突会导致 HAL_Delay() 卡死。

解决

1. System Core → SYS。
2. Debug 从 Disable 改成 Serial Wire（不然下面的配置项不显示）。
3. Timebase Source 从 SysTick 改成 TIM6 或 TIM7。
4. 重新 GENERATE CODE。

---

七、坑 5：VS Code 找不到 CMake

现象

[extension] 重试 4 次后未找到 CMake
[proc] 命令"C:\Windows\System32\where.exe cl"已退出，代码为 1

原因

VS Code 的 CMake Tools 插件没找到 cmake.exe，还误以为你要用微软 MSVC 编译器。

解决

在 .vscode/settings.json 或工作区设置里配置（或者直接把cmake.exe路径加到系统环境变量，这个可以自行百度）：

{
    "cmake.cmakePath": "E:\\ST\\STM32CubeCLT_1.22.0\\CMake\\bin\\cmake.exe"
}

八、坑 6：VS Code 找不到 Ninja

现象

CMake Error: CMake was unable to find a build program corresponding to "Ninja".

原因

CMAKE_MAKE_PROGRAM 没设置。CMake 知道在哪了，但 Ninja 还不知道。

解决（最稳的方法）：配置系统环境变量

1. Windows 搜索“环境变量” → 编辑系统环境变量。
2. 新建系统变量 STM32CLT_PATH，值为 E:\ST\STM32CubeCLT_1.22.0。
3. 编辑 Path，添加以下条目：

%STM32CLT_PATH%\CMake\bin
%STM32CLT_PATH%\Ninja\bin
%STM32CLT_PATH%\GNU-tools-for-STM32\bin
%STM32CLT_PATH%\STLink-gdb-server\bin
%STM32CLT_PATH%\STM32CubeProgrammer\bin

4. 彻底关闭 VS Code（任务管理器确认 Code.exe 全部结束），重新打开。

验证

在 VS Code 终端里输入：

ninja --version
cmake --version
arm-none-eabi-gcc --version

三个都能输出版本号，说明环境配好了。

---

九、坑 7：HAL_SRAM_MspInit 重复定义

现象

multiple definition of `HAL_SRAM_MspInit';
fmc.c:156: first defined here

原因

• CubeMX 生成的 fmc.c 里已经有 HAL_SRAM_MspInit。
• 从正点原子移植的 my_lcd.c 里又写了一份。

解决

删掉 my_lcd.c 里以下两个函数：

1. lcd_fmc_init() —— FMC 初始化，CubeMX 已经在 MX_FMC_Init() 里做了。
2. HAL_SRAM_MspInit() —— GPIO 和时钟初始化，CubeMX 已经在 fmc.c 里做了。

lcd_init() 里去掉 lcd_fmc_init() 调用，只保留 ST7789 初始化序列和背光控制。

---

十、坑 8：LCD 地址映射（NE1 + A18）

关键地址计算

• FMC Bank1 NE1 的基地址：0x60000000
• LCD 的 RS 引脚接在 A18，地址偏移：1 << 6 = 64
• 16 位数据宽度，地址要乘 2：64 × 2 = 128 = 0x80

正确宏定义

#define LCD_REG     (*(volatile uint16_t *)0x60000000)		
#define LCD_RAM     (*(volatile uint16_t *)0x60080000)   

---

十一、坑 9：缺少头文件声明

现象

error: implicit declaration of function 'write_lcd_cmd'
error: implicit declaration of function 'delay_ms'
error: implicit declaration of function 'lcd_init'

解决

三处都要改：

1. st7789_reginit.c 顶部：

#include "my_lcd.h"

2. my_lcd.h 的 #endif 之前加上函数声明：

void lcd_ex_st7789_reginit(void);
void delay_ms(uint32_t ms);
void delay_us(uint32_t us);

3. main.c 的 /* USER CODE BEGIN Includes */：

#include "my_lcd.h"

---

十二、坑 10：delay.c 与 FreeRTOS 冲突

现象

直接用正点原子的 delay.c，报：

• HAL_Delay 重复定义
• SysTick_Handler 重复定义

原因

• delay.c 里重定义了 HAL_Delay()，和 HAL 库冲突。
• delay.c 里定义了 SysTick_Handler()，和 FreeRTOS 的调度器冲突。

解决

不要移植 delay.c，直接在 my_lcd.c 里写两个简单的延时函数：

/* 微秒级延时（180MHz 主频忙等待，约 1us） */
void delay_us(uint32_t us)
{
    while (us--)
    {
        for (volatile uint32_t i = 0; i < 45; i++);
    }
}

/* 毫秒级延时，直接用 HAL 库 */
void delay_ms(uint32_t ms)
{
    HAL_Delay(ms);
}

---

十三、坑 11：DAP 调试器配置（OpenOCD）

现象

Failed to launch OpenOCD GDB Server: Error: spawn openocd.exe ENOENT

原因

Cortex-Debug 找不到 openocd.exe。

解决

1. 下载 xPack OpenOCD：https://github.com/xpack-dev-tools/openocd-xpack/releases
2. 解压到 C:\OpenOCD（路径不要有中文和空格）。
3. 把 C:\OpenOCD\bin 加到系统环境变量 Path。
4. 彻底重启 VS Code（不只是 reload）。

launch.json 配置（DAP 调试器）

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug (OpenOCD)",
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "openocd",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build/Debug/Smart_Environmental_Monitoring.elf",
            "device": "STM32F429IGT6",
            "serverpath": "C:/OpenOCD/bin/openocd.exe",
            "configFiles": [
                "interface/cmsis-dap.cfg",
                "target/stm32f4x.cfg"
            ],
            "runToEntryPoint": "main",
            "svdFile": "${workspaceFolder}/STM32F429xx.svd"
        }
    ]
}

关键点：

• serverpath 显式指定 openocd 路径，不依赖环境变量，最稳。
• DAP 用 interface/cmsis-dap.cfg，ST-Link 用 interface/stlink.cfg。
• runToEntryPoint 设为 "main"，启动后自动停在主函数。

DAP 与开发板接线

DAP 调试器	阿波罗 F429
SWDIO	PA13
SWCLK	PA14
GND	GND
3.3V	3.3V

---

十四、成功标志

编译成功

[build] [N/N] Linking C executable Smart_Environmental_Monitoring.elf
[build] Memory region         Used Size  Region Size  %age Used
[build]              RAM:       35872 B       192 KB     18.25%
[build]            FLASH:       21132 B         1 MB      2.02%
[build] Build finished with exit code 0

调试成功

Temporary breakpoint 1, main () at main.c:78
78	  HAL_Init();

屏幕成功

红 → 绿 → 蓝循环刷屏。

---

十五、避坑总结

1. CubeMX 6.11+，否则没有 CMake。
2. 路径全部纯英文，不能有中文和空格。
3. FMC 的 Memory type 要选 LCD Interface，不是 SRAM。
4. FreeRTOS 的时基要改成 TIM6，把 SysTick 让给 RTOS。
5. 正点原子的 lcd.c/delay.c 不能直接用，会和 CubeMX 和 FreeRTOS 打架。
6. LCD 地址是 NE1 + A18 → 0x60000000/ 0x60080000。
7. DAP 调试器需要 OpenOCD，并在 launch.json 里显式指定 serverpath。
8. 加完环境变量必须彻底重启 VS Code，reload window 不够。

---

十六、参考链接

• STM32CubeMX 官方下载
• STM32CubeCLT 下载
• xPack OpenOCD Releases
• Cortex-Debug 扩展
• 正点原子官方资料

---

本文基于 STM32F429IGT6 + 阿波罗开发板 + DAP 调试器实战整理，环境搭建耗时约 2 天，希望对你有所帮助。