1. 项目概述与准备工作
拿到一块STM32黑金板（Blackpill），看着上面那颗小小的LED，很多朋友的第一反应可能就是“点灯”。别小看这个操作，它就像嵌入式世界的“Hello World”，是你与这块芯片建立沟通的第一步。我刚开始接触STM32时，也在这个看似简单的环节上折腾了好一阵子，从寄存器直接操作到标准库，再到现在的HAL库，感觉开发方式越来越“人性化”了。今天，我就以手头这块基于STM32F103C8T6的黑金板为例，带你走一遍用STM32CubeIDE和HAL库实现LED闪烁的完整流程。这个过程不仅仅是让灯闪起来，更重要的是理解HAL库的工作逻辑、开发环境的配置思路，以及如何从一个空工程开始，构建起一个可运行的程序框架。
为什么选择HAL库？对于新手和需要快速开发的场景来说，HAL（Hardware Abstraction Layer，硬件抽象层）库的优势很明显。它把底层硬件的寄存器操作封装成了一个个直观的函数，比如HAL_GPIO_WritePin、HAL_UART_Transmit，你不需要去记忆某个外设的某个控制寄存器地址是0x4001 1004，也不需要去查手册看第几位是开关。这种抽象大大降低了入门门槛和开发时间。当然，老手可能会觉得它效率稍低、代码体积大，但对于学习和大多数应用来说，这点开销完全在可接受范围内。黑金板上的用户LED通常连接在PC13引脚上，这是一个开源硬件社区里非常通用的设计，也意味着你跟着教程做，成功率会非常高。
在开始写代码之前，我们需要把“战场”准备好。硬件上，你需要一块STM32F1系列的黑金板（注意区分F103C8和F401CC等不同核心的版本，本教程以最常见的F103C8为例）、一根Micro-USB数据线（既能供电也能下载调试）。软件上，核心就是STM32CubeIDE，这是ST官方推出的免费集成开发环境，它把STM32CubeMX图形化配置工具和基于Eclipse的代码编辑、编译、调试环境整合在了一起，一站式解决所有问题。你可以去ST官网下载对应你操作系统的版本。安装过程基本就是一路“Next”，建议安装路径不要有中文和空格。安装完成后，第一次启动可能会提示你设置工作空间（Workspace），同样建议选择一个英文路径。至此，我们的软硬件基础就搭好了。
2. 工程创建与芯片基础配置详解
打开STM32CubeIDE，映入眼帘的界面可能有点复杂，别慌，我们一步步来。点击菜单栏的File -> New -> STM32 Project，这会启动项目创建向导。首先会弹出一个芯片选择器（Target Selector）。在Part Number搜索框里输入“STM32F103C8”，下面会列出匹配的型号。这里有个关键点：一定要选择后面带有Tx后缀的，比如STM32F103C8Tx。这个T代表芯片封装是LQFP，而黑金板使用的正是这个封装。如果选成不带T的（比如BGA封装），虽然内核一样，但引脚定义会对不上，导致后续配置出错。选中正确的型号后，右下角会显示芯片的基本信息，如Flash大小（64KB）、RAM大小（20KB），核对无误后点击“Next”。
接下来是项目命名和保存。给你的第一个工程起个有意义的名字，比如Blackpill_LED_Blink。Project Location就是工程存放的目录，保持默认或自己指定一个都可以。下面最重要的选项是Project Type。这里一定要选择STM32Cube！这决定了工程是否包含HAL库以及CubeMX的图形化配置界面。Toolchain/IDE默认就是STM32CubeIDE，不用动。语言（Language）选择C。最后，在Code Generator部分，我强烈建议勾选“Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral”。这个选项会把每个外设（如GPIO、USART）的初始化代码单独放在一对.c/.h文件里，而不是全部堆在main.c，这样代码结构更清晰，后续维护和移植也方便。其他选项保持默认，点击“Finish”。
此时，CubeIDE会自动切换到Device Configuration Tool界面，也就是CubeMX的图形化配置视图。中间是芯片的引脚图，左侧是外设列表和时钟树，右侧是具体的配置选项。我们先进行最基础的配置。第一步是配置系统时钟。对于黑金板，外部高速时钟（HSE）通常是一颗8MHz的晶振。在左侧System Core->RCC（Reset and Clock Control）中，将High Speed Clock (HSE)从Disable改为Crystal/Ceramic Resonator。这告诉芯片，我们使用外部晶振作为时钟源。
然后点击上方Clock Configuration标签页，这里可以看到一个可视化的时钟树。我们的目标是把系统时钟（SYSCLK）配置到芯片的最高运行频率72MHz。操作顺序是：首先在时钟源选择部分，将PLL Source Mux的输入切换到HSE。然后，配置PLL倍频器：因为HSE是8MHz，我们需要将其倍频到72MHz。找到PLLMUL，将其设置为x9倍频。这样，PLL的输出就是8MHz * 9 = 72MHz。最后，在系统时钟源选择（System Clock Mux）处，选择PLLCLK作为SYSCLK的来源。此时，你应该看到SYSCLK、HCLK、PCLK1、PCLK2这几个主要时钟都变成了72MHz（PCLK1是36MHz，因为APB1总线最高频率为36MHz，系统会自动分频）。这一步是后续所有外设定时准确的基础，务必配置正确。
3. GPIO引脚配置与HAL库初始化逻辑
时钟配好了，接下来就是配置控制LED的那个GPIO引脚。回到Pinout & Configuration视图。在中间的芯片引脚图上，找到标号为PC13的引脚。用鼠标左键点击它，会弹出一个功能菜单。因为我们要用它驱动LED，所以将其功能设置为GPIO_Output。你也可以在左侧System Core->GPIO中找到PC13并进行设置，效果是一样的。
设置好功能后，右侧会自动切换到GPIO的配置面板。我们需要对PC13这个输出引脚进行参数配置，这决定了它输出电信号的特性：
- GPIO output level: 初始输出电平。设为
Low（低电平）。对于黑金板，LED通常是阴极接到PC13，阳极通过电阻接VCC（正极）。所以PC13输出低电平时，LED两端形成电压差，灯亮；输出高电平时，LED熄灭。设为低电平意味着程序一启动，LED就会先亮起来。 - GPIO mode: 引脚模式。选择
Output Push Pull（推挽输出）。这是最常用的输出模式，能明确地输出高或低电平，驱动能力强。 - GPIO Pull-up/Pull-down: 上拉/下拉电阻。选择
No pull-up and no pull-down。因为我们用推挽输出，引脚电平由内部MOS管强制拉高或拉低，不需要额外的上拉或下拉电阻。 - Maximum output speed: 最大输出速度。对于只是闪烁LED的应用，速度要求极低，选择
Low即可。这有助于降低噪声和功耗。如果后续用来驱动高速信号（如SPI时钟），则需要根据情况选择Medium或High。
配置完成后，别忘了给工程起个有意义的名称。点击上方Project Manager标签页，在Project部分可以修改Project Name。更重要的是检查Code Generator部分，确保“Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral”这个选项是勾选的，这和我们创建工程时的选择一致。最后，点击右上角的GENERATE CODE按钮。CubeIDE会根据你的图形化配置，自动生成所有底层的初始化代码，包括main.c、stm32f1xx_hal_conf.h、stm32f1xx_it.c（中断服务程序文件）以及我们单独生成的gpio.c。
代码生成后，CubeIDE会问你是否要打开工程，点击“Open Project”。现在，我们正式进入了代码编辑和编写阶段。在左侧的Project Explorer视图中，展开你的工程目录，重点看Core/Src下的main.c和gpio.c，以及Core/Inc下的main.h和gpio.h。自动生成的main.c结构非常清晰：
/* Includes */部分：包含了必要的头文件，如main.h、gpio.h。/* Private variables */：定义私有变量。/* Private function prototypes */：声明私有函数。/* USER CODE BEGIN PV */和/* USER CODE END PV */：这是用户代码区，你在这里定义的变量会被保护起来，重新生成代码时不会被覆盖。main()函数：程序入口。SystemClock_Config()函数：这就是根据我们图形化配置生成的72MHz时钟初始化函数。MX_GPIO_Init()函数：在gpio.c中定义，这里被调用，用于初始化PC13为推挽输出模式。
理解这个自动生成的框架至关重要。HAL库的初始化顺序通常是：HAL_Init()->SystemClock_Config()-> 各个外设的MX_XXX_Init()。HAL_Init()会初始化HAL库使用的滴答定时器（SysTick），为HAL_Delay()等函数提供时间基准。所以，千万不要改动这些初始化函数的调用顺序。
4. 核心代码编写与逻辑实现
现在，我们要在main()函数的无限循环（while (1)）里添加让LED闪烁的逻辑。找到main.c中/* USER CODE BEGIN WHILE */注释之后、/* USER CODE END WHILE */注释之前的位置。所有你自己的应用代码，都必须写在这些USER CODE BEGIN和USER CODE END注释对之间，这是CubeIDE为你划定的安全区，重新生成配置代码时，这里的代码会被保留。
让LED闪烁，本质上就是周期性地改变PC13引脚的电平。HAL库提供了非常直观的函数来完成这个操作。最基础的写法是使用HAL_GPIO_WritePin()函数，直接设置引脚为高或低电平：
while (1) { /* USER CODE BEGIN WHILE */ // 点亮LED (PC13输出低电平) HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_RESET); // 延时500毫秒 HAL_Delay(500); // 熄灭LED (PC13输出高电平) HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_SET); // 再延时500毫秒 HAL_Delay(500); /* USER CODE END WHILE */ }这段代码逻辑清晰：亮500ms -> 灭500ms -> 亮500ms……如此循环，形成一个周期为1秒的闪烁。HAL_Delay()函数依赖于SysTick中断，在HAL_Init()中已被初始化，它提供的是阻塞式延时，即调用这个函数时，CPU会在这里空等指定的毫秒数。对于简单的闪烁任务，这完全没问题。
但是，HAL库还提供了一个更简洁的函数HAL_GPIO_TogglePin()。它不需要你记住当前引脚是什么状态，每次调用都会将指定引脚的电平反转一次：如果原来是高，就变低；原来是低，就变高。用这个函数，代码可以简化为：
while (1) { /* USER CODE BEGIN WHILE */ // 翻转PC13引脚的电平状态 HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13); // 延时1000毫秒 HAL_Delay(1000); /* USER CODE END WHILE */ }这段代码的效果和第一段是一样的，都是1秒改变一次状态，但逻辑更简洁。Toggle（翻转）是数字电路和嵌入式编程中非常常见的操作。这里有一个细节需要注意：由于我们初始化时将PC13的默认输出电平设为了Low（在MX_GPIO_Init里配置的），所以程序一运行，LED就是亮的。第一次进入循环执行HAL_GPIO_TogglePin，会将电平翻转为High，LED熄灭，然后等待1秒。因此，你实际看到的闪烁效果是：上电常亮 -> 1秒后熄灭 -> 1秒后点亮 -> 1秒后熄灭…… 第一次亮灭的间隔是1秒，之后的亮、灭持续时间都是1秒。
如果你想调整闪烁频率，只需修改HAL_Delay()的参数。比如HAL_Delay(200)会让LED每200ms（0.2秒）改变一次状态，闪烁得更快。参数的单位是毫秒（ms），HAL_Delay(1000)就是延时1秒。
5. 代码编译、下载与硬件连接实操
代码写好了，下一步就是把它变成芯片能执行的二进制文件，并烧录进去。首先点击工具栏上的“锤子”图标（Build），或者按Ctrl+B编译工程。编译过程会在底部的“Console”窗口输出详细信息。如果代码没有语法错误，配置也正确，最后你会看到“Build Finished”的提示，以及生成的二进制文件大小信息，例如：
text data bss dec hex filename 1440 20 1572 3032 bd8 Blackpill_LED_Blink.elf这里text段是代码大小，data和bss是数据段大小。对于这个简单的程序，体积很小。
注意：如果编译报错，最常见的原因有两个。一是头文件包含错误，请检查
main.c开头是否包含了#include “main.h”，而main.h里又包含了#include “stm32f1xx_hal.h”。二是可能误删了某些自动生成的函数调用，比如MX_GPIO_Init()，确保它们在main()函数中被正确调用。
编译成功，接下来连接硬件。用Micro-USB线将黑金板连接到电脑。黑金板通常有两种USB接口：一种直接连接MCU的USB引脚（需要芯片支持USB，如F103C8），另一种是通过串口芯片（如CH340）转换。对于F103C8的黑金板，我们通常使用后者进行程序下载。连接后，电脑会识别出一个新的串口（在Windows设备管理器的“端口（COM和LPT）”下可以看到，比如COM3）。但下载程序我们不需要操作串口，而是需要让板子进入下载模式。
STM32有两种常用的下载方式：SWD（Serial Wire Debug）和串口ISP。黑金板一般会引出SWD接口（SWCLK和SWDIO两个引脚），但如果你没有ST-Link这类调试器，最简便的方法是使用串口ISP下载，也就是通过板载的USB转串口芯片（如CH340）来给主芯片烧录程序。这需要让芯片进入系统存储器启动模式。具体操作是：找到板子上的BOOT0和BOOT1（或BOOT）跳线帽或焊点。将BOOT0接高电平（3.3V），BOOT1接低电平（GND）。然后给板子重新上电（或按复位键），此时芯片就从系统存储区启动了，等待通过串口接收程序。
在STM32CubeIDE中配置下载方式。点击菜单Run -> Run Configurations...。在左侧找到你的工程名，双击或右键新建一个配置。在Main标签页，确认Project和C/C++ Application路径正确。关键在Debugger标签页：
- Debug probe: 如果你用ST-Link，就选
ST-LINK (OpenOCD)。如果用串口ISP，这里可能不需要配置（因为CubeIDE默认用OpenOCD通过SWD调试，串口ISP是另一种独立工具）。 - 实际上，对于新手，我强烈建议使用一个独立的图形化烧录工具，比如
STM32CubeProgrammer（ST官方）或者FlyMcu（针对CH340等串口下载）。以STM32CubeProgrammer为例，打开软件，在连接方式中选择UART，选择电脑识别到的对应COM口，波特率可以设高一点，比如115200。然后点击“Connect”。如果连接成功，软件会读取到芯片的ID等信息。接着，在“Download”页面，选择你刚才编译生成的.hex或.bin文件（文件在工程目录的Debug或Release文件夹下），点击“Start Programming”。烧录成功后，软件会有提示。
烧录完成后，切记：将BOOT0跳线重新接回低电平（GND），然后按一下板子的复位键。这样芯片才会从用户Flash（即我们刚才烧录程序的地方）启动。此时，你应该能看到板载的LED（通常是蓝色或绿色）开始按照你代码设定的节奏稳定地闪烁了。
6. 调试技巧与进阶思考
恭喜你，完成了第一个STM32项目！但让灯闪起来只是开始。在实际开发中，我们经常会遇到程序没按预期运行的情况。这里分享几个基础的调试心得。
首先，如果LED完全不亮，检查顺序应该是：电源 -> 硬件连接 -> 软件配置。
- 电源：确保USB线连接可靠，板子上的电源指示灯（如果有）是否亮了？可以用万用表量一下3.3V引脚是否有电压。
- 硬件连接：确认你操作的LED引脚是否正确。黑金板的用户LED绝大多数在PC13，但极个别版本或自己画的板子可能不同，一定要核对原理图。用万用表通断档，测量PC13引脚和LED焊盘是否确实连通。
- 软件配置：这是最容易出问题的地方。再检查一遍
MX_GPIO_Init()函数（在gpio.c里），看PC13的初始化模式是不是GPIO_MODE_OUTPUT_PP（推挽输出）。检查main.c的while循环里的代码是否确实被执行了？可以在HAL_Delay()前后加一句HAL_GPIO_TogglePin()来快速测试，如果LED开始高频闪烁（肉眼可见的亮灭），说明循环执行了，问题可能在延时时间太长让你误以为没反应。
其次，如果LED常亮或常灭，不闪烁。问题很可能出在while循环的逻辑上。比如，你可能不小心把HAL_GPIO_TogglePin和HAL_Delay的顺序写反了，或者HAL_Delay的参数写得太大（比如HAL_Delay(5000)是5秒，变化太慢不易察觉）。另一个常见原因是没有使能GPIOC的时钟。在HAL库中，使用任何外设（包括GPIO）前，必须先开启其时钟。不过，在我们使用CubeMX生成代码时，它已经在MX_GPIO_Init()函数内部，通过__HAL_RCC_GPIOC_CLK_ENABLE()这句代码帮我们开启了时钟。如果你是自己手写初始化代码，忘了这一步，外设是无法工作的。
掌握了基本的GPIO输出控制，你可以尝试很多有趣的扩展：
- 呼吸灯效果：不用
HAL_Delay，而是通过PWM（脉冲宽度调制）来控制LED的亮度。你需要将PC13引脚配置为PWM输出模式（比如TIMx_CHx），然后在代码中动态改变PWM的占空比。这涉及到定时器外设的配置，是进阶学习的好课题。 - 按键控制：增加一个按键，连接到另一个GPIO引脚（如PA0），并将其配置为输入模式（带上拉电阻）。在
while循环中，使用HAL_GPIO_ReadPin()函数读取按键状态，根据按键按下来改变LED的闪烁模式或开关。这里就要开始考虑按键消抖（软件延时或中断处理）的问题了。 - 脱离阻塞延时：
HAL_Delay()会阻塞CPU，意味着在延时的几百毫秒里，CPU什么都干不了。在实际项目中，这通常是不可接受的。你可以学习使用SysTick中断或者硬件定时器中断，在中断服务程序里设置一个标志位，然后在主循环中检查这个标志位来实现非阻塞的定时操作，让CPU在等待期间可以执行其他任务。
最后，关于HAL库，我想多说两句。它确实方便，但“黑盒”程度也高。作为学习者，在项目时间允许的情况下，不妨偶尔翻看一下HAL_GPIO_TogglePin()这种函数的底层实现（在stm32f1xx_hal_gpio.c文件中）。你会看到它最终是通过读写GPIOx->BSRR这个寄存器来实现的。了解这些，能让你更深刻地理解硬件是如何被驱动的，而不是仅仅停留在函数调用的层面。当你未来遇到更复杂的问题，或者需要极致优化性能时，这些底层知识会非常有用。从点灯出发，STM32的世界很大，慢慢探索吧。
