1. 从“点灯”到“看见状态”：为什么这个项目值得认真做

很多人第一次接触 STM32 或者任何一款单片机，都是从“点亮一颗 LED”开始的。代码烧进去，灯亮了，心里一阵激动，然后……就不知道下一步该干什么了。灯亮着，但它为什么亮？程序现在跑到哪一行了？我按一下按键，它到底有没有检测到？这些问题在“点灯”阶段是回答不了的。而“把按键和 LED 状态显示出来”这个项目，恰恰是跨过那道门槛的关键一步——它让你第一次真正“看见”程序在干什么。

这个项目的核心目标很朴素：用一颗 LED 表示某种输出状态，用一个按键作为输入，再通过一块 OLED 屏幕把当前按键的状态、LED 的状态、甚至按键按下的次数实时显示出来。听起来简单，但它串联起了嵌入式开发中最基础的几个环节：GPIO 输入输出、按键消抖、状态机逻辑、OLED 显示驱动、以及主循环的任务调度。对于刚学完 GPIO 点灯、还在迷糊“HAL_GPIO_ReadPin 到底怎么用”的朋友来说，这是一个绝佳的练手项目。它不需要复杂的传感器，也不需要联网，手头一块 STM32F103C8T6 最小系统板、一个按键、一个 LED、一块 0.96 寸 I2C OLED 就能全部搞定。

我之所以说这个项目值得认真做，是因为它解决了一个非常实际的痛点：调试可视化。在没有串口、没有调试器的情况下，OLED 就是你的“眼睛”。你可以把变量值、状态标志、计数器统统打印到屏幕上，比盯着 LED 猜要高效得多。而且，当你把按键状态和 LED 状态同时显示出来的时候，你会直观地看到“按下—消抖—确认—执行—反馈”这一整套流程在时间轴上的展开，这对理解中断、轮询、状态机这些概念有极大的帮助。

接下来的内容，我会从整体设计思路开始拆解，然后深入到 GPIO 模式选择、按键电路设计、OLED 驱动移植、状态显示逻辑这些核心细节，再给出完整的实操步骤和代码框架，最后把我自己踩过的坑和排查技巧整理出来。无论你是刚学完 HAL 库点灯的新手，还是想复习一下基础外设的老手，应该都能从中找到有用的东西。

2. 整体设计思路与方案选型

2.1 为什么选“按键 + LED + OLED”这个组合

在嵌入式入门阶段，输入和输出是最基本的两个概念。按键代表输入，LED 代表输出，而 OLED 代表状态可视化。这三者组合起来，就构成了一个最小的“感知—决策—执行—反馈”闭环。你按下按键，程序读取到电平变化，经过消抖确认，改变 LED 的亮灭状态，同时把当前状态刷新到 OLED 上。整个过程不需要任何通信协议栈，也不需要操作系统，裸机主循环就能跑起来。

相比单纯的按键控制 LED，加入 OLED 之后，项目的复杂度提升了一个档次，但这个提升是“有意义的复杂度”。你需要考虑 I2C 通信、显存管理、字符编码、刷新频率等问题。这些问题在实际产品中都会遇到，提前在这样一个简单项目里踩一遍，比以后在复杂项目里抓瞎要好得多。

2.2 轮询还是中断：按键检测方式的取舍

按键检测有两种主流方式：轮询和中断。轮询就是在主循环里不断读取 GPIO 电平，中断则是配置外部中断，按键按下时触发中断服务函数。两种方式各有优劣，我一般建议在这个项目里先用轮询，原因有三点。

第一，轮询的逻辑更直观。你可以在主循环里清楚地看到“读按键—消抖—判断—执行”的完整流程，对于理解程序执行顺序非常有帮助。第二，轮询不会引入中断优先级、中断嵌套这些复杂概念，降低了初学者的心智负担。第三，OLED 刷新本身也需要在主循环里完成，如果按键用中断，那么中断服务函数里就不适合做 OLED 刷新（I2C 通信耗时较长），还是得靠主循环来处理，反而增加了逻辑复杂度。

当然，轮询的缺点也很明显：如果主循环里有延时或者阻塞操作，按键响应就会变慢。但在我们这个项目里，主循环的任务很轻，轮询完全够用。等你把轮询版本跑通了，再尝试用中断方式重写一遍，对比两者的差异，收获会更大。

2.3 OLED 选型：I2C 还是 SPI

市面上常见的 0.96 寸 OLED 模块有 I2C 和 SPI 两种接口。I2C 版本只需要两根信号线（SCL、SDA），接线简单，占用 IO 少，但刷新速度相对慢一些。SPI 版本需要四根线以上，速度快，但接线复杂。对于这个项目来说，显示内容不多，刷新率要求不高，I2C 版本是更合适的选择。

不过 I2C 版本有一个经典问题：地址冲突和上拉电阻。有些模块背面有电阻可以选择 I2C 地址（0x78 或 0x7A），有些模块自带 4.7k 上拉电阻，有些则没有。如果你用 STM32 的硬件 I2C，需要确认引脚配置和上拉情况；如果用软件模拟 I2C，则灵活性更高，但时序需要自己保证。我个人的习惯是：先用软件模拟 I2C 把屏幕点亮，确认硬件没问题之后，再决定是否切换到硬件 I2C。这样可以把硬件问题和软件问题分开排查。

2.4 状态显示的内容设计

OLED 上显示什么内容，直接决定了这个项目的实用价值。我建议至少显示以下几项：

• 按键当前电平：实时显示 PA0 引脚的电平状态（0 或 1），让你看到按下和松开时的变化。
• 按键确认状态：经过消抖后的稳定状态，只有这个状态才用来触发逻辑。
• LED 当前状态：显示 LED 是亮还是灭，与 GPIO 输出寄存器的值对应。
• 按键按下次数：累计计数，用来验证每次按下是否被正确识别。
• 运行时间：可以用定时器计数，显示系统运行了多少毫秒，方便观察刷新频率。

把这些信息组织成几行文本，每 100 毫秒刷新一次，既不会闪烁，也能及时反映状态变化。刷新频率太高会占用 CPU 时间，太低则感觉迟钝，100 毫秒是一个比较舒服的平衡点。

3. 核心细节解析与实操要点

3.1 GPIO 模式选择：输入和输出到底怎么配

STM32 的 GPIO 有 8 种工作模式，初学者最容易在这里迷糊。对于这个项目，我们只需要关心两种：输入模式和输出模式。

按键连接的那一端，GPIO 配置为输入模式。具体来说，如果按键一端接 GPIO，另一端接 GND，那么 GPIO 需要配置为上拉输入（Pull-up）。这样按键未按下时，引脚被内部上拉电阻拉到高电平；按下时，引脚被拉到 GND，读到低电平。如果你用的是外部上拉电阻，那么 GPIO 可以配置为浮空输入（Floating），但我不推荐新手这么做，因为浮空输入在没有外部上拉的情况下，电平会飘忽不定，读出来的值随机变化，很容易让人怀疑人生。

LED 连接的那一端，GPIO 配置为推挽输出（Push-Pull）。推挽输出可以强驱动高电平和低电平，适合驱动 LED。如果是开漏输出，高电平需要外部上拉，驱动能力弱，不适合直接驱动 LED。至于输出速度，LED 这种应用选低速就够了，没必要选高速，高速会增加功耗和电磁干扰。

这里有一个细节：LED 的接法决定了逻辑电平。如果 LED 阳极接 VCC，阴极接 GPIO，那么 GPIO 输出低电平时 LED 亮，输出高电平时 LED 灭。如果 LED 阳极接 GPIO，阴极接 GND，则相反。我建议在代码里用宏定义把“亮”和“灭”对应到具体的电平，这样以后改电路也不用改逻辑代码。

#define LED_ON() HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_RESET) #define LED_OFF() HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_SET) #define LED_TOGGLE() HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13)

3.2 按键消抖：为什么你按一次，程序却认为你按了十次

机械按键在按下和松开的瞬间，触点会产生抖动，电平会在高和低之间快速跳变几次，持续时间通常在 5 到 20 毫秒之间。如果你直接在主循环里读电平，一次按下可能会被识别成多次按下。这就是为什么很多人写按键程序时，发现按一下 LED 闪了好几次。

消抖的方法有两种：硬件消抖和软件消抖。硬件消抖是在按键两端并联一个 0.1uF 的电容，利用电容的充放电特性吸收抖动。软件消抖则是在检测到电平变化后，延时 10 到 20 毫秒再读一次，如果电平仍然相同，才确认状态变化。

我一般用软件消抖，因为不需要额外元件，而且逻辑清晰。下面是一个典型的消抖状态机：

typedef enum { KEY_STATE_RELEASED, KEY_STATE_DEBOUNCE_PRESS, KEY_STATE_PRESSED, KEY_STATE_DEBOUNCE_RELEASE } KeyState; KeyState keyState = KEY_STATE_RELEASED; uint32_t keyTick = 0; uint8_t keyPressedFlag = 0; void Key_Scan(void) { uint8_t pinLevel = HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0); switch (keyState) { case KEY_STATE_RELEASED: if (pinLevel == GPIO_PIN_RESET) { keyState = KEY_STATE_DEBOUNCE_PRESS; keyTick = HAL_GetTick(); } break; case KEY_STATE_DEBOUNCE_PRESS: if (HAL_GetTick() - keyTick >= 20) { if (pinLevel == GPIO_PIN_RESET) { keyState = KEY_STATE_PRESSED; keyPressedFlag = 1; } else { keyState = KEY_STATE_RELEASED; } } break; case KEY_STATE_PRESSED: if (pinLevel == GPIO_PIN_SET) { keyState = KEY_STATE_DEBOUNCE_RELEASE; keyTick = HAL_GetTick(); } break; case KEY_STATE_DEBOUNCE_RELEASE: if (HAL_GetTick() - keyTick >= 20) { if (pinLevel == GPIO_PIN_SET) { keyState = KEY_STATE_RELEASED; } else { keyState = KEY_STATE_PRESSED; } } break; } }

这个状态机的好处是非阻塞。它不会用HAL_Delay卡住整个程序，而是靠HAL_GetTick()来判断时间。这样主循环可以同时处理 OLED 刷新和其他任务，不会因为按键消抖而卡顿。

3.3 OLED 驱动移植：从厂商例程到自己的工程

OLED 驱动通常厂商会提供一份例程，里面包含了初始化序列、写命令、写数据、设置光标、显示字符等函数。你需要做的就是把这份例程移植到自己的工程里，并适配你的 I2C 接口。

如果你用的是软件模拟 I2C，那么只需要修改 SCL 和 SDA 的 GPIO 定义，以及延时函数。如果你用的是硬件 I2C，那么需要把底层的读写函数替换成 HAL 库的HAL_I2C_Mem_Write等函数。

移植过程中最容易出问题的地方是初始化序列。OLED 的初始化命令是一串固定的字节序列，不同厂家的屏幕可能略有差异。如果你发现屏幕不亮，首先检查初始化序列是否完整发送，其次检查 I2C 地址是否正确。0.96 寸 OLED 的 I2C 地址通常是 0x78（8 位地址）或 0x3C（7 位地址），具体要看模块背后的电阻配置。

还有一个常见问题是显示花屏。花屏通常是因为显存数据错乱或者刷新时序不对。解决方法是先清空显存，再写入固定图案测试。如果固定图案显示正常，说明驱动没问题，问题出在字符编码或者刷新逻辑上。

3.4 状态显示逻辑：把变量变成屏幕上的文字

OLED 显示字符需要用到字库。常用的做法是用 PCtoLCD2002 之类的工具生成字模数组，然后写一个显示字符串的函数。对于这个项目，我们只需要显示 ASCII 字符和数字，所以取模方式选择“ASCII 字符”即可。

显示逻辑可以这样组织：定义一个Display_Update()函数，在里面调用 OLED 的清屏、设置光标、显示字符串等函数，把当前的状态变量格式化后输出。例如：

void Display_Update(void) { char buf[20]; OLED_Clear(); OLED_ShowString(0, 0, "Key Raw:"); sprintf(buf, "%d", HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0)); OLED_ShowString(64, 0, buf); OLED_ShowString(0, 2, "Key Stable:"); sprintf(buf, "%d", keyState == KEY_STATE_PRESSED ? 1 : 0); OLED_ShowString(80, 2, buf); OLED_ShowString(0, 4, "LED:"); sprintf(buf, "%d", HAL_GPIO_ReadPin(GPIOC, GPIO_PIN_13)); OLED_ShowString(40, 4, buf); OLED_ShowString(0, 6, "Count:"); sprintf(buf, "%lu", pressCount); OLED_ShowString(48, 6, buf); }

注意sprintf在嵌入式里会占用一定的栈空间和 Flash 空间，如果资源紧张，可以用自己写的整数转字符串函数代替。另外，OLED 刷新频率不要太高，我一般放在主循环里，配合一个 100 毫秒的定时标志，每 100 毫秒刷新一次就够了。

4. 完整实操流程与核心环节实现

4.1 硬件准备与接线

先把手头的元件清点一下：

接线方案如下：

• OLED VCC 接 3.3V，GND 接 GND，SCL 接 PB6，SDA 接 PB7（硬件 I2C1）或者任意两个 GPIO（软件模拟）。
• 按键一端接 PA0，另一端接 GND。如果使用内部上拉，不需要外部电阻；如果使用外部上拉，PA0 与 3.3V 之间接 10kΩ 电阻。
• LED 阳极通过 220Ω 电阻接 PC13，阴极接 GND。这样 PC13 输出高电平时 LED 亮。

注意：STM32F103C8T6 的 PC13 引脚驱动能力有限，建议 LED 电流不要超过 3mA，220Ω 电阻在 3.3V 下电流约 5mA，稍微偏大，可以用 470Ω 或 1kΩ。我实测 1kΩ 亮度也够看。

4.2 工程创建与 GPIO 初始化

用 STM32CubeMX 创建工程，选择 STM32F103C8T6，配置时钟树为 72MHz。然后配置引脚：

• PA0：GPIO_Input，Pull-up
• PC13：GPIO_Output，Push-Pull，Low Speed
• PB6：I2C1_SCL
• PB7：I2C1_SDA

如果使用软件模拟 I2C，则把 PB6 和 PB7 配置为普通 GPIO 输出，在代码里手动翻转电平。

生成代码后，在main.c里添加 OLED 驱动文件和按键扫描文件。OLED 驱动可以从厂商例程里复制oled.c和oled.h，然后修改 I2C 底层函数。

4.3 主循环逻辑与时间片调度

主循环的结构如下：

int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_I2C1_Init(); OLED_Init(); OLED_Clear(); OLED_ShowString(0, 0, "System Ready"); HAL_Delay(500); uint32_t lastDisplayTick = 0; uint32_t lastKeyTick = 0; while (1) { uint32_t now = HAL_GetTick(); if (now - lastKeyTick >= 5) { lastKeyTick = now; Key_Scan(); } if (keyPressedFlag) { keyPressedFlag = 0; pressCount++; LED_TOGGLE(); } if (now - lastDisplayTick >= 100) { lastDisplayTick = now; Display_Update(); } } }

这里用了三个时间片：按键扫描每 5 毫秒一次，按键处理在主循环里立即执行，显示刷新每 100 毫秒一次。这种“时间片轮询”的结构在裸机程序里非常常见，既保证了实时性，又不会让某个任务阻塞其他任务。

4.4 参数计算与调试观察

按键消抖时间设为 20 毫秒，这个值是根据机械按键的典型抖动时间（5 到 20 毫秒）来定的。如果发现按键偶尔失灵，可以适当增大到 30 毫秒；如果发现响应太慢，可以减小到 10 毫秒。我实测 20 毫秒在大多数轻触按键上表现稳定。

显示刷新周期设为 100 毫秒，对应 10Hz 的刷新率。人眼对 10Hz 的刷新基本感觉不到闪烁，同时 CPU 占用也很低。如果你需要更实时的观察，可以提高到 50 毫秒，但要注意 OLED 的 I2C 通信时间。以 400kHz 的 I2C 速率计算，传输一帧 128x64 的显存数据需要约 20 毫秒，所以刷新周期不能低于这个值，否则会丢帧。

调试的时候，我习惯先用 LED 验证按键逻辑：按一下 LED 翻转一次，说明按键检测和消抖没问题。然后再接入 OLED，观察屏幕上的数值变化。如果 OLED 不亮，先用万用表量一下 VCC 和 GND 是否接反，再检查 SCL 和 SDA 是否有波形。用示波器看 I2C 波形是最直接的排查方法，如果没有示波器，可以用逻辑分析仪，几十块钱的那种就够用。

5. 常见问题与排查技巧实录

5.1 按键按下没反应，或者反应混乱

这是最常见的问题，原因通常有三个：上拉没配置、消抖没做、引脚选错。

先检查 GPIO 初始化代码，确认按键引脚配置为 Pull-up 输入。如果用的是浮空输入，又没有外部上拉电阻，电平会随机跳动。其次检查消抖逻辑，如果消抖时间太短，抖动会被误判为多次按下；如果消抖时间太长，快速按下会被忽略。最后确认引脚编号和电路板上的丝印是否一致，有些最小系统板的 PA0 旁边还接了其他元件，可能会影响电平。

5.2 OLED 不亮或花屏

OLED 不亮的原因比较多，我整理了一个排查表：

我遇到过一次花屏，排查了半天发现是 I2C 上拉电阻没接。STM32 的硬件 I2C 引脚是开漏输出，必须外部上拉才能输出高电平。有些 OLED 模块自带 4.7k 上拉电阻，有些没有，买的时候要看清楚。如果没有，自己在 SCL 和 SDA 上各接一个 4.7k 到 3.3V 即可。

5.3 程序跑飞或卡死

如果程序烧进去之后没反应，先检查启动文件和时钟配置。STM32F103C8T6 的外部晶振是 8MHz，经过 PLL 倍频到 72MHz。如果时钟配置错误，系统时钟会不对，导致延时函数和 I2C 时序全部乱套。

另外，HAL_Delay依赖 SysTick 中断，如果中断优先级配置不当，或者在其他中断里调用了HAL_Delay，会导致死锁。我建议在中断服务函数里只做标志位设置，具体处理放到主循环里做。

5.4 独家避坑经验

第一个坑：不要在主循环里用HAL_Delay做消抖。HAL_Delay是阻塞的，会卡住整个程序，导致 OLED 刷新和按键响应都变慢。用HAL_GetTick做非阻塞延时才是正道。

第二个坑：OLED 的 I2C 地址要确认清楚。有些模块标注 0x78，有些标注 0x3C，其实 0x78 是 8 位地址，0x3C 是 7 位地址，HAL 库用的是 7 位地址，所以填 0x3C。如果你填了 0x78，通信会失败。

第三个坑：按键计数变量要用volatile修饰。如果这个变量在中断里被修改，在主循环里被读取，不加volatile编译器可能会优化掉读取操作，导致计数不更新。虽然这个项目里按键是轮询的，但养成这个习惯没坏处。

第四个坑：LED 限流电阻不要省。我见过有人直接把 LED 接在 GPIO 和 GND 之间，结果 LED 亮了但 GPIO 发热严重，长期运行可能损坏引脚。加一个 1kΩ 电阻，电流降到 3mA 左右，亮度足够，安全可靠。

6. 从“看见状态”到“理解系统”的进阶思路

把按键和 LED 状态显示出来之后，这个项目其实还可以继续扩展。比如，你可以加入定时器中断，用硬件定时器来触发按键扫描和显示刷新，把主循环解放出来处理更复杂的逻辑。你也可以加入串口输出，把状态信息同时打印到电脑上，方便记录和分析。还可以加入状态机，让按键实现单击、双击、长按等不同功能，OLED 上显示当前的操作模式。

我个人的体会是，嵌入式开发最难的不是写代码，而是建立对系统运行状态的直觉。你知道程序在干什么，你知道每个变量当前的值，你知道每个外设的状态，这种“看见”的能力，比会调用多少库函数重要得多。这个项目就是一个起点，它让你第一次真正看见程序在干什么。等你把这一套跑通了，再去学中断、DMA、RTOS，心里就有底了。

最后分享一个小技巧：在 OLED 上留一行显示HAL_GetTick()的值，你会直观地看到系统运行了多少毫秒。当你调试延时逻辑或者超时判断的时候，这一行数字比任何调试器都管用。