STM32F103开发入门：从CubeMX工程创建到Keil调试实战

1. 项目概述：从零搭建STM32F103的开发骨架

每次开始一个新的STM32项目，最基础也最关键的一步就是建立一个清晰、规范的工程。这就像盖房子前打地基，地基稳了，后续的代码开发、功能调试才能顺畅。对于STM32F103这类经典的Cortex-M3内核芯片，使用ST官方推出的图形化配置工具STM32CubeMX来初始化工程，再配合Keil MDK进行代码编写和调试，是目前最主流、最高效的开发流程。这个流程不仅大大减少了手动配置寄存器、编写底层驱动的时间，更重要的是，它通过HAL（硬件抽象层）库统一了编程接口，让开发者能更专注于应用逻辑本身。今天，我就以一个纯粹的“新建工程”为例，带你走一遍这个流程，并分享一些在配置过程中容易踩坑的细节和我的个人心得，确保你搭建的这个“地基”既标准又牢固。

2. 环境准备与工具链解析

在动手创建工程之前，确保你的“武器库”已经准备齐全。这里不仅仅是把软件装上就行，理解每个工具的作用和它们之间的协作关系，能让你在后续开发中事半功倍。

2.1 核心工具安装与要点

你需要准备三个核心软件：STM32CubeMX、Keil MDK-ARM（或IAR等IDE）、以及对应的STM32F1系列器件支持包。

STM32CubeMX：这是工程的起点。它是一个图形化的芯片配置工具，你可以通过它来配置时钟树、引脚功能、外设参数（如UART的波特率、ADC的采样时间等），并一键生成初始化代码框架。它的最大价值在于可视化，避免了手动查阅数据手册计算时钟分频系数、查找引脚复用功能的繁琐过程。

注意：建议从ST官网下载最新稳定版本。安装路径不要包含中文或特殊字符，这是一个老生常谈但总有人忽视的问题，可能导致软件运行异常或生成代码路径错误。

Keil MDK-ARM：这是我们的集成开发环境（IDE），用于编写应用代码、编译工程、下载程序到芯片以及在线调试。对于STM32F103，你需要安装MDK-ARM版本，而不是用于51单片机的Keil C51。

器件支持包（Device Family Pack, DFP）：这是连接CubeMX和Keil的桥梁。CubeMX生成的工程是基于特定系列的HAL库的，而Keil需要知道芯片的具体内存映射、外设地址等信息才能正确编译和调试。这个包通常包含了芯片的启动文件、链接脚本、Flash编程算法等。你可以在Keil的包管理器（Pack Installer）中在线安装，也可以从官网下载后离线安装。

我的实操心得是，先安装Keil MDK，然后通过其包管理器安装好STM32F1系列的DFP。接着再安装CubeMX，这样CubeMX在生成工程时，就能自动识别到已安装的Keil工具链，配置起来更顺畅。

2.2 理解HAL库与标准库的选择

在CubeMX生成代码时，你会面临一个选择：使用HAL库还是标准外设库（Standard Peripheral Library, SPL）。对于STM32F103这类有历史的产品，两种库都支持，但趋势非常明确。

标准外设库（SPL）：更接近寄存器操作，代码效率高，体积相对小，是早期STM32开发的主流。但它已经停止更新，ST官方不再维护，且不同芯片系列的库函数接口不完全统一。

硬件抽象层库（HAL）：ST目前主推且持续更新的库。它的设计目标是跨STM32系列通用，提供了更高级的API（如阻塞式、中断式、DMA式传输），降低了学习成本和移植难度。代价是代码体积稍大，执行效率相比直接操作寄存器或SPL略有损耗。

对于新手和大多数应用项目，我强烈建议直接使用HAL库。其优势在于：第一，官方持续维护，Bug修复和新功能支持有保障；第二，统一的编程模型让学习一次就能应用到其他STM32芯片上；第三，CubeMX对其支持最为完善，能自动生成绝大部分初始化代码。只有在极端追求代码体积或执行效率的特定场景（比如Bootloader），才需要考虑使用SPL或直接操作寄存器。本次工程创建我们将基于HAL库进行。

3. 使用CubeMX进行工程初始化详解

打开CubeMX，点击“New Project”，我们就正式进入了工程配置的核心环节。这个过程就像给芯片“画蓝图”，每一步配置都决定了最终生成代码的形态。

3.1 芯片选型与工程基础设置

在芯片选择器里，你可以直接搜索“STM32F103”，会看到一系列型号，如F103C8T6（中容量）、F103RCT6（大容量）等。这里务必根据你手头实际开发板的主控芯片型号进行选择，因为不同型号的Flash、RAM大小、外设数量可能不同。选中后，中间会显示芯片的引脚图。

接下来进入“Project Manager”标签页，这是配置工程的“元信息”：

• Project Name：给你的工程起个名字，例如“STM32F103_Test”。
• Project Location：选择工程存放路径。强烈建议为路径单独建立一个英文目录，避免任何中文。
• Toolchain / IDE：选择“MDK-ARM V5”（如果你用的是Keil5）。CubeMX会根据这个选择生成对应的Keil工程文件（.uvprojx）。
• 在“Code Generator”区域，有几个关键选项：
  • Copy all used libraries into the project folder：勾选。这会将HAL库等必要文件复制到你的工程目录中，这样工程就是完全独立的，移动或分享时不会因库路径问题而编译失败。
  • Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral：勾选。这会为每个你配置的外设（如GPIO、USART）单独生成一对初始化文件（如gpio.c/h,usart.c/h），而不是全部堆在main.c里。这样代码结构更清晰，模块化更好。
  • Backup previously generated files when re-generating：建议勾选。这样在重新通过CubeMX生成代码时，它会备份你之前修改过的文件，防止你的应用代码被意外覆盖。

3.2 核心系统配置：时钟与调试接口

这是最容易出错，也最影响系统稳定性的部分。

1. 时钟树（Clock Configuration）配置： STM32F103的时钟源可以是内部RC振荡器（HSI，8MHz）或外部晶振（HSE，通常8MHz）。使用外部晶振能获得更精确的时钟，特别是需要用到USB、高精度定时等场合。在“Pinout & Configuration”标签页的“System Core”里，先找到“RCC”（复位和时钟控制）。

• 如果你的板子上接了外部高速晶振（通常接在OSC_IN和OSC_OUT引脚，如PD0和PD1），则在“High Speed Clock (HSE)”选择“Crystal/Ceramic Resonator”。
• 如果没有，就选择“Disable”，使用内部HSI。

然后切换到“Clock Configuration”标签页。这里可以看到一个可视化的时钟树。我们的目标通常是将系统时钟（SYSCLK）配置到芯片允许的最高频率（对于F103，一般是72MHz），以获取最佳性能。一个常见的配置路径是：选择HSE作为PLL源，将HSE（8MHz）通过PLL倍频9倍，得到72MHz，然后将其选为SYSCLK。APB1总线时钟（PCLK1）最高为36MHz，APB2总线时钟（PCLK2）最高为72MHz。配置时，你直接在图中的输入框输入目标频率，CubeMX会自动计算并设置好分频系数，非常方便。配置完成后，时钟树上各节点的频率会以不同颜色显示（灰色表示未使用，橙色表示已配置但可能超频，绿色表示OK）。

2. 调试接口配置： 在“System Core” -> “SYS”中，需要配置“Debug”选项。默认是“No Debug”，这会导致下载程序后无法进行在线调试（如单步、断点）。根据你使用的调试器选择：

• 如果使用ST-LINK，选择“Serial Wire”。
• 如果使用J-LINK，也通常选择“Serial Wire”（即SWD模式）。
• 如果使用标准的JTAG接口，则选择“JTAG (4 pins)”。 选择“Serial Wire”是最常用的，它只占用SWDIO和SWCLK两个引脚，节省引脚资源。这个配置必须在生成代码前设置好，否则生成代码后，相应的调试引脚（PA13, PA14）可能被初始化为普通GPIO，导致无法连接调试器。

3.3 外设功能引脚配置示例

假设我们要为这个基础工程添加一个LED闪烁和一个串口打印功能，这是两个最经典的外设。

1. 配置一个LED引脚（以PC13为例，常见于最小系统板）：

• 在芯片引脚图上找到PC13，左键点击它。
• 在弹出的功能菜单中选择“GPIO_Output”。这个引脚就被配置为推挽输出模式了。
• 在左侧“System Core” -> “GPIO”中，点击刚配置的PC13，可以在右侧设置其初始输出电平（低电平点亮LED则设为High，高电平点亮则设为Low）、输出模式（推挽输出）、上下拉（根据电路选择）、速度（低速即可）等。这里我们可以将“GPIO output level”初始化为“High”（假设LED阴极接PC13，阳极接VCC，则高电平时LED灭）。

2. 配置一个串口（以USART1为例，对应PA9为TX，PA10为RX）：

• 在引脚图上找到PA9，选择“USART1_TX”；找到PA10，选择“USART1_RX”。
• 在左侧“Connectivity” -> “USART1”中，进行参数配置。
• “Mode”选择“Asynchronous”（异步通信）。
• “Basic Parameters”中设置波特率（如115200 Bits/s）、字长（8位）、停止位（1位）、校验位（None）、硬件流控制（Disable）。
• 如果需要使用串口中断或DMA，可以在“NVIC Settings”或“DMA Settings”子标签页中使能。

配置完这些，一个具备最小系统、调试接口、LED控制和串口通信能力的工程框架就定义好了。CubeMX的强大之处在于，所有这些图形化的操作，最终都会转化为对HAL库函数的调用，并生成到main.c的MX_GPIO_Init()和MX_USART1_UART_Init()等函数中。

4. 生成代码与Keil工程导入

配置完成后，点击CubeMX右上角的“GENERATE CODE”按钮。软件会检查配置是否有冲突，然后在你指定的工程目录下生成完整的代码框架和Keil工程文件。

4.1 生成代码的结构解析

打开工程目录，你会看到CubeMX生成了一系列文件和文件夹：

• Core/：这是核心目录。
  • Inc/和Src/：分别存放头文件和源文件。你的主要应用代码将在这里编写，特别是main.c,main.h。
  • Src/下的stm32f1xx_it.c：这是中断服务函数文件，所有外设的中断服务程序（如USART1中断、定时器中断）的骨架都在这里。
• Drivers/：存放STM32F1xx HAL驱动库、CMSIS（Cortex微控制器软件接口标准）等。
• MDK-ARM/：存放Keil的工程文件（.uvprojx）和一些链接脚本。
• STM32F103C8Tx_FLASH.ld（或类似）：GCC编译器的链接脚本（如果使用其他IDE）。

重点看Core/Src/main.c，CubeMX已经为我们搭建好了程序的骨架：

1. HAL_Init()：初始化HAL库。
2. SystemClock_Config()：这就是根据我们图形化配置的时钟树生成的函数，里面包含了所有时钟设置代码。
3. 各个外设的初始化函数，如MX_GPIO_Init(),MX_USART1_UART_Init()。
4. 最后进入while (1)主循环。

4.2 在Keil中打开与基础设置

双击MDK-ARM目录下的.uvprojx文件，用Keil打开工程。首次打开时，Keil可能会提示安装或确认器件支持包，确保其指向正确的STM32F103型号。

有几个关键设置需要检查：

• 目标选项（Target Options）：点击魔术棒图标。
  • “Device”标签页确认芯片型号正确。
  • “Output”标签页，勾选“Create HEX File”，以便生成可以烧录的HEX文件。
  • “C/C++”标签页，在“Define”中应该有“USE_HAL_DRIVER, STM32F103xB”这样的宏定义，这是使用HAL库所必需的。在“Include Paths”中，应该已经包含了Core/Inc、Drivers/STM32F1xx_HAL_Driver/Inc等路径。
  • “Debug”标签页，选择你使用的调试器（如ST-Link Debugger），并点击“Settings”确认SWD接口和速度设置正确。
  • “Utilities”标签页，设置好编程算法（通常是STM32F10x Med-density Flash）。

5. 编写第一个应用：LED闪烁与串口通信

现在，我们开始在生成的骨架里添加“血肉”，实现具体的功能。我们就在main.c的while (1)主循环里添加代码。

5.1 实现LED闪烁

在main.c的/* USER CODE BEGIN 2 */和/* USER CODE END 2 */注释对之间（这是CubeMX为用户代码保留的安全区域，重新生成代码时不会被覆盖），我们可以定义一些变量或执行初始操作。但简单的LED闪烁可以直接写在主循环里。

找到/* USER CODE BEGIN WHILE */，在它之后，while (1)循环内部添加如下代码：

/* USER CODE BEGIN WHILE */ while (1) { // 将PC13引脚电平翻转（即取反） HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13); // 延时大约500毫秒 HAL_Delay(500); /* USER CODE END WHILE */ /* USER CODE BEGIN 3 */ } /* USER CODE END 3 */

HAL_GPIO_TogglePin是HAL库提供的GPIO电平翻转函数。HAL_Delay是一个基于系统滴答定时器（SysTick）实现的毫秒级阻塞延时函数。编译下载后，你应该能看到连接到PC13的LED开始以1秒为周期闪烁。

5.2 实现串口打印

我们希望通过串口1（USART1）发送数据到电脑，以便调试。首先，确保在CubeMX中已正确配置USART1。

同样，在/* USER CODE BEGIN 2 */区域，我们可以先尝试发送一个启动信息。但更常见的做法是重定向printf函数到串口，这样就能直接使用printf进行格式化输出了，非常方便。

步骤一：重定向printf在main.c文件中，包含stdio.h头文件，然后添加以下代码重写_write函数（对于ARMCC编译器）：

/* USER CODE BEGIN Includes */ #include <stdio.h> /* USER CODE END Includes */ ... (其他代码) /* USER CODE BEGIN 4 */ // 重定向printf到串口1 #ifdef __GNUC__ #define PUTCHAR_PROTOTYPE int __io_putchar(int ch) #else #define PUTCHAR_PROTOTYPE int fputc(int ch, FILE *f) #endif PUTCHAR_PROTOTYPE { HAL_UART_Transmit(&huart1, (uint8_t *)&ch, 1, 0xFFFF); // 阻塞式发送一个字符 return ch; } /* USER CODE END 4 */

步骤二：使用printf打印现在，你就可以在代码的任何地方使用printf了。例如，在LED闪烁的循环里加上打印：

while (1) { HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13); printf("LED Toggled! System Tick: %lu\r\n", HAL_GetTick()); // 打印信息并获取系统运行时间 HAL_Delay(500); }

步骤三：在Keil中开启微库（MicroLIB）为了让这个重定向生效，需要在Keil的“Target Options” -> “Target”标签页中，勾选“Use MicroLIB”。MicroLIB是一个针对嵌入式系统优化的精简版C标准库，它支持printf重定向且占用资源更少。

编译工程，下载到芯片，然后用串口调试助手（如XCOM、Putty等）连接到开发板的串口1（注意TTL电平，可能需要USB转TTL模块），设置好波特率（115200），你就能看到循环打印的信息了。

6. 编译、下载与调试实战

代码写好了，接下来就是把它变成芯片里运行的程序。

6.1 编译与常见错误解决

点击Keil工具栏的“Rebuild”按钮（通常是三个红色箭头图标）进行编译。如果一切配置正确，你会在“Build Output”窗口看到“0 Error(s), 0 Warning(s)”的提示。

常见的编译错误及解决思路：

• undefined symbol错误：通常是链接错误，意味着某个函数或变量只有声明没有定义。检查是否包含了必要的源文件（.c）到工程中，或者是否在头文件中正确声明了函数。对于HAL库函数，确保在main.c里包含了stm32f1xx_hal.h以及具体外设的头文件（如stm32f1xx_hal_uart.h），CubeMX通常会自动做好这些。
• cannot open source input file错误：头文件路径错误。检查“Target Options” -> “C/C++” -> “Include Paths”是否包含了所有必要的目录。
• 程序大小超限：如果芯片是STM32F103C8T6（64KB Flash），而程序编译后显示超过64KB，就需要优化了。可以尝试将编译器优化等级提高到“-O2”（在“C/C++”标签页的“Optimization”中设置），或者检查代码中是否包含了不必要的大型数组或库。

6.2 程序下载与调试

确保调试器（如ST-LINK）已正确连接到开发板和电脑。

• 下载：点击Keil的“Load”按钮（通常是向下箭头图标），Keil会自动编译（如果代码有改动）、连接芯片、擦除Flash、编程、校验，最后复位运行。看到“Flash Load finished at…”的提示即表示下载成功。
• 调试：点击“Debug”按钮（或Ctrl+F5）进入调试模式。界面会发生变化，出现反汇编窗口、寄存器窗口、变量观察窗口等。
  • 设置断点：在代码行号前点击，可以设置/取消断点（红色圆点）。程序运行到断点处会暂停。
  • 单步执行：使用F10（Step Over）逐过程执行，F11（Step Into）逐语句执行（会进入函数内部）。
  • 查看变量：在“Watch”窗口可以添加想要观察的变量名，实时查看其值。
  • 查看外设寄存器：在“Peripherals”菜单中，可以选择查看具体外设（如GPIO、USART）的寄存器状态，这对于调试硬件配置非常有用。

第一次调试时，建议在main函数的开始和while(1)循环内设置断点，观察程序是否按预期执行。同时打开串口调试助手，观察printf输出是否正常。

7. 工程管理进阶与避坑指南

一个基础的工程跑起来后，为了项目的长期健康，我们还需要考虑工程结构和管理问题。

7.1 代码与配置分离的最佳实践

CubeMX生成的代码中，用户代码被放置在/* USER CODE BEGIN */和/* USER CODE END */注释对之间。绝对不要在注释对之外、CubeMX生成的代码区域内修改代码（例如直接修改MX_GPIO_Init函数体），因为下次你通过CubeMX修改配置并重新生成代码时，这些修改会被无情地覆盖。

正确的做法是：

1. 将应用逻辑模块化：对于复杂的应用，不要在main.c里堆砌所有代码。应该在Core/Src和Core/Inc下创建你自己的.c和.h文件，例如led.c/h,uart_comm.c/h，将相关功能封装成函数。然后在main.c中包含这些头文件并调用函数。
2. 使用CubeMX回调函数：HAL库为很多外设提供了回调函数机制。例如，当串口接收完成、定时器溢出时，会调用你在main.c中弱定义（Weak）的回调函数。你可以在/* USER CODE BEGIN 4 */区域重写这些回调函数，将事件处理逻辑放在这里。这样既实现了功能，又保证了代码在重新生成时的安全。
3. 管理全局变量和句柄：CubeMX会为每个初始化的外设生成一个实例句柄（如UART_HandleTypeDef huart1）。这些句柄是全局变量，你可以在自己的模块中通过extern声明来使用它们。对于你自己的全局变量，建议在main.h或单独的头文件中用extern声明，在某个.c文件中定义。

7.2 常见问题排查与解决实录

即使按照步骤操作，新手也常会遇到一些问题。这里记录几个高频问题：

• 问题一：程序下载后无反应，LED不闪，串口无输出。

  • 排查思路：
    1. 检查供电和复位：确保开发板供电正常，复位引脚没有一直被拉低。
    2. 检查启动模式：STM32的BOOT0和BOOT1引脚决定了启动方式（从主Flash、系统存储器或SRAM启动）。确保它们被正确设置为从主Flash启动（通常BOOT0接低电平）。
    3. 检查时钟配置：这是最常见的原因。回头仔细检查CubeMX中的时钟树配置，特别是PLL倍频系数和系统时钟源选择是否正确。可以尝试先用默认的内部HSI（8MHz）时钟源，排除外部晶振不起振的问题。
    4. 检查调试接口配置：确认在CubeMX的SYS中正确选择了“Serial Wire”。如果选错，可能无法下载程序，或者下载后芯片被意外锁定。
    5. 简化测试：注释掉所有功能代码，只在主循环里写一个最简单的LED翻转和延时，排除是外设配置或printf重定向导致的问题。

• 问题二：串口能发送数据，但电脑端接收全是乱码。

  • 排查思路：
    1. 波特率不匹配：这是首要怀疑对象。确保代码中设置的波特率（如115200）和串口调试助手设置的波特率完全一致。
    2. 时钟频率错误：如果系统时钟（SYSCLK）配置的不是72MHz，而是其他频率（如默认的8MHz HSI），那么根据72MHz计算出的串口分频系数就会错误，导致实际波特率偏差巨大。务必确保系统时钟频率与CubeMX中时钟树显示的目标频率一致。
    3. 数据位、停止位、校验位设置不匹配。

• 问题三：重新用CubeMX生成代码后，自己写的代码不见了。

  • 原因与解决：你肯定把代码写在了/* USER CODE BEGIN */和/* USER CODE END */注释对之外。CubeMX只保护这对注释之间的内容。立即检查你的代码位置，并移入安全区域。养成习惯，只在指定区域或自己新建的文件中编写代码。

• 问题四：编译时提示HAL_UART_Transmit等函数未定义。

  • 排查思路：
    1. 检查是否包含了对应的HAL库头文件（stm32f1xx_hal_uart.h）。
    2. 检查在main.c中是否正确定义了串口句柄huart1（CubeMX应已生成）。
    3. 检查Keil工程中是否包含了HAL库的源文件（stm32f1xx_hal_uart.c）。通常CubeMX生成的工程已经链接好了，但如果手动管理工程，可能会遗漏。

建立一个稳定的工程模板是后续所有开发的基础。花时间理解CubeMX每个配置项的意义，掌握HAL库的基本调用方法，并养成良好的代码管理习惯，这些投入在项目越复杂时，回报就越明显。当你熟悉了这个流程后，新建一个工程并实现基础功能，真的只需要几分钟。