1. 从"点灯"到"看见状态"：为什么这一步比想象中重要
很多人第一次接触 STM32 或者任何一款单片机，做的第一件事就是点亮一颗 LED。代码烧进去，灯亮了，心里一阵激动，然后呢？然后就没有然后了。灯一直亮着，你也不知道程序到底跑到哪一步了，按键按下去有没有被检测到，中断有没有触发，状态机现在停在哪个分支。这种感觉就像闭着眼睛开车，仪表盘全黑，你只能靠猜。
把按键和 LED 状态显示出来，这件事看起来简单，但它其实是从"能跑"到"能调试"的分水岭。我见过太多初学者卡在这个阶段：代码逻辑明明写对了，但现象就是不对，因为没有可视化的状态反馈，只能靠反复改代码、反复烧录去试，效率极低。而一旦你把按键状态和 LED 状态通过 OLED 实时显示出来，整个调试过程就完全不一样了——你能看见程序在干什么，能看见按键按下的瞬间 GPIO 电平的变化，能看见状态机在哪个状态之间跳转。
这篇文章面向的是刚上手 STM32、已经会点灯但还没建立起调试思维的开发者。我会从 GPIO 的输入输出配置讲起，把按键消抖、状态显示、OLED 驱动这几个环节串起来，重点不是给你一份能跑的代码，而是让你理解每一步为什么这么做，以及在实际操作中会遇到哪些坑。关键词里的 GPIO、STM32、OLED、按键中断、HAL 库这些概念，我都会结合实际场景展开讲，不堆砌术语。
先明确一个核心思路：按键是输入，LED 和 OLED 是输出，整个系统的本质是"输入→处理→输出"的闭环。把这个闭环跑通并且可视化，你就有了一个最小可用的调试平台，后面加什么功能都可以在这个平台上验证。
2. GPIO 输入输出的底层逻辑：别只会抄配置
2.1 推挽输出和上拉输入到底在选什么
STM32 的 GPIO 有 8 种工作模式，这个数字很多人背过，但真正理解每种模式适用场景的人不多。点亮 LED 用的是推挽输出，按键检测用的是上拉输入或浮空输入，这两个选择背后都有明确的电路原因。
推挽输出的"推"和"挽"指的是两个 MOS 管交替工作：输出高电平时上面的管子导通，把引脚拉到 VCC；输出低电平时下面的管子导通，把引脚拉到 GND。这种模式驱动能力强，能直接点亮 LED，也能输出稳定的高低电平。开漏输出则只有下面的管子工作，高电平需要外部上拉电阻，适合 I2C 这种总线场景。点灯用推挽，这是没有争议的。
按键这边就更有意思了。按键的本质是一个机械开关，一端接 GPIO，另一端接 GND 或 VCC。如果按键接 GND，那么 GPIO 需要配置成上拉输入，这样按键没按下时引脚被内部上拉电阻拉到高电平，按下时被拉到 GND，读到低电平。如果按键接 VCC，就配置成下拉输入。如果外部已经有上拉电阻，GPIO 可以配置成浮空输入。
我个人的习惯是：能用内部上拉就用内部上拉，省一个电阻，PCB 也干净。STM32 的内部上拉电阻典型值在 30kΩ 到 50kΩ 之间，对于按键这种低速信号完全够用。但要注意，如果你的按键线拉得很长，或者环境干扰大，内部上拉的抗干扰能力不如外部 10kΩ 上拉，这时候还是老老实实加外部电阻。
2.2 按键电路设计里那些容易忽略的细节
按键模块的电路设计看起来就是"一个开关加一个电阻"，但实际做项目的时候，有几个点特别容易出问题。
第一个是按键抖动。机械按键在按下和松开的瞬间，触点会因为弹性产生多次通断，持续时间通常在 5ms 到 20ms 之间。如果你在中断里直接读按键状态然后执行动作，一次按下可能会触发好几次。解决办法有两种：硬件上并联一个 0.1μF 的电容做 RC 滤波，软件上做延时消抖或者状态机消抖。我一般用软件消抖，因为灵活，不增加物料成本。
第二个是按键和 LED 共用引脚的问题。有些教程为了省引脚，把按键和 LED 接在同一个 GPIO 上，通过分时复用实现。这种做法在简单实验里能跑，但实际项目中非常不推荐，因为输入输出切换的时序很难控制，容易出现 LED 状态影响按键检测的情况。引脚不够就换引脚多的型号，或者用矩阵按键、IO 扩展芯片，别在这种地方省。
第三个是按键中断的触发边沿选择。STM32 的外部中断支持上升沿、下降沿、双边沿触发。按键接 GND 配上拉输入的话，按下是下降沿，松开是上升沿。如果你只想响应按下动作，就配置下降沿触发。但这里有个坑：中断触发后如果不做消抖，一次按下会进多次中断。我的做法是在中断服务函数里只做一个标记，实际的处理放到主循环里配合定时器消抖，这样既响应快又不会误触发。
2.3 HAL 库配置 GPIO 的实操要点
用 HAL 库配置 GPIO 比直接操作寄存器简单很多，但有几个参数容易填错。以 STM32F103C8T6 为例，点亮一个接在 PA5 的 LED，配置结构体是这样的：
GPIO_InitTypeDef GPIO_InitStruct = {0}; __HAL_RCC_GPIOA_CLK_ENABLE(); GPIO_InitStruct.Pin = GPIO_PIN_5; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; GPIO_InitStruct.Pull = GPIO_NOPULL; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);这里GPIO_SPEED_FREQ_LOW很多人会忽略，觉得速度无所谓。实际上 GPIO 速度设置影响的是引脚翻转的压摆率，速度越高，EMI 辐射越大。点 LED 这种低速应用，用 LOW 就够了，没必要设成 HIGH。只有 SPI、I2C 这种高速通信才需要调高速度。
按键配置成上拉输入：
GPIO_InitStruct.Pin = GPIO_PIN_0; GPIO_InitStruct.Mode = GPIO_MODE_INPUT; GPIO_InitStruct.Pull = GPIO_PULLUP; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);读取按键状态用HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0)，返回GPIO_PIN_SET或GPIO_PIN_RESET。注意这里返回的是引脚的实际电平，不是"按下"或"松开"，你需要根据电路自己判断。上拉输入接 GND 的按键，读到 RESET 表示按下。
提示：配置 GPIO 之前一定要先使能对应的时钟，
__HAL_RCC_GPIOx_CLK_ENABLE()这行漏了的话，后面所有配置都不生效，而且不会报错，现象就是引脚完全没反应。这个坑我踩过不止一次。
3. 按键消抖与状态机：让按键响应变得可靠
3.1 为什么延时消抖在复杂项目里会翻车
最简单的消抖方式是在检测到按键按下后延时 10ms 再读一次，如果还是按下状态就确认。这个方案在只有一个按键、主循环里没别的事情的时候能用，但一旦你的项目里有 OLED 刷新、传感器读取、串口通信这些任务，HAL_Delay()会把整个 CPU 卡住，OLED 会闪、串口会丢数据。
我早期做的一个环境监测项目就吃过这个亏：主循环里用HAL_Delay(10)做按键消抖，结果 DHT11 的时序被破坏，温湿度读出来全是乱码。后来改成定时器消抖才解决。
正确的做法是用一个定时器（比如 SysTick 或者 TIM2）产生 1ms 或 5ms 的中断，在中断里做按键扫描和状态判断，主循环只负责读取消抖后的按键状态。这样消抖不占用主循环时间，也不会阻塞其他任务。
3.2 用状态机实现按键的短按、长按和双击
按键消抖只是第一步，实际项目里往往还需要区分短按、长按、双击。用状态机来做这件事逻辑最清晰。我一般定义这几个状态：IDLE（空闲）、DEBOUNCE（消抖中）、PRESSED（已按下）、LONG_PRESS（长按中）、RELEASE（等待松开）。
状态转移的逻辑是这样的：在IDLE状态检测到低电平，进入DEBOUNCE并开始计数；计数到 10ms 后如果还是低电平，进入PRESSED，同时记录按下时间；在PRESSED状态下如果持续低电平超过 1000ms，进入LONG_PRESS并触发长按事件；检测到高电平后回到IDLE，根据按下持续时间判断是短按还是长按。
双击的判断稍微复杂一点：第一次松开后不立即触发短按事件，而是启动一个 300ms 的窗口，如果窗口内再次检测到按下，就判定为双击；窗口超时没有第二次按下，才触发短按。这个逻辑用状态机写出来大概几十行代码，但比一堆if-else嵌套清晰得多。
3.3 按键中断和轮询该怎么选
按键中断的优点是响应快，CPU 不用一直轮询。但中断方式有几个限制：一是中断服务函数里不能做耗时操作，二是多个按键同时按下时中断处理会变得复杂，三是中断方式天然不适合做消抖。
我的建议是：如果按键数量少（1-2 个）且对响应速度要求高，用中断；如果按键数量多或者需要复杂的按键逻辑，用定时器轮询。实际上大部分项目用定时器轮询就够了，5ms 扫描一次，人根本感觉不到延迟。
如果一定要用中断，配置方式是在 GPIO 初始化之后使能外部中断：
HAL_NVIC_SetPriority(EXTI0_IRQn, 2, 0); HAL_NVIC_EnableIRQ(EXTI0_IRQn);然后在HAL_GPIO_EXTI_Callback()回调函数里做标记，实际处理放到主循环。注意 STM32 的外部中断线是复用的，PA0 和 PB0 共用 EXTI0，不能同时使用。
4. OLED 显示：把程序内部状态搬到屏幕上
4.1 I2C OLED 的地址问题和初始化坑
0.96 寸的 OLED 模块大部分用 SSD1306 驱动芯片，I2C 接口，默认地址是 0x78（8 位地址）或 0x3C（7 位地址）。这里有个特别容易搞混的地方：HAL 库的 I2C 函数用的是 7 位地址左移一位后的值，也就是 0x78。如果你填 0x3C，屏幕不会有任何反应。
我见过太多人在这一步卡住，以为是接线问题或者屏幕坏了，其实只是地址填错了。判断方法很简单：用 I2C 扫描程序扫一下总线，看能不能找到设备。如果扫不到，先检查接线和上拉电阻；如果扫到了但地址不对，改地址就行。
初始化 SSD1306 需要发送一长串命令，包括设置对比度、显示模式、扫描方向、时钟分频等。这些命令手册里都有，但自己一条条写太麻烦。我一般直接用现成的驱动库，比如 U8g2 或者自己封装一个精简版。U8g2 功能全但占 Flash 比较大，STM32F103C8T6 只有 64KB Flash，用 U8g2 的话要精简配置，只保留需要的字体和功能。
4.2 显示按键和 LED 状态的界面设计
把状态显示出来，界面不用花哨，但要清晰。我通常这样布局：第一行显示 LED 状态（ON/OFF），第二行显示按键状态（按下/松开），第三行显示按键计数或者状态机当前状态，第四行显示运行时间或者帧率。
刷新策略上，不要每次主循环都全屏刷新，那样屏幕会闪，而且浪费 CPU。我的做法是只在状态发生变化时刷新对应的区域，比如 LED 状态变了就只更新第一行。SSD1306 支持页地址模式，可以只写入特定页的数据，这样刷新效率高很多。
如果用的是 HAL 库的 I2C 阻塞发送，每次刷新大概需要几毫秒，对于 128x64 的屏幕，全屏刷新 1024 字节数据在 400kHz I2C 下大约需要 20ms 左右。这个时间对于大部分应用可以接受，但如果你的主循环里有严格时序要求的任务，建议用 DMA 传输或者降低刷新频率。
4.3 用 OLED 做调试面板的实战技巧
OLED 不只是用来显示最终效果的，它本身就是一个极好的调试工具。我在调试 I2C 通信的时候，会把 I2C 的收发数据实时显示在 OLED 上，一眼就能看出是发送失败还是接收失败。调试定时器的时候，把定时器的计数值显示出来，能直观看到定时器有没有在跑、周期对不对。
有个小技巧：在 OLED 上留一个区域显示错误码。程序里每个可能出错的地方都设置一个错误码，出错时把错误码写到 OLED 上，这样即使程序跑飞了，你也能知道是在哪一步出的问题。比用串口打印方便，因为不需要连电脑，现场调试的时候特别有用。
还有一个坑要注意：OLED 的 I2C 通信和按键中断可能产生冲突。如果按键中断优先级比 I2C 高，中断触发时会打断 I2C 传输，导致 OLED 显示异常。解决办法是把 I2C 传输放在中断优先级较低的任务里，或者用 DMA 传输避免 CPU 参与。
5. 把按键、LED、OLED 串起来：一个完整的调试闭环
5.1 系统架构和任务划分
现在把前面几部分串起来。整个系统我分成三个层次：硬件抽象层负责 GPIO、I2C、定时器的初始化；驱动层封装按键扫描、LED 控制、OLED 显示的具体操作；应用层实现状态机和业务逻辑。
主循环的结构是这样的：定时器中断每 5ms 触发一次按键扫描，更新按键状态；主循环里检测按键事件，根据事件更新 LED 状态和状态机；状态变化时刷新 OLED 显示。这样按键响应及时，OLED 刷新不影响按键检测，LED 控制也是即时的。
具体到代码结构，我会定义几个全局变量：key_state存储当前按键状态，led_state存储 LED 状态，key_event存储按键事件（短按、长按等）。定时器中断里只更新key_state和key_event，主循环里根据key_event执行动作并更新led_state，然后调用 OLED 刷新函数。
5.2 状态变化的检测和显示更新
显示更新的核心是只在状态变化时刷新。我一般用一个display_dirty标志位，任何状态变化都把对应位置 1，主循环检测到标志位就刷新对应区域并清除标志。这样避免了无谓的刷新，也避免了屏幕闪烁。
举个例子：按键按下时，key_state从 0 变成 1，同时设置display_dirty |= KEY_DIRTY；主循环检测到KEY_DIRTY，调用OLED_ShowString()更新按键状态那一行，然后清除标志。LED 状态变化同理。
这里有个细节：OLED 刷新函数本身要保证原子性，不能在刷新到一半的时候被中断打断。如果 I2C 传输是在主循环里做的，而按键中断随时可能触发，理论上存在竞争。实际测试下来，因为 I2C 传输很快（几毫秒），按键中断频率很低，基本不会出问题。但如果你的项目对可靠性要求高，可以在刷新 OLED 时关中断，刷新完再开。
5.3 实测中遇到的典型问题和解决过程
我在第一次做这个系统的时候，遇到了一个很典型的问题：按键按下后 LED 状态变了，但 OLED 显示没更新。排查过程是这样的：先确认 LED 确实变了，说明按键检测和 LED 控制没问题；然后单独测试 OLED 显示函数，发现直接调用能正常显示；最后定位到是display_dirty标志位没有正确设置。
原因是我在按键处理函数里更新了led_state，但忘记设置display_dirty。这种问题很隐蔽，因为逻辑上"状态变了就应该刷新"是理所当然的，但代码里没有显式地建立这个关联。后来我养成了一个习惯：任何状态变量的修改，都紧跟着设置对应的 dirty 标志，用宏或者函数封装起来，避免遗漏。
另一个问题是 OLED 显示闪烁。原因是主循环里每次循环都调用了全屏刷新，而主循环执行很快，导致屏幕一直在刷新。改成只在 dirty 标志置位时刷新后，闪烁就消失了。
还有一个问题是按键响应偶尔失灵。用逻辑分析仪抓波形发现，按键按下时 GPIO 电平有毛刺，导致状态机误判。后来在按键引脚上并联了一个 100nF 电容，硬件消抖加上软件消抖，问题彻底解决。
6. 从这个小系统延伸出去：还能怎么玩
6.1 加入更多输入输出设备
这个按键+LED+OLED 的框架搭好之后，扩展起来非常方便。想加一个旋转编码器？只需要在定时器中断里多扫描两个引脚，状态机里增加编码器的处理逻辑，OLED 上多显示一行。想加一个蜂鸣器？LED 控制的代码复制一份改个引脚就行。
我后来在这个框架上加了 DHT11 温湿度传感器和 BH1750 光照传感器，OLED 分页显示不同传感器的数据，按键用来切换页面。整个扩展过程只花了半天时间，因为底层的按键扫描、显示刷新、状态管理都已经跑通了，新功能只是往框架里填内容。
6.2 用这个平台验证通信协议
OLED 和传感器用到了 I2C，你还可以在这个平台上加 SPI 的 Flash、UART 的蓝牙模块、CAN 总线的收发器。每加一种通信方式，都可以用 OLED 把收发数据实时显示出来，调试效率比用串口助手高得多。特别是调试 CAN 通信的时候，OLED 上直接显示 CAN ID 和数据帧，不用连电脑就能看到总线上的数据。
6.3 做成一个通用的调试助手
如果你经常做 STM32 项目，可以把这个系统固化成一个"调试助手"：一块 STM32 最小系统板，加上 OLED 和几个按键，烧录一个通用的固件，支持 GPIO 电平监测、PWM 输出、I2C 扫描、串口透传等功能。调试新项目的时候，把这个助手接上去，能省很多事。
我自己就做了这么一个东西，用的是 STM32F103C8T6 核心板加 0.96 寸 OLED，外壳用 3D 打印的。成本不到 30 块钱，但在我调试各种项目的时候帮了大忙。特别是现场调试的时候，没有电脑，全靠这个小东西看状态。
注意：做通用调试助手的时候，GPIO 引脚要引出排针，并且每个引脚旁边标注好丝印，不然接线的时候很容易搞混。我第一版没标丝印，每次接线都要翻原理图，后来重新打了一版 PCB，把引脚定义直接印在板子上，方便多了。
最后分享一个我在实际项目中总结的经验：可视化调试的价值不在于显示了多少信息，而在于把不可见的状态变成可见的。哪怕只是在 OLED 上显示一个变量的值，只要能让你不用猜、不用反复烧录去试，这个投入就是值得的。按键和 LED 状态显示是第一步，把这个闭环跑通，后面所有的调试都会变得轻松。
