嵌入式C++实践开发第21篇（单片机实践）：按钮输入 —— 硬件原理、消抖与HAL API

嵌入式C++实践开发第21篇（单片机实践）：按钮输入 ------ 硬件原理、消抖与HAL API

仓库已经开源！仍然在持续建设中，喜欢的话点个⭐！相关的链接如下：
https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP
静态网页直接阅览：https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/
承接上一篇：GPIO 输入路径已经搞清楚了------上拉输入、施密特触发器、IDR 寄存器。这一篇我们把理论落地：画接线图、算电流，面对机械抖动问题，然后用 HAL API 读取按钮状态。

我们的接线方案

在 LED 教程里，我们用的硬件是 Blue Pill 板上自带的 LED------连接在 PC13 上，不需要任何外部接线。按钮不一样------Blue Pill 上没有板载的用户按键（复位按钮是 NRST 引脚专用的，不能当通用按钮用），所以你需要自己接一个按钮。

接线方案如下：

text 复制代码

STM32F103C8T6 内部
         ┌─────────────────────┐
         │                     │
         │    VDD (3.3V)       │
         │      │              │
         │   [R_pullup ~40kΩ]  │
         │      │              │
         │      ├──── PA0 ─────┤─── 排针 PA0
         │      │              │
         │                     │
         │     GND ────────────┤─── 排针 GND
         │                     │
         └─────────────────────┘

         外部接线：
         PA0 排针 ──┤  按钮  ├─── GND 排针

   松开按钮：PA0 通过内部上拉电阻接到 VDD → 读到高电平 (1)
   按下按钮：PA0 直接接到 GND             → 读到低电平 (0)

就这么简单------按钮的两根线分别插到 Blue Pill 排针上的 PA0 和 GND 孔位。不需要电阻、不需要电容、不需要任何其他元件。STM32 内部的 40kΩ 上拉电阻帮我们搞定了默认电平的问题。

电流计算

按下按钮时，电流从 VDD（3.3V）经内部上拉电阻（约 40kΩ）流向 GND：

text 复制代码

I = VDD / R_pullup = 3.3V / 40000Ω = 82.5μA

82.5 微安。这个电流非常小------STM32 的每个引脚最大能承受 25mA 的电流，82.5μA 只是额定值的 0.3%。而且按钮按下的时间通常很短（几百毫秒级别），对功耗的影响可以忽略。即使在电池供电的项目中，这个电流也完全不是问题。

为什么选 PA0

上一篇我们提到了选 PA0 的原因：EXTI0 有独立的中断向量。这里再补充一个实际原因------PA0 在 Blue Pill 排针上的位置很好找。Blue Pill 板子右侧的排针上，PA0 通常在最上面几个位置，旁边的 GND 引脚也很近，用一根短杜邦线就能接好。

如果你手边只有 4 脚的轻触按键也不用担心------4 脚按键的对角两脚是连通的（同一个触点），相邻两脚之间才是开关。你只需要选对角的两脚分别接 PA0 和 GND 就行。

对比方案：下拉接法

作为参考，还有一种下拉接法：

text 复制代码

STM32F103C8T6 内部
         ┌─────────────────────┐
         │                     │
         │   [R_pulldown ~40kΩ]│
         │      │              │
         │      ├──── PA0 ─────┤─── 排针 PA0
         │      │              │
         │     VDD ────────────┤─── 排针 3.3V
         │                     │
         └─────────────────────┘

         外部接线：
         PA0 排针 ──┤  按钮  ├─── 3.3V 排针

   松开按钮：PA0 通过内部下拉电阻接到 GND → 读到低电平 (0)
   按下按钮：PA0 直接接到 VDD             → 读到高电平 (1)

下拉方案是"高电平有效"（Active High）------松开=低，按下=高。对应代码中的 ButtonActiveLevel::High。

我们不用下拉方案，原因有三：(1) 上拉方案中按钮接地，GND 在板子上到处都是，接线更方便；(2) 绝大多数 MCU 开发资料默认用上拉方案，社区资源更丰富；(3) 如果按钮线被意外拉断或脱落，上拉方案引脚回到高电平（安全状态），而浮空的引脚电平不确定，可能导致误触发。

机械抖动：按钮的"原罪"

接好了线，理论上按钮应该产生理想的信号：按下瞬间从高电平干净地跳到低电平，松开瞬间从低电平干净地跳回高电平。就像这样：

text 复制代码

理想的按钮信号：

高 ───────────┐                 ┌───────────
              │                 │
低            └─────────────────┘
              │← 按下 →│← 松开 →│

但现实中，机械开关不是理想器件。按钮内部的金属触点在闭合和断开的瞬间，由于弹簧效应和金属弹性，会经历一个短暂的"弹跳"过程------触点反复接触、断开、再接触，直到最终稳定。

用示波器看，实际信号是这样的：

text 复制代码

实际的按钮信号（按下瞬间）：

高 ───┐  ┌┐ ┌┐  ┌┐  ┌─────────────
      │  ││ ││  ││  │
低    └──┘└─┘└──┘└──┘
      │← 5~20ms →│
       抖动区间
      最终稳定为低电平

实际的按钮信号（松开瞬间）：

低 ─────────────┐  ┌┐ ┌┐  ┌─────
                │  ││ ││  │
高              └──┘└─┘└──┘
                │← 5~20ms →│
                 抖动区间
                最终稳定为高电平

抖动的持续时间取决于开关的物理特性------便宜的轻触按键可能抖 10-15ms，质量好的可能只有 2-5ms。但几乎不存在完全不抖动的机械开关。

不处理的后果

如果代码不处理抖动，直接在主循环中读取引脚状态，会发生什么？

假设主循环每 1ms 执行一次（对于 72MHz 的 STM32 来说绰绰有余）。按下按钮的 10ms 抖动期间，CPU 可能采样到这样的序列：

text 复制代码

采样：  1 1 0 1 0 0 1 0 0 0 0 0 0 0 ...
         ↑       ↑ ↑       ↑
         按下    抖动中的假"释放"和假"按下"

CPU 看到的是：高→低→高→低→高→低→低→低→低... 它会认为按钮被按下了三四次，而不是一次。如果你的代码是"每次按下切换 LED 状态"，那你会发现按一次按钮，LED 可能亮、可能灭、可能根本没反应------因为多次翻转互相抵消了。

这不是理论推演------你可以很容易地验证。写一个最简单的轮询程序，不加任何消抖，然后快速按一下按钮，用计数器记录检测到的"按下"次数。你会发现一次按压被计了 2-5 次，偶尔甚至是 7-8 次。

软件消抖：我们的路线

软件消抖的核心思想很简单：不信任第一次采样。检测到引脚电平变化后，不立即认为状态变了，而是等一段时间再采样确认。如果连续多次采样结果一致，才认为状态真正发生了变化。

具体实现有几种方式，我们会逐步演进：

阻塞延时消抖 ：检测到变化后 HAL_Delay(20) 等待，然后再采样。简单但有代价------CPU 被阻塞 20ms，什么都干不了。
非阻塞时间戳消抖 ：用 HAL_GetTick() 记录变化时间，每次循环检查是否已经过了足够长的时间。不阻塞 CPU，但需要手动管理状态变量。
状态机消抖：用 7 个状态的有限状态机来精确管理整个消抖和事件检测过程。这是最可靠的方案。

每一种都是前一种的自然演进------先用最简单的方式解决问题，看到问题后用更好的方式解决。这种"先脏后净"的学习路径比直接给出最终方案要好得多，因为你理解了每一步的"为什么"。

从输出 API 到输入 API

LED 教程中，我们用了三个 HAL 函数来控制 LED：

操作	HAL 函数	操作的寄存器
初始化引脚	`HAL_GPIO_Init()`	CRL/CRH
写引脚电平	`HAL_GPIO_WritePin()`	ODR/BSRR
翻转引脚电平	`HAL_GPIO_TogglePin()`	ODR/BSRR

按钮只需要两个：一个初始化，一个读取。

操作	HAL 函数	操作的寄存器
初始化引脚	`HAL_GPIO_Init()`	CRL/CRH
读引脚电平	`HAL_GPIO_ReadPin()`	IDR

HAL_GPIO_Init() 在 LED 教程中已经拆解过了------它把 GPIO_InitTypeDef 结构体中的配置翻译成 CRL/CRH 寄存器的位域操作。按钮初始化和 LED 初始化用的是同一个函数，只是参数不同。

输入模式初始化

GPIO_InitTypeDef 的输入配置

LED 的初始化代码是这样的：

c 复制代码

GPIO_InitTypeDef init = {0};
init.Pin = GPIO_PIN_13;
init.Mode = GPIO_MODE_OUTPUT_PP;   // 推挽输出
init.Pull = GPIO_NOPULL;
init.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOC, &init);

按钮的初始化只需要改两个参数：

c 复制代码

GPIO_InitTypeDef init = {0};
init.Pin = GPIO_PIN_0;
init.Mode = GPIO_MODE_INPUT;       // 通用输入
init.Pull = GPIO_PULLUP;           // 内部上拉
init.Speed = GPIO_SPEED_FREQ_LOW;  // 输入模式下 Speed 无意义，但需要填值
HAL_GPIO_Init(GPIOA, &init);

三个值得注意的地方：

第一，Mode 从 GPIO_MODE_OUTPUT_PP 变成了 GPIO_MODE_INPUT。 这对应 CRL 寄存器中 MODE[1:0] = 00（输入模式）和 CNF[1:0] = 10（上拉/下拉输入）。

第二，Pull 从 GPIO_NOPULL 变成了 GPIO_PULLUP。 这启用内部上拉电阻，同时在 ODR 对应位写 1 来选择上拉方向。

第三，Speed 在输入模式下没有实际意义。 Speed 控制输出驱动器的翻转速率------输入模式下输出驱动器是断开的，所以这个参数不影响任何行为。但 HAL 要求你填一个值，随便填就行。

别忘了时钟

和输出一样，使用任何 GPIO 端口之前必须先使能对应的时钟。PA0 在 GPIOA 上，所以：

c 复制代码

__HAL_RCC_GPIOA_CLK_ENABLE();

如果你忘了这一步，HAL_GPIO_Init() 调用不会报错（它不知道你有没有开时钟），但写入的配置不会生效------引脚保持复位状态（浮空输入），读出来的值是不确定的。这是新手最常见的坑之一。

LED 教程中我们用 if constexpr 在编译时自动选择时钟使能宏，按钮教程的 Button 模板类会复用同样的机制。但如果你用 C 语言写，记得手动调用。

HAL_GPIO_ReadPin

函数签名

c 复制代码

GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin);

两个参数：GPIOx 指定端口（GPIOA、GPIOB、GPIOC...），GPIO_Pin 指定引脚编号（GPIO_PIN_0 ~ GPIO_PIN_15）。返回值是 GPIO_PinState 枚举：

c 复制代码

typedef enum {
    GPIO_PIN_RESET = 0,  // 低电平
    GPIO_PIN_SET   = 1   // 高电平
} GPIO_PinState;

底层实现

HAL 库的 HAL_GPIO_ReadPin() 实现非常简洁：

c 复制代码

GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin) {
    GPIO_PinState bitstatus;
    if ((GPIOx->IDR & GPIO_Pin) != (uint32_t)GPIO_PIN_RESET) {
        bitstatus = GPIO_PIN_SET;
    } else {
        bitstatus = GPIO_PIN_RESET;
    }
    return bitstatus;
}

核心就是一个位操作：GPIOx->IDR & GPIO_Pin。IDR 是 16 位只读寄存器，每个 bit 对应一个引脚。GPIO_PIN_0 的值是 0x0001，所以 IDR & 0x0001 就是取 bit 0 的值。如果不为 0，引脚是高电平；否则是低电平。

几个时钟周期就能完成（LDR + AND + CMP，编译器优化后约 2-4 个周期）。72MHz 的 CPU 意味着读引脚状态只需要约数十纳秒。

和 WritePin 的对比

HAL_GPIO_WritePin() 操作的是 BSRR 寄存器（Bit Set/Reset Register），这是一个只写的寄存器------写 1 到低 16 位会复位（清零）对应的 ODR bit，写 1 到高 16 位会置位（设一）对应的 ODR bit。这是一种原子操作，不需要读-改-写的三步过程。

HAL_GPIO_ReadPin() 操作的是 IDR 寄存器，只读，直接返回引脚电平。

	输出 (LED)	输入 (按钮)
初始化	`GPIO_MODE_OUTPUT_PP`	`GPIO_MODE_INPUT`
核心操作	`HAL_GPIO_WritePin()` → BSRR	`HAL_GPIO_ReadPin()` → IDR
寄存器属性	BSRR 只写	IDR 只读
操作耗时	1 个时钟周期	1 个时钟周期

read_pin_state()：我们的 C++ 封装

在 device/gpio/gpio.hpp 中，我们给 GPIO 模板类新增了 read_pin_state() 方法：

cpp 复制代码

[[nodiscard]] State read_pin_state() const {
    return static_cast<State>(HAL_GPIO_ReadPin(native_port(), PIN));
}

这里有几个设计决策需要解释。

为什么返回 State 枚举而不是 bool

你可以争论说返回 bool 更简单------true 是高电平，false 是低电平。但我们选择返回 State 枚举（State::Set 和 State::UnSet），和输出端的 set_gpio_pin_state(State) 保持对称。这样输入和输出用的是同一套类型，代码风格一致。

而且 State 枚举比 bool 更不容易被误用。如果你有多个引脚要操作，bool 的 true/false 含义在不同上下文中可能混淆------true 是按下还是松开？取决于上拉还是下拉。但 State::Set 永远表示引脚为高电平，State::UnSet 永远表示低电平，不含歧义。

为什么加 [[nodiscard]]

[[nodiscard]] 告诉编译器：这个函数的返回值不应该被忽略。如果你写了 button.read_pin_state(); 但没有使用返回值，编译器会发出警告。

读引脚状态的唯一目的就是获取返回值。如果你调用了 read_pin_state() 却不使用结果，那这个调用百分之百是写错了------多半是忘写赋值语句了。在嵌入式开发中，这类低级错误如果不被抓出来，可能导致按钮状态没被检测到，系统行为异常且难以调试。

static_cast 的零开销

HAL_GPIO_ReadPin() 返回 GPIO_PinState（0 或 1），static_cast<State>() 把它转成 State::Set 或 State::UnSet。static_cast 在枚举之间的转换是纯编译时操作------底层值（0 或 1）不变，只是类型信息变了。生成的机器码和直接用 GPIO_PinState 完全一样。

const 成员函数

read_pin_state() 被声明为 const------它不修改对象的任何成员变量。这是"只读操作"在 C++ 中的标准表达方式。对比 set_gpio_pin_state() 也被声明为 const------这是因为我们的 GPIO 模板类没有成员变量需要修改，所有的"状态"都存在于硬件寄存器中，而不是 C++ 对象里。

最小的 C 语言示例

在进入完整的轮询程序之前，先用一个最小的 C 代码片段验证一下：能不能读到按钮状态？

c 复制代码

#include "stm32f1xx_hal.h"

int main(void) {
    HAL_Init();
    /* 系统时钟配置省略 */

    /* 使能 GPIOA 时钟 */
    __HAL_RCC_GPIOA_CLK_ENABLE();

    /* 配置 PA0 为上拉输入 */
    GPIO_InitTypeDef init = {0};
    init.Pin = GPIO_PIN_0;
    init.Mode = GPIO_MODE_INPUT;
    init.Pull = GPIO_PULLUP;
    HAL_GPIO_Init(GPIOA, &init);

    /* 同时配置 PC13 为推挽输出（控制 LED） */
    __HAL_RCC_GPIOC_CLK_ENABLE();
    GPIO_InitTypeDef led_init = {0};
    led_init.Pin = GPIO_PIN_13;
    led_init.Mode = GPIO_MODE_OUTPUT_PP;
    led_init.Speed = GPIO_SPEED_FREQ_LOW;
    HAL_GPIO_Init(GPIOC, &led_init);

    while (1) {
        /* 读取 PA0 状态 */
        GPIO_PinState state = HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0);

        if (state == GPIO_PIN_RESET) {
            /* 按钮按下：低电平 → 点亮 LED（PC13 低电平有效） */
            HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_RESET);
        } else {
            /* 按钮松开：高电平 → 熄灭 LED */
            HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_SET);
        }
    }
}

这段代码做了四件事：(1) 使能 GPIOA 和 GPIOC 时钟，(2) 配置 PA0 为上拉输入，(3) 配置 PC13 为推挽输出，(4) 主循环中读取 PA0 并控制 PC13。

⚠️ 注意：这段代码没有消抖。快速按一下按钮，LED 可能会闪好几次。后续文章会看到这个问题的完整演示和解决方案。

如果你把这段代码烧到板子上，按住按钮时 LED 亮，松开时 LED 灭。最基本的输入输出交互就这样实现了。

硬件准备清单

总结一下你需要的硬件：

Blue Pill 开发板 --- 和 LED 教程同一块，不需要换
ST-Link V2 调试器 --- 和 LED 教程一样
一个按钮开关 --- 最普通的轻触按键（tactile switch），2 脚或 4 脚都行
一到两根杜邦线 --- 用来连接按钮和排针（PA0 和 GND 在排针上不一定相邻，通常需要杜邦线跳接）

接线只有两根：

按钮一端 → PA0
按钮另一端 → GND

PC13 板载 LED 保持不变，不需要额外接线。

⚠️ 如果你手边确实没有按钮开关，可以用一根杜邦线模拟------一端插 PA0，另一端碰一下 GND 再松开。效果和按钮一样，只是没有弹簧回弹，抖动可能会少一些（但仍然会有）。

本章小结

这一篇从硬件接线讲到了软件 API。核心要点：

硬件接线：上拉方案最简单，按钮接 PA0 和 GND，电流只有 82.5μA
机械抖动：真实按钮在按下和松开时会产生 5-20ms 的电平震荡，必须用软件消抖处理
输入初始化 ：GPIO_MODE_INPUT + GPIO_PULLUP 两个参数就够了
读引脚 API ：HAL_GPIO_ReadPin() 底层就是读 IDR 寄存器，一个时钟周期
我们的封装 ：read_pin_state() 返回类型安全的 State 枚举，带 [[nodiscard]] 防止误用

下一篇我们会学习完整的轮询程序，亲眼看到没有消抖会发生什么，然后一步步实现可靠的消抖算法。

嵌入式C++实践开发第21篇（单片机实践）：按钮输入 —— 硬件原理、消抖与HAL API