1. 从“点灯”到“看见状态”为什么这一步如此关键很多人第一次接触 STM32 或者任何一款单片机都是从“点亮一颗 LED”开始的。但真正让人产生“我好像入门了”这种感觉的瞬间往往不是灯亮了而是你按下按键灯跟着变了同时 OLED 屏幕上把当前的状态明明白白地显示出来。这个项目标题——“把按键和 LED 状态显示出来第一次看见程序到底在干什么”——说的就是这件事。它不是一个炫技的项目而是一个让你第一次真正“看见”程序运行状态的窗口。我见过太多初学者卡在“灯亮了然后呢”这个阶段。代码烧进去LED 闪烁但完全不知道程序内部发生了什么按键按下去有没有被检测到、GPIO 电平到底变没变、程序是不是卡在某个死循环里全靠猜。而把按键状态和 LED 状态同时显示到 OLED 上相当于给你的程序装了一个“仪表盘”。你不再需要靠示波器或者反复改代码来验证逻辑屏幕上的每一个字符都是程序真实运行状态的映射。这个项目涉及的核心技术点其实非常集中GPIO 输入输出配置、按键消抖、OLED 显示驱动、状态机逻辑。但它的价值远不止这些技术点本身而在于它建立了一种“可观测”的开发习惯。你以后做再复杂的项目环境监测、电机控制、通信网关底层逻辑都是一样的——先让状态可见再谈控制逻辑。适合读这篇内容的人包括刚学完 GPIO 点灯实验、不知道下一步该做什么的初学者也包括做过一些项目但调试全靠“改代码猜结果”的开发者。我会从硬件选型、GPIO 模式选择、按键电路设计、OLED 驱动、状态刷新逻辑一直到实际调试中踩过的坑完整地拆一遍。你照着做大概率能一次跑通而且能理解每一步为什么这么做。2. 硬件选型与电路设计别小看按键和 LED 的电路2.1 为什么选 STM32F103C8T6 和 0.96 寸 OLED主控选STM32F103C8T6几乎是入门项目的默认答案。原因很实际价格便宜、资料多、HAL 库支持完善、GPIO 数量足够。这个项目只需要用到几个 GPIOF103C8T6 的 37 个 GPIO 绰绰有余。更重要的是它的芯片包在 Keil 和 CubeMX 里都是标配不需要折腾环境。OLED 选0.96 寸 I2C 接口的 SSD1306模块。这里有个细节值得说市面上 0.96 寸 OLED 有 I2C 和 SPI 两种接口I2C 只需要两根线SCL、SDA接线简单适合这种状态显示场景。SPI 版本刷新更快但占用的 IO 更多对于显示几个状态字符来说完全没必要。0.9 寸和 0.96 寸的 I2C 兼容性问题在热词里被提到过实际原因是 0.9 寸有些模块的 I2C 地址和初始化命令跟 0.96 寸不一样买的时候认准 SSD1306 驱动芯片、地址 0x78 或 0x7A 的模块基本不会出问题。按键用最普通的四脚轻触按键LED 用 3mm 或 5mm 的直插式发光二极管。这两个元件的电路设计看起来简单但恰恰是最容易出问题的地方。2.2 按键电路上拉还是下拉这不是随便选的按键电路的核心问题是引脚在按键未按下时电平必须是确定的。如果引脚悬空电平会随机漂移程序读到的值完全不可预测。所以必须加一个上拉或下拉电阻。我推荐的做法是按键一端接 GPIO另一端接 GNDGPIO 配置为上拉输入。这样按键未按下时内部上拉电阻把引脚拉到高电平程序读到 1按下时引脚被拉到 GND程序读到 0。这种“按下为低”的逻辑是 STM32 按键电路最常见的做法。为什么不加外部上拉电阻因为 STM32 的 GPIO 内部自带可配置的上拉电阻范围大概在 30kΩ 到 50kΩ 之间。对于轻触按键这种低速信号内部上拉完全够用。加外部电阻反而增加布线复杂度。但如果你用的是长线连接或者电磁环境复杂的场景外部加一个 10kΩ 上拉电阻会更稳。这里有个坑要提前说有些开发板上的按键电路已经焊好了外部上拉或下拉电阻你直接接上去就行不需要再配置内部上拉。如果你不确定用万用表量一下按键未按下时引脚对 GND 的电压如果是 3.3V说明已经有上拉了GPIO 就配置为浮空输入或者上拉输入都行如果是 0V说明有下拉那按键逻辑就是反的。2.3 LED 驱动电路限流电阻怎么算LED 的电路设计只有一个核心问题限流电阻选多大。STM32 的 GPIO 输出高电平时电压是 3.3V单个引脚最大输出电流是 25mA但整个芯片的总电流有限制所以不能每个引脚都跑满。假设你用一颗普通的红色 LED正向压降约 1.8V想要的工作电流是 5mA 到 10mA。限流电阻的计算公式是R (VCC - VLED) / ILED代入数值R (3.3V - 1.8V) / 0.008A ≈ 187Ω。实际选 220Ω 或 330Ω 都可以电流分别是 6.8mA 和 4.5mA亮度足够也不会给 GPIO 太大负担。如果你用的是蓝色或白色 LED正向压降约 3.0V 到 3.2V那限流电阻就要小很多甚至直接用 100Ω 以下。但要注意3.3V 供电下蓝色 LED 的压降接近电源电压亮度会不稳定建议用低亮度型号或者降低供电电压。LED 的接法有两种灌电流GPIO 输出低电平点亮LED 阳极接 VCC和拉电流GPIO 输出高电平点亮LED 阴极接 GND。我习惯用灌电流接法因为 STM32 的 GPIO 在输出低电平时灌电流能力更强能到 25mA而输出高电平时拉电流能力弱一些。对于这个项目两种接法都行但灌电流更稳妥。3. GPIO 模式选择8 种模式到底用哪个3.1 输入模式的选择逻辑STM32 的 GPIO 有 8 种工作模式初学者最容易在这里迷糊。我把它简化成一句话输入看要不要电阻输出看要不要速度。对于按键输入可选的有浮空输入引脚完全悬空电平由外部电路决定。如果你的按键电路已经有外部上拉或下拉电阻用这个模式。上拉输入内部上拉电阻启用引脚默认高电平。按键接 GND 时用这个。下拉输入内部下拉电阻启用引脚默认低电平。按键接 VCC 时用这个。模拟输入用于 ADC 采样按键场景不用。我的建议是如果你不确定板子上有没有外部电阻直接用上拉输入。这样即使外部没有电阻引脚也有确定的默认电平。唯一需要注意的是如果外部已经有上拉电阻内部再上拉会让总电阻变小功耗略微增加但对于按键这种场景完全可以忽略。3.2 输出模式的选择逻辑LED 输出可选的有推挽输出可以输出高电平和低电平驱动能力强适合 LED。开漏输出只能输出低电平高电平需要外部上拉。适合 I2C 总线这种需要线与逻辑的场景不适合直接驱动 LED。所以 LED 用推挽输出输出速度选低速就行。输出速度影响的是引脚电平翻转的速率低速模式下翻转慢一些但电磁干扰小功耗低。对于 LED 这种毫秒级变化的信号低速完全够用。如果你选高速除了增加功耗和干扰没有任何好处。3.3 I2C 引脚的复用配置OLED 用的 I2C 接口GPIO 要配置成复用开漏输出模式。这是因为 I2C 总线是线与逻辑多个设备共享 SCL 和 SDA 线任何一个设备拉低总线总线就是低电平。开漏输出配合外部上拉电阻OLED 模块上通常自带 4.7kΩ 上拉才能实现这个逻辑。在 CubeMX 里配置 I2C 时选择 I2C1 或 I2C2对应的 GPIO 会自动配置成复用开漏模式你不需要手动改。但如果你用软件模拟 I2C那就需要手动把两个引脚配置成开漏输出然后在代码里手动控制电平翻转。4. 按键消抖为什么你按一次程序读到了十次4.1 抖动是怎么产生的轻触按键的内部是金属弹片按下和松开的瞬间弹片会发生多次弹性碰撞导致电平在几毫秒内快速跳变。你用示波器看按一次按键电平可能会跳变 5 到 20 次。如果程序直接读引脚电平就会把一次按键识别成多次。这个问题在按键中断模式下尤其明显。如果你用外部中断检测按键一次按下可能触发多次中断程序逻辑就乱了。所以消抖是必须的不是可选项。4.2 软件消抖的两种实现延时消抖是最简单的做法检测到按键按下后延时 10ms 到 20ms再读一次引脚如果还是按下状态就确认按键有效。这个方法的缺点是延时期间程序被阻塞不能做其他事情。对于这个状态显示项目阻塞 20ms 完全没问题因为 OLED 刷新本身也需要时间。定时器消抖是更优雅的做法用定时器每 5ms 中断一次在中断里读取按键状态连续多次读到相同状态才确认。这个方法不阻塞主循环适合复杂项目。但实现起来代码量更大对于初学者来说先用延时消抖把逻辑跑通再考虑优化。我实际用下来10ms 的延时消抖能解决 95% 以上的按键抖动问题。如果你发现偶尔还是有误触发加到 20ms。但不要加到 50ms 以上那样按键响应会明显变迟钝按下去要等半秒才有反应体验很差。4.3 按键状态机的设计比消抖更重要的是按键状态机的设计。很多初学者写的按键代码只能检测“按下”这个瞬间但实际项目里你需要区分按下瞬间按键从松开变为按下用于触发一次动作。持续按下按键保持按下状态用于长按功能。松开瞬间按键从按下变为松开用于结束动作。这个项目里我用一个简单的状态机来管理按键typedef enum { KEY_IDLE, // 空闲状态 KEY_DEBOUNCE, // 消抖中 KEY_PRESSED, // 已按下 KEY_RELEASED // 已松开 } KeyState; KeyState keyState KEY_IDLE; uint32_t keyPressTime 0;每次主循环调用按键扫描函数根据当前状态和引脚电平决定下一步动作。这样不仅能消抖还能检测长按和短按。对于状态显示项目你只需要在“按下瞬间”翻转 LED 状态然后在 OLED 上更新显示。5. OLED 显示驱动让状态真正“看得见”5.1 HAL 库驱动 OLED 的初始化流程OLED 的驱动芯片是 SSD1306初始化流程是固定的上电、发送初始化命令序列、清屏、设置显示模式。用 HAL 库的 I2C 接口初始化代码大概长这样void OLED_Init(void) { HAL_Delay(100); // 等待 OLED 上电稳定 OLED_WriteCmd(0xAE); // 关闭显示 OLED_WriteCmd(0xD5); // 设置时钟分频 OLED_WriteCmd(0x80); OLED_WriteCmd(0xA8); // 设置多路复用率 OLED_WriteCmd(0x3F); OLED_WriteCmd(0xD3); // 设置显示偏移 OLED_WriteCmd(0x00); OLED_WriteCmd(0x40); // 设置起始行 OLED_WriteCmd(0x8D); // 电荷泵设置 OLED_WriteCmd(0x14); // 开启电荷泵 OLED_WriteCmd(0x20); // 设置内存寻址模式 OLED_WriteCmd(0x00); OLED_WriteCmd(0xA1); // 设置左右方向 OLED_WriteCmd(0xC8); // 设置上下方向 OLED_WriteCmd(0xDA); // 设置 COM 引脚配置 OLED_WriteCmd(0x12); OLED_WriteCmd(0x81); // 设置对比度 OLED_WriteCmd(0xCF); OLED_WriteCmd(0xD9); // 设置预充电周期 OLED_WriteCmd(0xF1); OLED_WriteCmd(0xDB); // 设置 VCOMH 电压 OLED_WriteCmd(0x40); OLED_WriteCmd(0xA4); // 全局显示开启 OLED_WriteCmd(0xA6); // 正常显示模式 OLED_WriteCmd(0xAF); // 开启显示 OLED_Clear(); }这段初始化序列看起来很长但每一行都有明确目的。最关键的是0x8D 和 0x14这两条命令它们开启电荷泵为 OLED 提供驱动电压。如果漏掉这两条屏幕可能完全不亮或者亮度极低。另一个关键是0x20 和 0x00设置内存寻址模式为水平寻址这样写入数据时会自动换行简化显示逻辑。5.2 显示内容的组织方式OLED 屏幕分辨率是 128x64分成 8 页每页 8 行像素。显示字符时我通常用8x16 像素的 ASCII 字库每个字符占一页的一半高度。这样一屏可以显示 4 行每行 16 个字符。显示按键和 LED 状态时我建议用这样的布局行号显示内容示例第 1 行标题KEY LED STATUS第 2 行按键状态KEY: PRESSED第 3 行LED 状态LED: ON第 4 行计数或时间COUNT: 42这种布局的好处是信息清晰一眼就能看到所有状态。如果你还想显示更多信息比如按键按下的次数、LED 闪烁的频率可以压缩到 6x8 像素的字库一屏能显示 8 行。5.3 刷新策略全屏刷新还是局部刷新OLED 的刷新方式有两种全屏刷新和局部刷新。全屏刷新是每次更新时把整个屏幕的显存重写一遍代码简单但速度慢I2C 速率 400kHz 下大概需要 20ms 到 30ms。局部刷新只更新变化的区域速度快但代码复杂。对于这个项目我建议用全屏刷新。因为状态变化不频繁按键按一次才刷新一次20ms 的刷新时间完全可以接受。而且全屏刷新代码简单不容易出 bug。如果你以后做需要高频刷新的项目比如显示波形再考虑局部刷新。刷新时要注意不要在中断里调用 OLED 刷新函数。I2C 通信需要时间在中断里阻塞会导致其他中断响应延迟。正确的做法是在主循环里检测状态变化变化了才刷新。6. 完整实操流程从 CubeMX 配置到代码烧录6.1 CubeMX 配置步骤打开 CubeMX新建工程选择 STM32F103C8T6。然后按以下步骤配置系统配置在 SYS 里把 Debug 设为 Serial Wire这样可以用 SWD 下载和调试。RCC 里把 HSE 设为 Crystal/Ceramic Resonator使用外部晶振。GPIO 配置找到按键对应的引脚比如 PA0设为 GPIO_Input然后在 GPIO 设置里把 Pull-up/Pull-down 设为 Pull-up。找到 LED 对应的引脚比如 PC13设为 GPIO_Output输出模式选 Push-Pull速度选 Low初始电平选 High这样上电时 LED 是灭的。I2C 配置在 Connectivity 里选 I2C1模式选 I2C速度设为 Fast Mode 400kHz。对应的引脚 PB6 和 PB7 会自动配置。时钟配置在 Clock Configuration 里把 HCLK 设为 72MHz这是 F103 的最高主频。I2C 时钟会自动计算确保在 400kHz 以内。生成代码Project Manager 里选 MDK-ARM勾选 Generate peripheral initialization as a pair of .c/.h files然后点 Generate Code。6.2 按键扫描函数的实现在 main.c 里添加按键扫描函数uint8_t Key_Scan(void) { static uint8_t keyReleased 1; if (keyReleased HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) GPIO_PIN_RESET) { HAL_Delay(10); // 消抖 if (HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) GPIO_PIN_RESET) { keyReleased 0; return 1; // 按键按下 } } else if (HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) GPIO_PIN_SET) { keyReleased 1; } return 0; // 无按键 }这个函数每次调用返回 1 表示按键按下返回 0 表示无按键。keyReleased变量确保按住按键时只触发一次不会连续触发。6.3 主循环逻辑主循环里做三件事扫描按键、更新 LED、刷新 OLED。uint8_t ledState 0; uint32_t pressCount 0; while (1) { if (Key_Scan()) { ledState !ledState; pressCount; HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, ledState ? GPIO_PIN_RESET : GPIO_PIN_SET); OLED_ShowString(0, 2, KEY: PRESSED ); OLED_ShowString(0, 4, ledState ? LED: ON : LED: OFF); OLED_ShowNum(0, 6, pressCount, 5); } HAL_Delay(10); }这段代码的逻辑很直白按键按下时翻转 LED 状态增加计数更新 OLED 显示。HAL_Delay(10)让主循环每 10ms 跑一次既降低了功耗也避免了按键扫描过于频繁。6.4 烧录与验证用 ST-Link 连接开发板在 Keil 里点 Download 烧录。烧录成功后按一下复位键OLED 应该显示初始状态。按下按键LED 翻转OLED 上的状态同步更新。如果你用的是 Proteus 仿真需要注意 Proteus 里的 OLED 模型和实际硬件有差异I2C 时序可能对不上。我建议先用真实硬件跑通再用 Proteus 验证电路逻辑。热词里提到的“KeilSTM32Proteus 的 LED 灯点亮”是可行的但 OLED 仿真容易出问题不如直接买一块十几块钱的开发板来得快。7. 常见问题与排查技巧实录7.1 OLED 不亮或显示乱码这是最常见的问题排查顺序如下现象可能原因解决方法完全不亮电荷泵未开启检查初始化序列里是否有 0x8D 和 0x14完全不亮I2C 地址错误用 I2C 扫描程序确认地址是 0x78 还是 0x7A显示乱码字库取模方式不对确认取模软件设置为“列行式”或“行列式”与代码匹配显示偏移寻址模式设置错误检查 0x20 命令后的参数是否为 0x00部分区域不亮显存未清空初始化后调用 OLED_Clear()我踩过最坑的一次是 I2C 地址搞错了。SSD1306 的地址是 0x78 或 0x7A取决于模块上的电阻配置。有些模块标称 0x78实际是 0x7A。用 HAL 库的HAL_I2C_IsDeviceReady()函数扫描一下就能确认。7.2 按键不灵敏或误触发按键问题的排查思路完全不响应用万用表量按键按下时引脚电压是否变化。如果不变检查按键接线和 GPIO 配置。按一次触发多次消抖时间不够加到 20ms。如果还不行检查按键质量劣质按键抖动时间可能超过 20ms。偶尔误触发引脚悬空或上拉电阻太大改用内部上拉或加 10kΩ 外部上拉。按住时连续触发状态机逻辑有问题检查keyReleased变量是否正确复位。热词里提到的“同一根矩阵线路上的多个按键集体失效”是矩阵键盘的问题和这个独立按键项目无关。但如果你以后做矩阵键盘那个问题的根源通常是行线或列线虚焊用万用表逐段测量就能找到。7.3 LED 亮度异常或闪烁LED 问题的排查亮度太暗限流电阻太大换小一档。或者 GPIO 输出模式配置错误检查是否为推挽输出。亮度太亮或烧毁限流电阻太小或没接立即断电检查。闪烁不稳定电源供电不足USB 口供电可能只有 500mA如果接了多个外设电压会跌落。换一个独立供电的 USB Hub 或者用外部电源。7.4 程序跑飞或卡死如果程序运行一段时间后卡死优先检查栈溢出OLED 刷新函数里用了大数组检查栈大小设置。在 Keil 的 startup 文件里可以改 Stack_Size。I2C 死锁I2C 通信失败后没有超时机制程序一直等待。在 I2C 读写函数里加超时判断超时后重新初始化 I2C。中断优先级冲突如果用了多个中断检查优先级配置。I2C 中断优先级不要设太高否则会阻塞其他中断。8. 从状态显示到可观测开发习惯这个项目做完之后你手里有了一个能实时显示按键和 LED 状态的工具。但它的价值不止于此。你可以在这个基础上继续扩展把按键状态换成传感器数据比如 DHT11 的温湿度、BH1750 的光照强度OLED 上就能显示环境监测数据。热词里提到的“STM32 环境监测系统 DHT11 BH1750 MQ-2 OLED”就是这个思路的延伸。把 LED 换成继电器就能控制家电。把按键换成旋转编码器就能做菜单导航。但最核心的习惯是先让状态可见再写控制逻辑。我见过太多项目代码写了几百行调试全靠串口打印和猜。而有了 OLED 状态显示你一眼就能看出程序卡在哪一步、哪个变量不对、哪个条件没满足。这个习惯能帮你省下大量调试时间。最后分享一个小技巧在 OLED 上留一行显示HAL_GetTick()的值。这是一个毫秒级的时间戳程序跑飞时如果这个值还在变说明主循环还在跑如果不变了说明程序卡死了。这个简单的技巧能帮你快速定位是硬件问题还是软件问题。这个项目后续还可以这样扩展加一个定时器中断让 LED 自动闪烁OLED 上显示闪烁频率加一个串口把按键次数发送到电脑加一个 EEPROM把计数保存下来断电不丢失。每一步扩展都是在验证你对 GPIO、中断、通信的理解。等你把这些都跑通了再回头看这个“按键和 LED 状态显示”的项目你会发现它其实是一个微缩版的完整嵌入式系统。