简介：这是一份基于 STM32 标准外设库（HAL 库）的 OLED 显示驱动示例，采用 IIC 串行通信协议完成数据交互，面向嵌入式入门开发者或需要快速集成显示模块的工程师，解决微控制器与屏幕之间通信和驱动移植的实际问题。压缩包共三个文件，含两个头文件与一个 C 源文件；头文件用于函数声明与 ASCII 字符点阵数据，源文件实现底层 IIC 读写时序、屏幕初始化、显示与清屏等函数，整体大小仅 8KB，轻量简洁，便于直接嵌入工程。已有 1081 人学习/下载，反馈良好，适合直接用于项目参考或二次开发。通过阅读这份代码，开发者能理解 IIC 设备驱动的核心流程，包括主从设备通信、寄存器读写和时序控制；同时借助 ASCII 字模，可快速实现字符与简单图形的显示，并为后续扩展菜单、仪表盘等界面功能打下基础。代码注释清晰，结构紧凑，也适合用于课堂教学或毕业设计。 搞嵌入式这些年，最常被问到的外设之一就是OLED屏怎么点亮。尤其现在大家习惯用STM32CubeMX生成工程、再用HAL库写驱动，网上能找到的例程不少，但很多是拿过来能跑、一改就废，要么显示花屏，要么IIC总线直接卡死。我最近在做一个小项目，需要实时显示传感器数据，手头正好有一块0.96寸的IIC接口OLED，于是把整套驱动重新整理了一遍，从HAL库的IIC配置到上层显示API，再到调试中遇到的几个大坑，都记录下来。这篇文章适合刚接触HAL库、准备用IIC驱动OLED的开发者，也适合已经把屏幕点亮但遇到显示异常、卡死等问题的朋友。
1. 为什么我选了OLED + IIC而不是SPI
1.1 引脚占用的账要算清楚
很多人纠结OLED用IIC还是SPI接口，我的答案很直接：看你的引脚余量和显示刷新需求。SPI接口的OLED虽然刷新速度快，但至少要占用SCK、MOSI、CS、DC、RST五个引脚；IIC接口的OLED只需要SDA和SCL两根线，而且可以挂在总线上和其他IIC器件共享。
做传感器数据展示这类场景，刷新率要求并不高，一秒钟更新几次就够了，IIC的带宽完全够用。省下来的几个引脚，可以用来接按键、编码器或者别的传感器，整体的资源利用率高不少。如果你的项目需要频繁刷全屏动画或者显示视频级画面，那才需要认真考虑SPI接口。
1.2 HAL库和标准外设库的差异
早些年大家习惯用标准外设库，寄存器操作都是直接读写，代码写起来虽然繁琐，但心里有底。HAL库的好处是抽象层做得比较统一，CubeMX里勾选一下就能生成初始化代码，换芯片平台的时候移植成本低。但代价是HAL库封装了很多超时判断和状态检查，IIC这种带状态机的通信协议，在HAL库下的行为跟标准库比有不小差别，尤其体现在错误处理和通信超时上。
我见过不少初学者直接在标准库例程上套HAL库的函数名，结果初始化后屏幕没反应，第一反应是代码写错了，实际上往往是IIC初始化参数或者时序处理不对。后面我会专门讲HAL_I2C的配置细节和容易出问题的地方。
2. 先弄懂屏幕的IIC接口：地址怎么算、时序怎么走
2.1 7位地址和8位地址
绝大多数0.96寸OLED屏用的是SSD1306或者SH1106驱动芯片，IIC接口的从机地址由硬件引脚决定。常见的是SA0引脚接地，7位地址为0x3C；如果SA0接高，则7位地址为0x3D。
这里有一个高频错误点：HAL库的HAL_I2C_Mem_Write和HAL_I2C_Master_Transmit函数里，地址参数用的是8位地址，也就是7位地址左移一位后的值。0x3C左移一位是0x78，不是直接填0x3C。如果填错了，驱动的返回值一直是HAL_ERROR，屏幕毫无反应。
2.2 控制字节与寄存器地址
SSD1306通过IIC接收数据时，每个数据包的结构是：起始信号、从机地址+写位、控制字节、数据字节。控制字节很关键，0x00表示后续字节是命令，0x40表示后续字节是显示数据。
举个例子，发送“开显示”命令0xAF，完整的发送序列是：
uint8_t buf[2] = {0x00, 0xAF}; HAL_I2C_Master_Transmit(&hi2c1, 0x78, buf, 2, 100);如果把控制字节写成0x40，那0xAF会被当作显示数据写进显存，屏幕不会执行开显示命令，反而可能出现花屏或者显示乱码。很多人在网上抄例程时看到两套写法，一套用HAL_I2C_Master_Transmit发控制字节，另一套用HAL_I2C_Mem_Write写寄存器地址，其实原理是一样的。
// 用Mem_Write的写法，第二个参数是寄存器地址0x00，对应控制字节 HAL_I2C_Mem_Write(&hi2c1, 0x78, 0x00, I2C_MEMADD_SIZE_8BIT, &cmd, 1, 100);这两种方式都可以，但我更推荐前一种Master_Transmit，因为它把控制字节和数据字节放在同一个buffer里发送，协议层面更直观，也方便一次发多字节数据。
2.3 时序与上拉电阻
IIC总线是开漏结构，所以SCL和SDA必须有上拉电阻才能工作。STM32内部虽然有上拉，但驱动能力有限，而且CubeMX默认配置的IIC引脚不是开漏输出，如果你忘了手动改，那内部上拉根本没用。我建议硬件上至少加4.7kΩ或者10kΩ的上拉电阻，SCL和SDA各一个。
上拉电阻太小，总线灌电流过大，可能导致电平拉不低；上拉电阻太大，上升沿太慢，高速通信时信号边沿不合格。我在调试时遇到过一种诡异现象：屏幕偶尔能点亮，但显示数据容易错乱。后来用示波器看波形，发现SDA上升沿接近1μs，明显太慢。把上拉电阻从10kΩ换成4.7kΩ后问题消失，这就是iic上升沿测试标准里的基本要求——上升时间要在协议规定的范围内。
3. 驱动代码的落地：从底层写函数到上层显示字符串
3.1 初始化序列
SSD1306上电后需要发送一串初始化命令，网上流传的版本很多，但核心命令是一致的。我在项目里用的是这样一组：
static void OLED_InitSequence(void) { OLED_WriteCmd(0xAE); // 关闭显示 OLED_WriteCmd(0x20); // 设置内存寻址模式 OLED_WriteCmd(0x02); // 页寻址模式 OLED_WriteCmd(0xB0); // 设置页地址 OLED_WriteCmd(0xC8); // 扫描方向 OLED_WriteCmd(0x00); // 低列地址 OLED_WriteCmd(0x10); // 高列地址 OLED_WriteCmd(0x40); // 起始行 OLED_WriteCmd(0x81); // 对比度设置 OLED_WriteCmd(0x7F); // 对比度值 OLED_WriteCmd(0xA1); // 段重映射 OLED_WriteCmd(0xA6); // 正常显示 OLED_WriteCmd(0xA8); // 多路复用比 OLED_WriteCmd(0x3F); // 1/64 duty OLED_WriteCmd(0xA4); // 从RAM内容显示 OLED_WriteCmd(0xD3); // 显示偏移 OLED_WriteCmd(0x00); OLED_WriteCmd(0xD5); // 时钟分频 OLED_WriteCmd(0x80); OLED_WriteCmd(0xD9); // 预充电周期 OLED_WriteCmd(0xF1); OLED_WriteCmd(0xDA); // COM引脚配置 OLED_WriteCmd(0x12); OLED_WriteCmd(0xDB); // VCOMH电平 OLED_WriteCmd(0x30); OLED_WriteCmd(0x8D); // 电荷泵 OLED_WriteCmd(0x14); // 开启电荷泵 OLED_WriteCmd(0xAF); // 开启显示 }初始化顺序不是绝对不能动，但有几个关键点要注意：电荷泵（0x8D, 0x14）必须在开启显示（0xAF）之前设置好，否则屏幕亮度会非常低甚至黑屏。很多人的OLED显示极暗，实际上是漏掉了电荷泵命令。
3.2 底层写函数
用HAL库实现底层写命令和写数据函数，核心是HAL_I2C_Master_Transmit。注意超时时间要留够，IIC在400kHz速率下发送一个字节大约几十微秒，100ms超时足够，但如果系统时钟配置有问题，超时太短会导致发送失败。
void OLED_WriteCmd(uint8_t cmd) { uint8_t buf[2] = {0x00, cmd}; HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR_8BIT, buf, 2, 100); } void OLED_WriteData(uint8_t data) { uint8_t buf[2] = {0x40, data}; HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR_8BIT, buf, 2, 100); }3.3 显存与刷新
SSD1306内部有个显存，128x64像素对应1024字节。IIC接口的OLED不能像SPI那样连续写整个显存，但可以通过页寻址模式配合列地址连续发送。我常用的做法是在单片机内部维护一个128x8的二维数组作为显存缓存，需要更新内容时先修改缓存，再一次性把整屏推到屏幕。
uint8_t OLED_GRAM[8][128]; void OLED_Refresh(void) { for (uint8_t page = 0; page < 8; page++) { OLED_WriteCmd(0xB0 + page); // 设置页地址 OLED_WriteCmd(0x00); // 低列地址 OLED_WriteCmd(0x10); // 高列地址 HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR_8BIT, OLED_GRAM[page], 128, 200); } }这里有个性能细节：使用页寻址模式时，连续发送128个数据字节会写满当前页的128列，不需要每写一个字节都重设列地址，所以整屏刷新只需要8次Master_Transmit调用，每次发128字节，效率比逐字节发送高得多。
3.4 封装上层API
有了显存和刷新函数，剩下的画点、画字符、显示字符串就好办了。画点就是修改缓存数组里对应的位：
void OLED_DrawPoint(uint8_t x, uint8_t y) { if (x >= 128 || y >= 64) return; uint8_t page = y / 8; uint8_t bit = y % 8; OLED_GRAM[page][x] |= (1 << bit); }字符显示需要准备字库，我用的是6x8和8x16两套ASCII字库。8x16字库比较常用，一个字符占16字节，每字节对应一列的上半部分和下半部分。
void OLED_ShowString(uint8_t x, uint8_t y, char *str) { while (*str) { OLED_ShowChar(x, y, *str++); x += 8; if (x > 120) { x = 0; y += 16; } } }到此，一个完整的驱动文件就算写完了。我习惯把写命令、写数据、显存操作、画点、字符显示、字符串显示、清屏这些函数统一放一个oled.c，头文件里只暴露上层接口，业务代码根本不用关心底层是HAL_I2C_Master_Transmit还是寄存器操作。
4. 我在实测里踩过的坑
4.1 第一帧花屏的罪魁祸首是上电时序
我最初把OLED初始化和外设初始化放在同一个函数里，上电后立刻执行初始化命令。结果发现，前两次上电偶尔花屏，按压复位键后能正常。排查了很久，最后定位到是** OLED模块上电后内部驱动芯片还没稳定，紧接着的IIC通信命令没有正确执行。**
解决办法是在OLED初始化之前加一个延时，等电源稳定。我在CubeMX生成的main函数里，在OLED_Init()之前加了HAL_Delay(100)，花屏问题基本消失。如果是电池供电或者电源纹波比较大的场景，建议把延时加到200ms。
4.2 HAL_I2C_XXX返回HAL_BUSY的排查链路
有次换了一块新的OLED屏，屏上没有任何反应，HAL_I2C_Master_Transmit返回HAL_BUSY。我排查的顺序是这样的：先检查IIC引脚配置，发现CubeMX默认把PA11和PA12配置成了开漏，这没问题；再检查上拉电阻，发现手头的模块板载了上拉电阻，排除。然后用示波器看SCL和SDA波形，发现SDA一直为低。
进一步查才发现问题不在OLED，而是IIC总线上还挂了一个MPU6050，它的地址和OLED冲突了，而且MPU6050的SDA输出配置有问题，把总线拉死了。移除MPU6050后OLED正常。如果你遇到IIC总线异常，优先怀疑总线上其他器件，用万用表量一下SDA对地电阻，如果接近0，基本就是某个从机把总线拉死了。
4.3 软件IIC和硬件IIC的取舍
很多时候屏幕点不亮，不是因为代码问题，而是硬件IIC引脚被复用占用，或者CubeMX配置的引脚与实际接线不一致。这种时候最直接的排查办法就是临时改用软件IIC，用GPIO模拟时序。软件IIC的好处是不受引脚复用限制，随便找两个GPIO就能用，而且时序完全可控，方便逻辑分析仪抓数据。
我当时的做法是写了一个software_iic.c，用两个GPIO模拟起始信号、停止信号、发送字节。软件IIC虽然占CPU，但在显示这种低频场景下完全够用。如果你只是为了快速验证屏幕好坏，软件IIC是最快的路径；如果做正式产品，我还是建议用硬件IIC，省CPU资源，配合DMA还能进一步提升性能。
4.4 地址位和时序标准别想当然
热词里有一条“iic上升沿测试标准”，这个在调试时确实会碰到。IIC标准模式下上升时间最大1000ns，快速模式最大300ns。如果波形上升沿不达标，数据建立时间不够，从机就可能采样到错误电平，体现为屏幕偶尔乱码。
测试方法很简单：用示波器看SDA和SCL的上升沿，配合上拉电阻阻值调整。如果没有示波器，可以通过降低IIC时钟速度来规避。CubeMX里I2C的时钟速度默认100kHz，这个速度比较稳。如果想跑400kHz，务必确认上拉电阻和总线电容是否满足要求。
4.5 不要忽略引脚的电气属性配置
HAL库的GPIO初始化里，IIC引脚需要配置为开漏输出。CubeMX在配置I2C外设时会自动生成正确的GPIO初始化和AF复用配置，但如果你是在已有工程里手动添加IIC功能，很容易漏掉AF配置。漏配置的后果是引脚保持推挽输出，SCL和SDA的电平无法被从机拉低，通信必然失败。
检查方法是在调试器里看GPIO寄存器配置，或者直接看引脚能否被外部拉低。我第一次手动移植工程时就栽在这里，后来凡是涉及引脚复用，我都优先用CubeMX重新生成，而不是手改寄存器。
5. 关于这个驱动文件，我最后的几点心得
这个OLED驱动.zip里的内容，核心就是上面这些代码和排查思路。整理文件的时候，我把oled.c、oled.h、字库文件、软件IIC备用驱动一起打包，方便不同的项目直接复用。
在实际使用中，还有两个小技巧值得分享。一是如果不确定屏幕驱动芯片是SSD1306还是SH1106，先看驱动IC的丝印再选初始化命令序列。两者初始化命令基本一致，但SH1106在列地址处理上略有区别，如果你的屏幕是SH1106且用SSD1306的驱动，显示内容会整体偏移几列。二是不要在中断服务函数里直接调用HAL_I2C_Master_Transmit，IIC本身带状态机，中断里调用容易导致HAL_BUSY，正确做法是在主循环里处理。
另外建议把HAL_I2C_ErrorCallback写一下，哪怕只是放个断点或者记录错误码。HAL库的IIC错误处理比较隐蔽，有时通信失败不会立刻反映出来，有了错误回调，排查问题能省不少时间。这个驱动文件我已经在STM32F103C8T6和STM32G431上各跑过一轮，基本是开箱即用。如果你在移植过程中遇到屏幕不亮、显示乱码或者IIC卡死，按上面的排查链路走一遍，大概率能找到问题。
本文还有配套的精品资源，点击获取
