欢迎关注 youcans@xidian【嵌入式软件AI编程】专栏
【嵌入式软件AI编程】03. STM32 VS Code 开发环境与工具链
【嵌入式软件AI编程】04. AI 编程 的STM32开发流程
本专栏结合STM32项目实践，介绍嵌入式软件AI编程的实战路径。本专栏内容来自图书《嵌入式系统AI编程》，即将出版。
1.3 第一个STM32工程
本节通过创建一个最小STM32工程，验证STM32 VS Code开发环境能否完成从工程生成到烧录调试的基本流程。这一过程既能帮助读者熟悉环境操作，也为后续引入Claude Code参与项目开发做好准备。
1.3.1 使用STM32CubeMX创建工程
开始创建工程之前，请确认软硬件环境已经准备就绪。
- 软件需求：
需完成上一节介绍的STM32CubeMX、STM32CubeProgrammer、VS Code以及STM32扩展工具的安装与检查。 - 硬件需求：
需准备一块STM32开发板、板载或外接ST-LINK调试器，以及一条可传输数据的USB连接线。
本书使用NUCLEO-G431RB开发板，板载STM32G431RBT6芯片与ST-LINK/V3E调试器。也可以使用其他NUCLEO开发板，如NUCLEO-F103RB、NUCLEO-H533RE、NUCLEO-H755ZI等。不同开发板的芯片型号、引脚定义和调试接口可能不同，实际配置时应以所用开发板的型号、原理图或官方说明为准。
建议在计算机中建立一个专门存放STM32项目的目录，如C:/STM32/WorkspaceG431，本书后续工程均存放于此目录下。
- 第1步：启动STM32CubeMX并新建工程。
打开STM32CubeMX，单击File→NewProject进入新建工程选择界面。STM32CubeMX提供了按芯片型号（MCU Selector）和按开发板型号（Board Selector）两种选择方式，本书选用Board Selector方式。在搜索框中输入并选中NUCLEO-G431RB，然后单击Start Project按钮，进入工程配置界面。
- 第2步：配置调试接口、时钟和GPIO引脚。
进入工程配置界面后，对调试接口、时钟和GPIO进行配置。
（1）配置调试接口。
在Pinout&Configuration选项卡中，选择System Core→SYS设置调试器类型，将Debug模式设置为Serial Wire，启用SWD接口用于后续程序下载和在线调试。
（2）配置时钟模式。
选择System Core→RCC配置时钟模式。对于本节创建的最小STM32工程，保持默认时钟配置即能满足LED闪烁示例的运行需要。后续如果需要更高系统主频或更高时钟精度，可以根据芯片手册配置HSE、PLL及相关分频参数。
（3）配置LED引脚。
NUCLEO-G431RB板载用户LED连接至PA5。如图1-8所示，在右侧的芯片封装图中单击PA5引脚，在弹出菜单中选择GPIO_Output，将其配置为输出模式。然后在左侧配置栏中选择System Core→GPIO，并在引脚列表中选中PA5，在User Label中命名为"LD2"。
设置标签后，STM32CubeMX会在生成的代码中自动使用该名称，例如LD2_Pin、LD2_GPIO_Port。
图1-8 在STM32CubeMX中进行引脚配置
- 第3步：配置工程选项。
单击上方的Project Manager选项卡，进入工程设置页面，如图1-9所示。单击左侧的Project菜单，输入工程名称"GPIO_IoToggle"，并选择保存路径。注意工程路径中不要包含中文、空格或特殊字符。
图1-9 在STM32CubeMX中进行工程配置
在Toolchain/IDE下拉菜单中选择CMake，在Default Compiler/Linker菜单中选择GCC。这是开发环境的关键配置，使VSCode能够直接打开和构建STM32CubeMX生成的工程。
- 第4步：生成工程代码。
完成以上设置后，单击右上角的GENERATE CODE按钮生成工程代码。首次创建工程时，STM32CubeMX可能会提示下载对应的MCU软件包，按提示完成下载即可。
代码生成完成后，打开工程目录，可以看到.ioc文件、CMakeLists.txt文件以及Core、Drivers等文件夹，说明工程已创建成功。至此，一个基于CMake的STM32工程已经生成，并完成了调试接口、时钟、LED和用户按键的配置。工程目录中包含了CMake工程文件、HAL库源码，以及main.c等用户代码文件。下一节将在VS Code中打开这个工程，并开始编写代码。
1.3.2 使用VS Code运行STM32程序
本小节打开上一小节创建的"GPIO_IoToggle"工程，编写一个LED闪烁程序，并完成编译、烧录和运行验证。程序运行后，开发板上的LD2指示灯以1s为周期闪烁。
-
第1步：在VS Code中打开工程。
启动VS Code，切换到之前创建的"STM32"配置文件。在顶部菜单中选择File→Open Folder...，打开上一小节生成的工程目录，例如C:/STM32/WorkspaceG431/GPIO_IoToggle，在左侧资源管理器中可以看到.ioc文件、CMakeLists.txt文件，以及Core、Drivers等文件夹。
-
第2步：执行CMake配置。
首次打开工程要执行一次CMake配置。按下Ctrl+Shift+P打开命令面板，输入并执行CMake: Configure，选择Debug模式。Debug为调试版本，便于学习、测试和在线调试；Release通常用于正式发布。VS Code将读取工程中的CMakeLists.txt文件，并生成构建所需的配置文件。STM32扩展工具会识别当前工程为STM32Cube工程，并调用相应工具链完成初始化。
配置完成后，如图1-10所示，工程目录中出现"build/Debug"文件夹，说明CMake配置已完成，工程可以进入编译阶段。
图1-10 在VS Code中执行CMake配置
-
第3步：打开main.c文件。
在VS Code左侧资源管理器中，依次展开Core→Src，双击打开Core/Src/main.c文件。main.c是本工程的主程序文件，包含系统初始化、外设初始化和主循环等代码。
在main.c文件中找到while(1)主循环。STM32上电并完成初始化后，会不断重复执行while(1)中的代码。因此，只要将LED闪烁代码写在该循环内部的用户代码区域即可。
-
第4步：编写LED闪烁代码。
在while(1)主循环中找到USER CODE BEGIN 3和USER CODE END 3标记，并在两者之间加入以下代码：
c
HAL_GPIO_TogglePin(LD2_GPIO_Port, LD2_Pin);
HAL_Delay(500);修改后的主循环代码如下：
c
/* USER CODE BEGIN WHILE */
while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
HAL_GPIO_TogglePin(LD2_GPIO_Port, LD2_Pin);
HAL_Delay(500);
}
/* USER CODE END 3 */其中，HAL_GPIO_TogglePin()用于翻转用户LED（LD2）的引脚电平；HAL_Delay(500);则产生500毫秒的延时。主循环每执行一次，LED状态翻转一次，两次翻转构成一个完整周期，因此LED将以1秒的周期（500ms亮，500ms灭）闪烁。
需要注意的是，用户代码应写在USER CODE BEGIN和USER CODE END标记之间。这样即使重新使用STM32CubeMX生成代码，用户编写的代码也不会被覆盖。
- 第5步：编译工程。
保存main.c文件后，开始编译工程。单击VS Code底部工具栏中的"生成（Build）"按钮，或通过命令面板执行CMake: Build。VS Code会调用CMake、Ninja和ARM GCC等底层工具，对工程代码进行编译和链接。
编译过程中，可以在终端或输出窗口中查看构建信息。如果编译成功，输出信息中会显示构建完成；如果编译失败，则会显示具体的错误位置和错误原因。
编译成功后，工程目录中会生成固件文件，例如"build/Debug/GPIO_IoToggle.elf"，该文件是后续烧录和调试所使用的目标文件。
- 第6步：烧录程序。
使用USB数据线将NUCLEO-G431RB开发板连接到计算机。开发板连接后，电源指示灯应正常点亮，VS Code提示识别到ST-LINK调试器。
在VS Code左侧活动栏中单击"运行和调试"图标进入调试面板，再单击"运行和调试"按钮启动调试会话。如果VS Code提示选择调试器，可以选择STM32Cube: STM32 Launch ST-Link GDB Server；如果提示创建launch.json文件，可以按提示创建默认调试配置。
调试会话启动后，VS Code会检查工程是否已经成功编译，并将程序下载到STM32开发板中，同时建立ST-LINK调试连接。程序下载完成后，VS Code会进入调试状态，并暂停在main()函数附近。单击顶部调试工具栏中的"继续"按钮，或按下F5，程序即可继续运行。
如果程序运行正常，开发板上的LD2指示灯会按照固定时间间隔闪烁，说明工程创建、代码编写、编译构建、程序烧录和程序运行等基本环节已经全部打通。
- 第7步：停止运行与完成验证。
完成测试后，可以单击顶部调试工具栏中的"停止"按钮，或使用快捷键Shift+F5退出当前调试连接。
至此，已经跑通第一个STM32工程从代码编写到编译烧录的基本流程。如果LED正常闪烁，说明STM32CubeMX生成的工程代码、VS Code中的CMake构建环境、ST-LINK下载连接以及STM32芯片运行环境均已正常工作。下一小节将进一步介绍如何在VS Code中设置断点、单步执行和观察程序运行过程。
版权声明：
欢迎关注 youcans@xidian【嵌入式软件AI编程】专栏
转发必须注明原文链接：
Copyright by ai4mcu@qq.com
Crated：2026-09