STM32矩阵按键驱动：从CubeMX配置到状态机扫描的完整实现

简介：本资源是一份面向嵌入式初学者与STM32进阶开发者的完整实践项目，聚焦于使用HAL库与CubeMX实现STM32F103RCT6对4×4矩阵按键的可靠识别与控制，解决多按键场景下GPIO资源受限、消抖处理、扫描逻辑与时序控制等典型工程问题。压缩包共183个文件，包含25个核心C源码（含HAL外设驱动与按键扫描逻辑）、52个头文件（.h）、29个编译中间文件（.o/.d）及Keil工程必备配置（.uvprojx/.ioc/.axf/.hex等），完整覆盖从CubeMX图形化配置、GPIO初始化、定时扫描调度到中断响应与按键状态机实现的全链路代码结构，包体大小为9.49MB。已有1379人学习下载，资源中已集成去抖延时、按键编码映射、行列电平切换逻辑及可复用的扫描函数框架，便于读者直接移植、调试验证或拓展为键盘输入模块。

1. 项目概述：从独立按键到矩阵按键的必然选择

在嵌入式开发，尤其是基于STM32这类MCU的项目中，人机交互是基础且关键的一环。按键作为最经典的输入设备，其实现方式直接关系到系统的资源占用和设计复杂度。很多新手朋友都是从独立按键开始学起的，每个按键独占一个GPIO引脚，代码简单直观。但当按键数量增加到8个、16个甚至更多时，你会发现STM32的GPIO资源突然变得捉襟见肘，PCB布线也变得异常复杂。这时，矩阵按键（Matrix Keypad）就成了一个优雅且高效的解决方案。

我这次分享的项目，就是基于STM32F103RCT6这款经典的“增强型”MCU，使用STM32CubeMX进行图形化配置，结合HAL库，实现一个4x4矩阵按键的稳定扫描驱动。选择扫描法，是因为它在资源消耗、响应速度和代码复杂度之间取得了很好的平衡，非常适合大多数中低端应用场景。你可能会问，为什么不用中断法？对于矩阵按键，中断法实现起来更复杂，需要额外的二极管来防止“鬼影”，硬件成本更高，而扫描法在软件上稍作处理就能满足绝大多数需求，性价比突出。

这个方案的核心价值在于，它提供了一套从硬件连接到软件驱动、从CubeMX配置到代码实现的完整链路。无论你是正在做毕业设计的学生，还是需要为产品增加按键输入功能的工程师，都可以直接“抄作业”，快速搭建起一个可靠的16键输入系统。接下来，我会把整个过程中的设计思路、配置细节、代码实现以及我踩过的坑，毫无保留地分享给你。

2. 硬件设计与核心原理拆解

2.1 矩阵按键的硬件连接与扫描法原理

首先，我们得搞清楚4x4矩阵按键在硬件上是怎么一回事。它本质上是用8根线（4行+4列）来管理16个按键，通过行列交叉点来定位每一个按键。硬件连接上，通常将4个行线设置为输出模式，4个列线设置为输入模式（带上拉或下拉）。

扫描法的工作原理，可以想象成在一个网格上找人。我们让“行”作为主动扫描方。程序依次将每一行输出低电平（其余行输出高电平），然后去读取所有列线的状态。如果某一列读到了低电平，那就说明当前被拉低的这一行，与读到低电平的这一列，它们的交叉点处的按键被按下了。举个例子，如果我们把第2行拉低，然后读到第3列是低电平，那么就可以确定是S(2,3)这个按键被按下。

这里有一个关键点：为什么列线需要配置为上拉输入？这是为了确保在没有任何按键按下时，列线能被稳定地拉至高电平，形成一个明确的“无效”状态。当某一行被拉低，且该行某列的按键被按下时，这个低电平才会通过按键被“传递”到对应的列线上，从而被MCU读取到。如果配置为浮空输入，引脚电平不确定，极易受到干扰导致误触发。

2.2 STM32F103RCT6的GPIO资源规划

STM32F103RCT6拥有51个GPIO口，资源对于4x4矩阵按键来说绰绰有余。选择哪8个GPIO口，有一定的讲究。我的建议遵循以下原则，这也是很多实际项目中的经验：

1. 尽量集中在一个GPIO端口：例如全部使用GPIOA或GPIOB。这样做的好处是，在软件扫描时，可以一次性读取整个端口的值，然后通过位掩码来提取列线状态，效率远高于逐个引脚读取。例如，将4根列线连接到PA0~PA3，那么一次HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_All)再与0x000F进行与操作，就能得到所有列的状态。
2. 避开特殊功能引脚：比如晶振引脚（PC14/PC15）、调试接口（PA13/JTMS, PA14/JTCK, PA15/JTDI, PB3/JTDO, PB4/NJTRST）。虽然它们也可以复用为普通IO，但通常会带来不必要的麻烦，尤其是在调试阶段。
3. 考虑PCB布局便利性：尽量选择位置相邻的引脚，可以减少PCB走线的复杂度。

基于以上原则，我本次项目的引脚分配如下：

• 行线（输出）：PB12, PB13, PB14, PB15
• 列线（输入上拉）：PB0, PB1, PB2, PB3

这样，行线和列线都集中在GPIOB口，非常规整。PB0~PB3作为列输入，PB12~PB15作为行输出。

注意：在CubeMX中配置PB3时需要注意，它的默认复用功能是JTDO。如果你要用作普通GPIO，需要在Pinout & Configuration标签页的System Core->SYS里，将Debug选项改为Serial Wire。这样JTAG-DP接口会被禁用，释放出PA15、PB3、PB4等引脚作为普通IO使用，否则这些引脚无法正常控制。

3. 使用STM32CubeMX进行工程配置

3.1 创建工程与时钟树配置

打开CubeMX，选择STM32F103RCT6。首先配置时钟，这是整个系统稳定运行的基石。对于F103系列，我们通常使用外部高速时钟（HSE）。

1. 在Pinout & Configuration标签页，进入RCC配置。将High Speed Clock (HSE)设置为Crystal/Ceramic Resonator。
2. 切换到Clock Configuration标签页。你会看到一个非常直观的时钟树图。我们的目标是让系统主时钟（SYSCLK）达到72MHz，这是F103系列的最高频率。
   • 首先，在HSE框内输入8（假设你用的是8MHz晶振）。
   • 然后，将PLL Source Mux选择为HSE。
   • 接着，配置PLLMUL为x9倍频。这样PLL输出就是8MHz * 9 = 72MHz。
   • 最后，将SYSCLK的来源选择为PLLCLK。
   • AHB、APB1、APB2的预分频器可以保持默认（AHB不分频为72MHz，APB1二分频为36MHz，APB2不分频为72MHz）。注意APB1总线上的外设（如定时器2-7，USART2-5等）最高时钟是36MHz。
3. 检查HCLK是否显示为72MHz，确认无误后，时钟就配置完成了。

3.2 GPIO引脚详细配置

回到Pinout & Configuration标签页，找到左侧的GPIO选项。

1. 配置列线（输入上拉）：

   • 点击芯片图上PB0、PB1、PB2、PB3。
   • 在右侧的GPIO Mode and Configuration中，将GPIO mode设置为Input mode。
   • 将GPIO Pull-up/Pull-down设置为Pull-up。这是关键一步，为列线提供默认的高电平。
   • User Label可以分别命名为KEY_COL0,KEY_COL1等，方便代码阅读。

2. 配置行线（推挽输出）：

   • 点击芯片图上PB12、PB13、PB14、PB15。
   • 将GPIO mode设置为Output Push Pull。
   • GPIO Pull-up/Pull-down设置为No pull-up and no pull-down。
   • GPIO output level初始设置为High。因为我们的扫描逻辑是“拉低某一行”，所以初始状态所有行都应为高电平。
   • Maximum output speed对于按键扫描来说，Low速度就足够了，有助于降低噪声和功耗。可以设置为Low。
   • 同样，给它们加上User Label，如KEY_ROW0。

3.3 生成工程代码

点击Project Manager标签页。

1. Project选项卡：设置工程名称、存储路径，选择Toolchain / IDE（如MDK-ARM V5）。
2. Code Generator选项卡：这里有几个重要设置：
   • Generated files: 勾选Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral。这会把每个外设的初始化代码放在独立的文件里，结构更清晰。
   • HAL Settings: 建议勾选Enable Full Assert在开发阶段，有助于发现参数错误。发布时可以关闭。
   • Generated Function Calls: 选择Do not generate the main()，因为我们通常会在main.c里写自己的主循环。
3. 点击右上角的GENERATE CODE，生成工程代码。用你熟悉的IDE（如Keil MDK）打开工程。

4. 矩阵按键驱动代码实现

4.1 按键扫描状态机实现

直接在main.c的while(1)循环里写扫描逻辑虽然简单，但不是一个好习惯。更好的做法是将按键驱动模块化。我们在Src文件夹下新建一个keypad.c和keypad.h文件。

首先，在keypad.h中定义一些常量和结构体：

#ifndef __KEYPAD_H #define __KEYPAD_H #include "main.h" // 包含HAL库和GPIO定义 #define KEYPAD_ROWS 4 #define KEYPAD_COLS 4 #define KEY_DEBOUNCE_TIME_MS 20 // 消抖时间 // 假设按键值定义为0-15，或者根据你的需求定义字符‘0’-‘F’， ‘1’-‘16’等 typedef enum { KEY_1 = 0, KEY_2, KEY_3, KEY_A, KEY_4, KEY_5, KEY_6, KEY_B, KEY_7, KEY_8, KEY_9, KEY_C, KEY_STAR, KEY_0, KEY_HASH, KEY_D, KEY_NONE = 0xFF // 无按键按下 } Keypad_Key_t; // 按键事件类型 typedef enum { KEY_EVENT_NONE = 0, KEY_EVENT_PRESSED, KEY_EVENT_RELEASED, KEY_EVENT_LONG_PRESS // 可选，支持长按 } Keypad_Event_t; // 按键状态结构体 typedef struct { Keypad_Key_t current_key; // 当前物理按键 Keypad_Event_t event; // 当前事件 uint32_t press_tick; // 按下时刻的tick，用于长按计时 } Keypad_State_t; void KEYPAD_Init(void); void KEYPAD_Scan(void); Keypad_State_t KEYPAD_GetState(void); #endif

接下来是核心的keypad.c文件。我们实现一个带消抖的状态机扫描：

#include "keypad.h" // 行线引脚定义 static const uint16_t row_pins[KEYPAD_ROWS] = {KEY_ROW0_Pin, KEY_ROW1_Pin, KEY_ROW2_Pin, KEY_ROW3_Pin}; static GPIO_TypeDef* row_ports[KEYPAD_ROWS] = {KEY_ROW0_GPIO_Port, KEY_ROW1_GPIO_Port, KEY_ROW2_GPIO_Port, KEY_ROW3_GPIO_Port}; // 列线引脚定义 static const uint16_t col_pins[KEYPAD_COLS] = {KEY_COL0_Pin, KEY_COL1_Pin, KEY_COL2_Pin, KEY_COL3_Pin}; static GPIO_TypeDef* col_ports[KEYPAD_COLS] = {KEY_COL0_GPIO_Port, KEY_COL1_GPIO_Port, KEY_COL2_GPIO_Port, KEY_COL3_GPIO_Port}; // 按键映射表，根据你的键盘布局定义 static const Keypad_Key_t keymap[KEYPAD_ROWS][KEYPAD_COLS] = { {KEY_1, KEY_2, KEY_3, KEY_A}, {KEY_4, KEY_5, KEY_6, KEY_B}, {KEY_7, KEY_8, KEY_9, KEY_C}, {KEY_STAR, KEY_0, KEY_HASH, KEY_D} }; static Keypad_State_t key_state = {KEY_NONE, KEY_EVENT_NONE, 0}; static uint32_t last_scan_tick = 0; static Keypad_Key_t last_raw_key = KEY_NONE; // 用于消抖的临时变量 static uint32_t debounce_start_tick = 0; static uint8_t debouncing = 0; void KEYPAD_Init(void) { // 初始化所有行线为高电平（无按键按下） for(int i = 0; i < KEYPAD_ROWS; i++) { HAL_GPIO_WritePin(row_ports[i], row_pins[i], GPIO_PIN_SET); } } void KEYPAD_Scan(void) { uint32_t current_tick = HAL_GetTick(); // 控制扫描频率，例如每10ms扫描一次，避免过于频繁占用CPU if(current_tick - last_scan_tick < 10) { return; } last_scan_tick = current_tick; Keypad_Key_t detected_key = KEY_NONE; // 扫描每一行 for(uint8_t row = 0; row < KEYPAD_ROWS; row++) { // 将当前行拉低 HAL_GPIO_WritePin(row_ports[row], row_pins[row], GPIO_PIN_RESET); // 短暂延时，等待电平稳定（对于72MHz主频，1-2us足矣，这里用HAL_Delay不合适，可以用空循环） for(volatile int i=0; i<10; i++); // 简单延时 // 读取所有列 for(uint8_t col = 0; col < KEYPAD_COLS; col++) { if(HAL_GPIO_ReadPin(col_ports[col], col_pins[col]) == GPIO_PIN_RESET) { // 发现按键按下 detected_key = keymap[row][col]; break; // 一次只处理一个按键（单键按下），如需多键需修改逻辑 } } // 恢复当前行为高电平 HAL_GPIO_WritePin(row_ports[row], row_pins[row], GPIO_PIN_SET); // 恢复后也需要短暂延时，防止相邻行扫描干扰 for(volatile int i=0; i<10; i++); if(detected_key != KEY_NONE) { break; // 找到按键，跳出行扫描循环 } } // 消抖状态机处理 if(detected_key != last_raw_key) { // 按键状态发生变化，开始消抖计时 last_raw_key = detected_key; debounce_start_tick = current_tick; debouncing = 1; } else if(debouncing) { // 状态稳定，检查是否达到消抖时间 if(current_tick - debounce_start_tick >= KEY_DEBOUNCE_TIME_MS) { debouncing = 0; // 确定最终按键事件 if(detected_key != KEY_NONE && key_state.current_key == KEY_NONE) { // 新的按键按下 key_state.current_key = detected_key; key_state.event = KEY_EVENT_PRESSED; key_state.press_tick = current_tick; } else if(detected_key == KEY_NONE && key_state.current_key != KEY_NONE) { // 之前的按键释放 key_state.event = KEY_EVENT_RELEASED; // 这里可以添加快键值返回逻辑，比如在释放时才返回键值 // key_state.current_key = KEY_NONE; // 可以在GetState后清除 } } } // 长按检测（可选） if(key_state.current_key != KEY_NONE && key_state.event == KEY_EVENT_PRESSED) { if(current_tick - key_state.press_tick > 1000) { // 长按1秒 key_state.event = KEY_EVENT_LONG_PRESS; } } } Keypad_State_t KEYPAD_GetState(void) { Keypad_State_t ret_state = key_state; // 获取状态后，如果是PRESSED或LONG_PRESS事件，不清除current_key，等待RELEASE // 如果是RELEASE事件，则清空状态 if(key_state.event == KEY_EVENT_RELEASED) { key_state.current_key = KEY_NONE; key_state.event = KEY_EVENT_NONE; } else if(key_state.event == KEY_EVENT_LONG_PRESS) { // 长按事件通常只触发一次，触发后可以将事件重置，但保持current_key key_state.event = KEY_EVENT_NONE; } // 注意：PRESSED事件在第一次GetState后也应重置，避免重复触发 else if(key_state.event == KEY_EVENT_PRESSED) { key_state.event = KEY_EVENT_NONE; } return ret_state; }

4.2 在主循环中集成与调用

现在，我们在main.c中集成这个按键驱动模块。

/* 在main.c的USER CODE BEGIN Includes区域添加 */ #include "keypad.h" /* 在main.c的USER CODE BEGIN 2区域添加 */ KEYPAD_Init(); /* 在main.c的while(1)循环中，USER CODE BEGIN WHILE区域添加 */ while (1) { /* USER CODE END WHILE */ /* USER CODE BEGIN 3 */ // 1. 执行按键扫描 KEYPAD_Scan(); // 2. 获取按键状态 Keypad_State_t key_status = KEYPAD_GetState(); // 3. 处理按键事件 switch(key_status.event) { case KEY_EVENT_PRESSED: // 短按按下事件，可以在这里处理，或者等释放再处理 // printf("Key Pressed: %d\r\n", key_status.current_key); break; case KEY_EVENT_RELEASED: // 按键释放事件，这是最常用的触发点，可以有效避免连击 printf("Key Released: %d\r\n", key_status.current_key); // 根据key_status.current_key执行不同功能 handle_key_action(key_status.current_key); break; case KEY_EVENT_LONG_PRESS: printf("Key Long Pressed: %d\r\n", key_status.current_key); // 处理长按功能，如进入设置菜单 break; default: break; } HAL_Delay(1); // 主循环延时，避免CPU全速空转 } /* USER CODE END 3 */

5. 高级优化与常见问题排查

5.1 扫描频率优化与低功耗考量

上面的基础扫描代码每10ms扫描一次，在while(1)中通过延时控制。这虽然简单，但有两个问题：1)HAL_Delay依赖SysTick，可能被中断打断；2) 即使没有按键操作，CPU也在不停扫描，功耗较高。

优化方案1：使用定时器中断触发扫描这是更专业的方法。配置一个基本定时器（如TIM6）产生10ms中断，在中断服务函数中只设置一个标志位，在主循环中检查这个标志位再执行KEYPAD_Scan()。这样扫描间隔更精确，且主循环可以做其他事情。

// 在tim.c的中断回调函数中 void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim) { if(htim->Instance == TIM6) { keypad_scan_flag = 1; } } // 主循环中 if(keypad_scan_flag) { keypad_scan_flag = 0; KEYPAD_Scan(); }

优化方案2：引入睡眠模式如果系统对功耗敏感，可以在无按键时让MCU进入睡眠（Sleep）模式。这需要将列线对应的GPIO中断使能（配置为下降沿和上升沿触发）。当任何按键按下（下降沿）或释放（上升沿）时，触发GPIO外部中断，在中断服务例程中唤醒MCU，并启动一个定时器进行扫描消抖。这样可以实现极低的待机功耗。

5.2 多键按下与“鬼影”问题处理

基础扫描法在同时按下多个键时可能会产生“鬼影”（Ghosting）或误判。例如，按下三个特定位置的键，可能会虚拟出第四个不存在的按键被按下的信号。

解决方案1：软件规避（适合要求不高的场景）在扫描逻辑中，一旦检测到有按键按下，可以立即记录并跳出扫描循环，本次扫描只报告最先检测到的一个键。这实现了“单键按下”响应，避免了多键组合的歧义。大多数消费电子产品（如计算器、遥控器）都采用这种方式，因为用户极少需要真正同时按下两个以上的键。

解决方案2：二极管隔离（硬件解决）这是彻底解决多键无冲突（N-Key Rollover）的硬件方法。在每个按键的两个引脚之间串联一个二极管，方向要一致（例如，所有二极管的阳极接行线，阴极接列线）。这样，电流只能从行流向列，防止了多键按下时产生的逆向电流通路，从而消除了鬼影。代价是硬件成本和布局复杂度增加。

解决方案3：行列反转扫描法这是一种纯软件的改进方案。先按前述方法扫描一遍（行输出，列输入），然后再反过来，将列设置为输出并依次拉低，行设置为输入并读取。通过两次扫描的结果进行对比和运算，可以识别出部分多键按下的情况，但不能完全解决所有鬼影问题，复杂度较高。

对于绝大多数应用，方案1（软件单键响应）已经完全够用且是最佳选择。

5.3 常见问题排查实录

1. 所有按键无反应

   • 检查CubeMX配置：确认行线是否正确配置为推挽输出，且初始电平为高；列线是否为上拉输入。
   • 检查硬件连接：用万用表蜂鸣档，确认PCB或杜邦线连接可靠，没有虚焊或接错。
   • 检查引脚冲突：确认使用的引脚（特别是PB3/PA15等）没有被JTAG/SWD复用功能占用。在CubeMX的SYS->Debug里确认。
   • 检查时钟配置：确保系统时钟正确配置并运行，最简单的验证方法是点灯。

2. 某个特定行或列的按键全部失灵

   • 检查对应GPIO引脚：重点检查失灵行或列对应的那个GPIO引脚配置和焊接。
   • 检查代码中的数组：核对row_pins/ports和col_pins/ports数组的定义顺序是否与硬件连接一一对应。

3. 按键响应不稳定，偶尔触发或连击

   • 消抖时间不足：将KEY_DEBOUNCE_TIME_MS从20ms增加到30ms或50ms试试。机械按键的抖动时间通常在5-20ms。
   • 扫描间隔不当：扫描太快可能捕捉到抖动，太慢则影响响应。10-20ms的扫描周期是个不错的起点。
   • 硬件干扰：如果走线过长或靠近噪声源，可能引入干扰。可以在GPIO引脚到地之间加一个20-100pF的电容滤除高频噪声，或者软件上采用连续多次采样确认的滤波算法。

4. 同时按下多个键行为异常

   • 这就是前述的“鬼影”问题。首先明确你的应用是否需要支持多键同时按下。如果不需要，采用“单键响应”逻辑即可。如果需要，考虑增加二极管或使用更复杂的扫描芯片。

5. 代码编译后下载，按键功能时好时坏

   • 优化等级问题：在Keil中，高优化等级（如-O2, -O3）可能会优化掉一些它认为“无效”的延时循环。对于for(volatile int i=0; i<10; i++);这样的简单延时，建议将循环变量i声明为volatile，或者直接使用HAL库提供的微秒级延时HAL_Delay_us()（需要自己实现或使用定时器）。
   • 中断干扰：如果系统中有其他高优先级中断频繁发生，可能会打断扫描过程。确保按键扫描的代码执行时间足够短，或者将扫描放在主循环中，并考虑关键部分是否需要临时关闭中断。

6. 项目扩展与进阶思路

实现基础功能只是第一步，一个健壮的按键系统还可以从以下几个方面扩展：

1. 组合键与层功能（Fn键）通过定义一个“Fn”键，配合状态机，可以轻松实现按键功能的扩展。例如，当检测到Fn键处于“已按下并保持”状态时，再去扫描其他按键，将它们的键值映射到第二层功能（如F1-F12）。

2. 模拟摇杆或飞梭编码器如果项目需要模拟量输入或快速增减值，可以考虑将矩阵按键的某一行或某一列，通过电阻分压网络连接到一个ADC通道上。通过ADC读取的电压值来判断多个按键中哪一个被按下，或者实现类似摇杆的方向模拟。不过，这种方式精度和稳定性不如专用摇杆模块。

3. 与显示模块（如OLED）的联动这是非常常见的组合。将按键扫描的结果实时显示在OLED屏幕上，用于菜单导航、参数设置等。你可以设计一个菜单系统，用上下左右键（用矩阵按键中的四个键模拟）移动光标，用确认键（如中间的键）进入子菜单或确认设置。

4. 使用硬件扫描芯片如果MCU的GPIO资源真的非常紧张，或者需要实现全键无冲突（NKRO），可以考虑外置专用的键盘扫描芯片，如TM1650（LED驱动兼按键扫描）、HT16K33等。这些芯片通过I2C或SPI与MCU通信，只需要2根线就能管理大量的按键，大大节省MCU资源和软件开销。

最后，我个人的一点体会是，嵌入式开发中，像矩阵按键这样的基础模块，追求的不是代码有多么炫技，而是稳定、可靠、易于维护。清晰的模块化设计、充分的注释、以及针对具体应用场景的适度优化（比如是否要低功耗、是否要防抖、是否支持多键），远比一个看似高效但晦涩难懂的“奇技淫巧”要重要得多。把这个4x4矩阵按键的驱动调稳定了，其背后体现的状态机思想、消抖策略、硬件软件协同的思维，会让你在应对更复杂的嵌入式系统任务时更加游刃有余。

本文还有配套的精品资源，点击获取