STM32F103C8T6驱动OLED屏：从硬件连接到菜单系统的嵌入式开发实践

1. 项目缘起：为什么是STM32F103C8T6与OLED的组合？

如果你手头有一块“蓝色药丸”（Blue Pill，STM32F103C8T6最小系统板的俗称），想给它找个能说会道的“嘴巴”，那么一块小巧的OLED显示屏几乎是首选。这个组合在电子爱好者、学生和嵌入式开发者中流行了十多年，至今依然是入门和验证想法的黄金搭档。我最初接触这个组合，是为了做一个能显示温度和湿度的桌面小摆件，结果一发不可收拾，从简单的字符显示玩到了动画和菜单。

STM32F103C8T6这颗芯片，属于ARM Cortex-M3内核，72MHz主频，64KB Flash，20KB RAM，外设丰富。它的核心优势在于性价比和庞大的社区生态。你几乎能在网上找到关于它的任何问题的答案。而OLED屏，特别是0.96寸或1.3寸的I2C/SPI接口型号，功耗低、对比度高、无需背光，在暗环境下显示效果极佳，非常适合作为微型设备的交互窗口。

这个组合解决了嵌入式开发中的一个核心需求：低成本、低功耗的人机交互界面。无论是显示传感器数据、系统状态、调试信息，还是构建简单的用户菜单，它都能胜任。更重要的是，驱动OLED的过程，几乎涵盖了嵌入式开发的所有基础技能：GPIO控制、硬件或软件I2C/SPI通信、时序理解、内存管理（字库、图像缓存）以及状态机编程（用于菜单）。所以，搞懂它，意义远不止于点亮一块屏幕。

2. 硬件连接：从原理图到面包板

动手之前，我们必须理清硬件连接。STM32F103C8T6与OLED的通信主要有两种方式：I2C和SPI。I2C接线简单，但刷新速度慢；SPI速度快，适合动画或全屏刷新，但占用引脚多。对于大多数显示文本和简单图形的应用，I2C足矣。我们以最常见的4针I2C接口OLED（0.96寸，SSD1306驱动芯片）为例。

核心连接只有四根线：

• VCC： 接3.3V。特别注意：虽然有些OLED模块标称支持5V，但STM32的IO口是3.3V电平，为保险起见，强烈建议统一使用3.3V供电，避免电平不匹配损坏芯片。
• GND： 接地。
• SCL： 时钟线，接STM32的某个GPIO。我们选择PB6，因为它是STM32F103C8T6默认的I2C1时钟引脚。
• SDA： 数据线，接STM32的某个GPIO。我们选择PB7，它是I2C1的数据引脚。

为什么选I2C1（PB6， PB7）？一方面，这是芯片设计上外设I2C1的复用功能引脚，使用硬件I2C效率更高、更稳定。另一方面，在最小系统板上，这两个引脚通常没有被其他关键功能占用，方便使用。

注意：市面上有些OLED模块的I2C地址默认为0x78（写地址）或0x7A，这对应7位地址0x3C。这是SSD1306的常见地址。如果你的屏幕不亮，首先要用逻辑分析仪或代码扫描I2C总线，确认地址是否正确。

除了主控和屏幕，你还需要一个ST-Link或DAP-Link之类的调试下载器，以及若干杜邦线。硬件连接图在脑海里应该是清晰的：调试器连接SWD接口（SWCLK->PA14， SWDIO->PA13， GND， 3.3V），OLED的四根线按上述对应连接。确保共地，这是所有通信的基础。

3. 软件工程搭建：HAL库、标准库还是LL库？

连接好硬件，下一步是创建软件工程。这里你会面临第一个选择：用什么库？主流有三种：标准库（Standard Peripheral Library）、HAL库（Hardware Abstraction Layer）和LL库（Low-Layer）。

• 标准库： 经典，直接操作寄存器，代码效率高，但STM32已停止更新，对新学者来说寄存器操作略显晦涩。
• HAL库： ST主推，抽象程度高，跨系列芯片移植方便，配合STM32CubeMX工具能快速生成初始化代码，但代码体积大，执行效率相对较低。
• LL库： 可以看作是HAL库的“轻量级”补充，它提供了更接近寄存器的操作接口，可以和HAL库混合使用，在需要高效操作的地方用LL。

对于新手和快速开发，我强烈推荐“STM32CubeMX + HAL库”的组合。它能图形化配置时钟、引脚和外设，自动生成工程框架，让你避开繁琐的底层配置，专注于应用逻辑。这也是当前社区最主流、资料最全的方式。

具体操作：

1. 打开STM32CubeMX，新建工程，选择芯片型号STM32F103C8Tx。
2. 配置时钟树（RCC）：在RCC配置中，将High Speed Clock (HSE)设为Crystal/Ceramic Resonator。这告诉芯片，我们使用外部高速晶振（通常是8MHz）。然后转到Clock Configuration标签页，将系统时钟源选为PLLCLK，输入频率选HSE，然后通过调节PLL倍频系数，将HCLK（系统时钟）设置为72MHz。这一步是让芯片跑在最高性能状态。
3. 配置I2C1：在引脚图界面，找到PB6和PB7，分别将其功能设置为I2C1_SCL和I2C1_SDA。在左侧Connectivity菜单下点击I2C1，将I2C Mode设置为I2C，参数通常保持默认（标准模式，100kHz）。对于OLED，100kHz的速率完全足够。
4. 配置调试接口：在System Core->SYS中，将Debug设置为Serial Wire。这非常重要，否则芯片可能无法再次下载程序。
5. 生成工程：在Project Manager标签页，设置工程名称、路径、选择IDE（MDK-ARM V5 for Keil）。在Code Generator中，建议勾选“Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral”，这样代码结构更清晰。最后点击GENERATE CODE。

至此，一个包含HAL库、系统时钟初始化、I2C1初始化的Keil工程就生成了。你的main.c文件中，SystemClock_Config()和MX_I2C1_Init()函数已经就绪。

4. OLED驱动移植：从“拿来主义”到理解精髓

工程有了，接下来需要OLED的驱动程序。我们不需要从零编写SSD1306的驱动，网上有大量成熟的开源驱动库，例如“中景园电子”提供的例程，或者GitHub上搜索“SSD1306 HAL”。我们的工作是将这些驱动文件适配到我们的工程中。

通常，一个最简化的OLED驱动包含两个文件：oled.c和oled.h，以及一个字库文件（通常是oledfont.h）。移植步骤如下：

1. 添加文件：将oled.c、oled.h、oledfont.h复制到你的工程文件夹，并在Keil的工程管理器中将其添加到项目。
2. 修改硬件依赖：打开oled.c，找到I2C写数据/命令的函数。它内部会调用HAL库的I2C发送函数。你需要确保它使用的是我们初始化好的hi2c1对象。通常函数原型类似void OLED_WR_Byte(uint8_t dat, uint8_t cmd)。其内部实现可能是：

   HAL_I2C_Mem_Write(&hi2c1, OLED_ADDRESS, reg, I2C_MEMADD_SIZE_8BIT, &data, 1, HAL_MAX_DELAY);

   检查&hi2c1这个句柄是否与CubeMX生成的全局变量名一致。同时确认OLED_ADDRESS（通常是0x78）是否正确。
3. 初始化序列：驱动中会有一个OLED_Init()函数，里面包含了一长串发送给SSD1306的初始化命令。这些命令设置了对比度、显示模式、扫描方向、起始行等。除非你非常了解SSD1306的数据手册，否则不要随意修改这个序列。它是屏幕能正常点亮的关键。
4. 提供基础API：驱动库应至少提供以下几个核心函数，我们在应用层会频繁调用：
   • OLED_Init()： 初始化屏幕。
   • OLED_Clear()： 清屏。
   • OLED_ShowChar(uint8_t x, uint8_t y, uint8_t chr)： 在指定坐标（x行， y列，注意坐标体系）显示一个ASCII字符。
   • OLED_ShowString(uint8_t x, uint8_t y, uint8_t *chr)： 显示字符串。
   • OLED_ShowNum(uint8_t x, uint8_t y, uint32_t num, uint8_t len)： 显示数字。
   • OLED_Refresh()： 对于有缓冲区的驱动，此函数将内存缓冲区的内容一次性刷新到屏幕。这是实现无闪烁刷新（双缓冲思想）的关键。

踩坑记录：我曾遇到一个驱动库，显示中文总是乱码。排查后发现是oledfont.h中的字库编码与我的字符串编码不一致。我代码里用的是UTF-8，而字库是GB2312编码的。解决方法要么转换字符串编码，要么使用UTF-8格式的字库。这是做中文显示时必须注意的细节。

移植完成后，在main.c的while(1)循环前调用OLED_Init()，然后调用OLED_ShowString(0, 0, "Hello World!")。编译、下载、复位，你的OLED屏幕上应该就会出现问候语了。这是第一个里程碑。

5. 核心显示功能实现：从字符到图形

点亮屏幕只是第一步，接下来我们要让它显示有用的信息。这涉及到坐标管理、数据格式转换和刷新策略。

5.1 坐标系统与显示API的灵活运用

大多数OLED驱动将屏幕划分为若干“页”（Page）。以128x64分辨率的屏幕为例，通常沿Y方向分为8页（Page0-Page7），每页8行像素，共64行；X方向128列。OLED_ShowChar等函数里的x参数通常指第几页（0~7），y参数指该页中的第几列（0~127）。

显示变量数据：这是最常见的需求。例如从DHT11读取了温湿度，需要显示。你需要先将整数或浮点数转换为字符串。可以使用sprintf，但它在资源紧张的单片机上开销较大。更安全的方法是使用自定义的转换函数，或者HAL库自带的HAL_UART_Transmit（如果你开启了串口）配合printf重定向，但这里我们直接用驱动提供的OLED_ShowNum。

float temperature = 25.6; float humidity = 60.3; // 显示温度 OLED_ShowString(0, 0, "Temp:"); OLED_ShowNum(0, 40, (uint32_t)temperature, 2); // 显示整数部分 OLED_ShowChar(0, 56, '.'); // 显示小数点 OLED_ShowNum(0, 64, (uint32_t)((temperature - (uint32_t)temperature) * 10), 1); // 显示一位小数 OLED_ShowString(0, 80, "C"); // 同理显示湿度...

显示中文与自定义图形：这需要用到取模软件。将中文字符或小图标保存为位图，利用取模软件（如PCtoLCD2002）生成字模数组，放入oledfont.h或单独的bmp.h中。驱动库中需要有一个OLED_DrawBMP或OLED_ShowPicture函数，能够将位图数组数据写入显存。这个过程考验的是耐心和细心，要确保取模方式（逐行/逐列、顺向/逆向）与驱动函数的读取方式匹配。

5.2 动态刷新与避免闪烁

直接反复调用OLED_ShowString在原位置更新数字，比如一个变化的计数器，会导致屏幕局部频繁刷新，可能产生闪烁。优化方案是局部刷新或双缓冲。

• 局部刷新：在更新数字前，先用背景色（黑色）重写之前区域的旧数字，再写入新数字。或者，如果新旧数字位数固定，可以只更新变化的位。
• 双缓冲：这是更彻底的解决方案。在内存中开辟一块和屏幕显存一样大的缓冲区（对于128x64单色屏，是128 * 64 / 8 = 1024字节）。所有绘图操作都针对这个缓冲区进行。操作完成后，调用一次OLED_Refresh()或OLED_Update()，将整个缓冲区数据通过I2C一次性发送到屏幕。由于发送过程很快（即便用I2C，1024字节也在可接受范围内），屏幕几乎是一次性完成更新，完全避免了闪烁。这是实现流畅动画和复杂UI的基础。你需要评估你的STM32F103C8T6的RAM是否足够（20KB中拿出1KB做缓冲是可行的）。

在我的一个天气时钟项目中，我使用了双缓冲。主循环里，传感器数据更新后，先在内存缓冲区绘制所有元素（时间、日期、温度、湿度、天气图标），绘制完成后，一次性刷新到OLED。视觉体验非常稳定。

6. 进阶应用：菜单系统的设计与实现

当功能变多，需要通过屏幕进行选择时，菜单系统就变得必要。一个简单的菜单可以理解为状态机。

设计思路：

1. 定义菜单结构体：每个菜单项包含显示文本、上级菜单索引、下级菜单索引、以及一个执行函数指针（当该项被选中时调用）。

   typedef struct { uint8_t currentIndex; // 当前菜单项索引 uint8_t itemCount; // 本层菜单项总数 char *displayStr[MENU_MAX_ITEMS]; // 显示字符串 void (*func[MENU_MAX_ITEMS])(); // 对应功能函数 uint8_t parentIndex; // 父菜单索引 uint8_t childIndex[MENU_MAX_ITEMS]; // 子菜单索引 } Menu_t;

2. 初始化菜单：预先定义好所有菜单层级和关系，形成一个菜单树。
3. 交互逻辑：使用一个或两个按键（上/下， 确认/返回）。在while(1)循环中检测按键。
   • 上下键：改变currentIndex，高亮显示当前选中的项。
   • 确认键：判断当前项是否有子菜单。有则进入子菜单（切换当前菜单上下文）；没有则执行对应的func函数。
   • 返回键：返回到父菜单。
4. 显示刷新：根据当前的菜单上下文（哪一层，选中第几项），调用OLED显示函数绘制菜单列表，并高亮currentIndex指向的项。

实现菜单的关键在于清晰的状态管理和与显示驱动的解耦。菜单逻辑只负责维护状态（当前在哪，选中谁），显示驱动根据状态进行绘制。这样，更换不同的显示设备（比如换成LCD）时，只需重写绘制部分，菜单逻辑可以复用。

经验分享：在菜单实现中，避免在按键检测函数里直接进行复杂的OLED绘图。更好的做法是，设置一个menuRefreshFlag标志位。按键动作只修改菜单状态变量并置位标志位。主循环中检查到这个标志位，再调用统一的Menu_RefreshDisplay()函数进行重绘。这能有效解决按键响应和屏幕刷新时序冲突的问题，让逻辑更清晰。

7. 性能优化与调试技巧

当项目复杂后，你可能会遇到显示卡顿、内存不足等问题。这里有一些优化和调试心得。

I2C速度优化：CubeMX生成的I2C默认是标准模式（100kHz）。对于有大量数据刷新（如图形动画）的场景，可以尝试将I2C时钟速度提高到快速模式（400kHz）。在CubeMX的I2C配置里修改Speed Mode为Fast Mode，并重新生成代码。前提是确保你的OLED模块和连接线能稳定支持这个速率。

使用DMA刷新：如果使用SPI接口，并且刷新数据量巨大，可以考虑使用DMA来搬运显存数据到SPI外设，从而解放CPU。对于STM32F103C8T6，其SPI和DMA配置相对直接，能显著提升刷新效率。但对于I2C，HAL库的I2C DMA模式有时不如轮询模式稳定，需要仔细测试。

内存优化：STM32F103C8T6只有20KB RAM，非常宝贵。

• 慎用sprintf、printf等大型库函数。
• 字符串常量尽量使用const修饰，并将其存放到Flash中（默认情况下，Keil MDK会将常量字符串放在Flash）。
• 如果使用了双缓冲，那1KB的缓冲区就是固定的开销。可以考虑使用单缓冲，或者将缓冲区定义为全局静态变量，并确保它被分配到.data或.bss段，而不是栈上。
• 使用malloc/free要极其小心，容易导致内存碎片。在嵌入式系统中，更推荐静态或栈上分配。

调试技巧：

1. “屏幕不亮”：首先检查硬件连接（电源、地、SCL、SDA）。然后用逻辑分析仪或示波器抓取I2C总线波形，看是否有起始信号、地址信号（0x78）和应答。如果没有波形，检查代码中I2C初始化是否正确，引脚配置是否冲突。
2. “显示乱码”：检查字库是否匹配。如果是自定义图形乱码，检查取模软件设置（横向/纵向取模，字节内像素顺序）与驱动代码中的绘图函数逻辑是否一致。
3. “显示内容错位”：检查坐标计算。确认你的x，y参数含义是页地址和列地址，并且没有超出屏幕范围（页0~7， 列0~127）。
4. 利用串口打印：在初始化OLED和关键操作步骤前后，通过串口打印信息（如“OLED Init Start”， “I2C Write OK”），能极大帮助定位问题。确保串口初始化正确，并且printf已重定向到串口。

8. 从项目到产品：稳定性与可维护性思考

当你完成了炫酷的显示功能，考虑将它用于一个需要长期运行的产品时，稳定性就成为首要目标。

电源管理：OLED屏幕虽然功耗低，但在电池供电设备中仍需考虑。SSD1306支持睡眠模式。你可以在系统空闲时，通过发送命令将屏幕置于睡眠状态，需要显示时再唤醒。这能节省可观的电量。

错误恢复：I2C通信可能受干扰而失败。HAL库的HAL_I2C_Mem_Write函数有返回值。在实际产品代码中，不应该忽略这个返回值。可以设计一个简单的重试机制，例如失败后延时几毫秒再重试1-2次。如果连续失败，可以尝试重新初始化I2C外设。

代码模块化：将OLED驱动、菜单逻辑、应用业务（如读取传感器）清晰地分离在不同的.c/.h文件对中。通过头文件暴露必要的接口，隐藏内部数据。这使得代码易于阅读、测试和复用。例如，你可以将oled.c打包成一个独立的驱动模块，未来移植到其他STM32型号甚至其他品牌的MCU时，只需修改底层的硬件抽象层（即发送字节的函数）。

版本与配置管理：使用#define宏定义来管理硬件相关的配置，例如OLED的I2C地址、屏幕尺寸、使用的I2C端口等。将这些定义放在一个单独的config.h文件里。这样，当你换用另一款不同地址或尺寸的OLED时，只需修改这一个文件，而不是在整个工程里搜索替换。

最后，STM32F103C8T6和OLED的组合是一个绝佳的嵌入式学习平台。它涉及硬件接口、通信协议、驱动开发、UI逻辑和系统设计。通过这个项目练手，你积累的经验能无缝迁移到更复杂的芯片（如STM32F4/H7）和更高级的显示设备（如TFT-LCD、LVGL图形库）上。我建议你在基本功能跑通后，尝试挑战一些扩展：比如用定时器中断实现一个精准的时钟，用ADC读取电位器值并在OLED上显示一个动态的进度条，或者结合FreeRTOS，创建一个独立的显示任务来管理OLED刷新。这些实践会让你对嵌入式系统的理解更深一层。