简介：一套面向STM32F1系列微控制器的OLED显示驱动源码包，围绕IIC通信接口提供完整驱动逻辑，适用于嵌入式入门开发者或需要在项目中快速点亮OLED屏的工程师。压缩包共4个文件，包括3个头文件与1个C源文件：.h中声明了函数原型、OLED初始化配置结构体以及汉字字库数组，.c则实现了IIC初始化、OLED_Init、OLED_Clear、OLED_SendCommand/SendData等核心函数，并对中文显示所需的编码映射与像素数据发送做了示例封装。资源包整体仅6KB，代码精简，便于研读和移植。目前已有1096人学习。通过该驱动包，读者可以直观理解STM32F1的GPIO复用配置、IIC外设时序控制以及OLED命令与数据的组织方式，同时可参考其字号定义与取模数据结构，灵活适配不同分辨率的屏幕，有助于缩短显示模块的开发周期。
1. 为什么我还留着这份 OLED 驱动文件：不只是点亮一块屏
前几年做一个室内环境监测的小项目，板子上需要一块小屏幕显示温湿度和空气质量。当时手头最顺手的是一块 0.96 寸 OLED，翻遍资料后发现别人分享的 .C/.H 驱动文件比我自己从头写要省事得多。这份 OLED 文件包专为 STM32F1 系列设计，通过 IIC 通信方式驱动 SSD1306 控制芯片，两个文件丢进工程就能显示字符、汉字、图片和简单图形。本文会拆解它的文件结构、IIC 时序、核心显示函数，并给出实测有效的移植与二次开发方法。
如果你正在做毕设、小仪表或快速原型，又想绕开从底层寄存器开始的心力交瘁，这份驱动值得下载。它能让你把精力花在业务逻辑上，而不是在一行行配置屏幕的细节里翻车。
2. 技术栈与文件结构：一份能直接搬走的 .C/.H 驱动包
很多 MCU 开发者第一次接触 OLED 驱动文件时，第一反应是“里面是不是有复杂的寄存器配置”或“是不是依赖某个厂商库”。实际上这份驱动文件的依赖非常轻，它只做三件事：初始化屏幕、维护一块显存缓冲区、把缓冲区的数据通过 IIC 定时刷到屏幕上。
2.1 驱动对象的正确认识：SSD1306 与 IIC 的组合
0.96 寸 OLED 常见方案是两种接口：SPI 和 IIC。这份文件走的是 IIC，好处是只占两根引脚（SCL、SDA），而且能和其他 IIC 设备挂在同一条总线上。SSD1306 本身是一块带 128×64 像素显存的驱动芯片，它不仅驱动 OLED，还负责把单片机送来的显示数据映射到每一个像素点上。
关键点在于：OLED 屏幕的数据不会自动留存，你需要持续刷新，否则会黑屏。驱动文件内部维护的显存缓冲区大小是 8 页 × 128 字节，也就是 128×64 像素，一屏数据量不大，完全可以在普通 STM32F1 上用 GPIO 模拟 IIC 方式刷屏。硬件 IIC 能解放 CPU，但在 F1 上使用模拟 IIC 更容易控制时序，所以这份文件选择了后者。
2.2 文件清单与依赖关系
资源包里通常包含两个核心文件：oled.c 和 oled.h。oled.c 里实现全部驱动逻辑，包括 IIC 起始、停止、字节发送，向 SSD1306 发送命令与数据，绘制像素点、显示字符串和数字。oled.h 负责声明这些函数，还定义了常用字符宽度、页数和显示方向之类的宏。
除了这两个文件，还有一份字库表，常见做法是把它直接放在 oled.c 里，以 const 数组形式保存 ASCII 字符点阵和常用汉字点阵。这样做的好处是移植时只复制两个文件即可，不必额外引入资源目录。
依赖关系上，这份文件只依赖标准 CMSIS 头文件和两个延时函数（毫秒级和微秒级延时）。如果工程里没有这两个延时函数，常见处理方式是直接调用系统滴答定时器或用简单空循环实现。
2.3 初始化时序：为什么要 8 条指令一组
SSD1306 上电后不会自己进入可以显示的状态，必须先通过 IIC 向它发送一串初始化命令，让它知道接口模式、显示时钟、复用率和对比度等参数。常见的初始化顺序是先关闭显示，再设置显示时钟分频和电荷泵，然后设置内存地址模式，最后打开显示。
这份驱动的初始化函数会把几十条命令分成两组：第一组是基础配置，第二组是清屏和显示开关。如果你只发配置不发清除指令，屏幕往往会留下一堆随机噪点。另外，初始化后必须至少调用一次清屏函数，把显存缓冲区全部置零并刷新，否则首次显示时可能会出现花屏。
代码里的初始化指令参数不是随便写的，比如 0xA8 是设置多路复用比，0x3F 对应 64 行；0x8D 开启电荷泵时，必须先给 0x14 再给 0x14，这是 SSD1306 数据手册里写死的步骤。缺少电荷泵开启，屏幕会永久保持黑屏，这也是新手最容易误解的“编译没错但屏幕不亮”的原因。
3. 核心模块拆解：从 IIC 底层到 OLED 显示
如果把 OLED 驱动看作一条链路，最底层是 IIC 引脚操作，中层是 SSD1306 协议处理，上层才是字符串、数字和图片绘制。这一章从下往上逐层拆解，每一步的代码逻辑都会说明。
3.1 IIC 底层通信：GPIO 模拟还是硬件 IIC
模拟 IIC 的核心代码是起始信号、停止信号和字节发送。起始信号是 SCL 保持高电平期间 SDA 由高变低；停止信号相反。这两个信号是 IIC 通信的“握手”，任何从设备都要靠它们识别一帧数据的开始与结束。
void OLED_IIC_Start(void) { OLED_SDA_GPIO_HIGH(); /* SDA 先拉高 */ OLED_SCL_GPIO_HIGH(); /* SCL 拉高 */ delay_us(5); OLED_SDA_GPIO_LOW(); /* SCL 高电平期间 SDA 拉低，产生起始条件 */ delay_us(5); OLED_SCL_GPIO_LOW(); /* 拉低 SCL，准备发送数据 */ } void OLED_IIC_Stop(void) { OLED_SCL_GPIO_LOW(); /* 确保 SCL 为低 */ OLED_SDA_GPIO_LOW(); /* SDA 拉低 */ delay_us(5); OLED_SCL_GPIO_HIGH(); /* SCL 拉高 */ OLED_SDA_GPIO_HIGH(); /* SDA 在高电平期间拉高，产生停止条件 */ delay_us(5); }这段代码里每次切换信号后都加了微秒延时，目的是让总线电平稳定。GPIO 速度配置也很关键，在 STM32F1 上最好把 SCL 和 SDA 引脚设为开漏输出并外加上拉电阻，或者配置为复用推挽输出。如果引脚配置成普通推挽输出，在有其他 IIC 设备共用总线时容易造成电平冲突。
每次写一个字节，是按位把数据放到 SDA 上，同时用 SCL 产生时钟脉冲。发送完 8 位数据后，从设备会在第 9 个时钟周期拉低 SDA 作为应答，因此主机在发送完一个字节后应该释放 SDA，然后读取应答位。这份驱动里省略了严格的应答判断，因为 OLED 屏通常不会不应答，但如果总线接错或地址不对，这里就区分不出故障。
3.2 驱动核心：写指令、写数据与显存刷新
在 IIC 底层的上面，SSD1306 规定了两个重要的控制字节：0x00 表示后续数据是命令，0x40 表示后续数据是显示数据。驱动里的 OLED_WR_CMD 和 OLED_WR_DATA 就是基于这两个控制字节实现的。
void OLED_WR_CMD(uint8_t cmd) { OLED_IIC_Start(); /* 起始条件 */ OLED_IIC_SendByte(0x78); /* 7 位地址 0x3C 左移一位，加上写位得到 0x78 */ OLED_IIC_SendByte(0x00); /* 命令控制字节 */ OLED_IIC_SendByte(cmd); /* 具体命令 */ OLED_IIC_Stop(); /* 停止条件 */ } void OLED_WR_DATA(uint8_t dat) { OLED_IIC_Start(); OLED_IIC_SendByte(0x78); OLED_IIC_SendByte(0x40); /* 数据控制字节 */ OLED_IIC_SendByte(dat); OLED_IIC_Stop(); }参数 0x78 的来源是：OLED 屏的 7 位 IIC 地址通常为 0x3C，如果板上的地址选择电阻改过，可能变成 0x3D。这里左移一位保留最低写位，0x3C 左移一位就是 0x78。如果显示器不亮，第一件事就是检查这句地址是否与实际硬件匹配。
刷新操作是把显存缓冲区 GRAM 里的 1024 个字节通过 IIC 分批发送到屏幕上。SSD1306 的显存布局是按页排列的，每页 8 个像素行，8 页共 64 行。屏幕刷新时，先设置列地址和页地址，再连续发送数据。驱动里的 OLED_Refresh 函数会循环 8 个页，每页发送 128 个字节。
3.3 画点、字符与中文显示
所有显示效果最终都要落到像素层面。画点函数的核心是计算一个坐标点属于哪一页、哪一列，再通过置位或清零对应缓冲区字节的位来实现。字符显示就是按 8×16 点阵在屏幕上摆放点，中文则是 16×16 点阵。
void OLED_DrawPoint(uint8_t x, uint8_t y, uint8_t dot) { uint8_t page, column, bit_pos; if (x > 127 || y > 63) return; /* 坐标越界直接返回 */ page = y / 8; /* 每一页包含 8 行像素 */ column = x; bit_pos = y % 8; if (dot == 1) { OLED_GRAM[page][column] |= (1 << bit_pos); } else { OLED_GRAM[page][column] &= ~(1 << bit_pos); } }这里 OLED_GRAM 是一个二维数组，第一维是页，第二维是列。画点前必须检查坐标是否超出 128×64，否则数组越界会污染其他内存区域，轻则显示错乱，重则导致单片机死机。画点后不会立即显示在屏幕上，必须调用 OLED_Refresh 把缓冲区同步到屏幕，这个习惯很重要，有不少人改了半天缓存没刷新，以为函数坏了。
字符显示函数的参数是行和列，以及要显示的字符。它会先从字库表中取出 16 字节的点阵，再按位调用 OLED_DrawPoint。中文字库通常要额外引入一个较大的数组，原驱动里一般只带常用 ASCII 字符，二次开发时增加中文字符需要注意 Flash 空间占用。
4. 避坑记录：OLED 显示异常排查与移植注意
OLED 驱动文件不大，看起来没什么可踩坑的，但真跑起来后问题往往比预想多。这一章整理了几条我在实际调试和带人移植时遇到的高频问题，每一条都有现象、原因和解决思路。
4.1 上电白屏：IIC 地址 0x78 与 0x7A 写错的后果
现象：程序下载后屏幕完全没有反应，背光不亮，或者一片均匀的白屏。排查串口和引脚都没发现问题。
原因：OLED 模块的 IIC 地址并不是固定的。大部分模块默认地址是 0x3C，对应发送地址 0x78，但部分模块的地址选择电阻默认接到了高电平，从机地址变成 0x3D，对应发送地址就是 0x7A。驱动文件里写死 0x78，如果硬件实际是 0x3D，从机根本不会应答。
解决：先查模块背面的地址电阻标志，或者用 IIC 扫描程序在总线上扫一遍，看看到底是哪个地址有响应。如果手头没有逻辑分析仪，就写一个简单的扫描函数，把 0x00 到 0x7F 的地址都发一遍，哪个地址从机有应答，那个就是实际地址。扫描代码调试一轮后，把驱动文件里的 0x78 改成实际值即可。
4.2 花屏与残影：刷新缓冲区没有清空
现象：屏幕能显示内容，但显示新内容时会出现旧画面的残影，或者初次上电时出现雪花一样的随机噪点。无论怎么刷新，噪点总在固定区域出现。
原因：这是典型的显存缓冲区未初始化问题。OLED_GRAM 是全局数组，如果不显式清零，上电后内容是不可预知的随机值。初始化函数只配置了 SSD1306 的寄存器，并没有把所有像素点置零。驱动文件里的清屏函数如果只清屏幕却不同步清 OLED_GRAM，也会出现刷新后旧数据被再次搬运上屏的情况。
解决：初始化完成后，强制执行 memset(OLED_GRAM, 0, sizeof(OLED_GRAM))，再调用一次 OLED_Refresh。以后每次清屏都先清缓冲区，再刷屏幕。有些驱动甚至不让用户直接调用 OLED_Clear，而是把清屏逻辑隐藏在初始化里，就是为了避免这种问题。我在自己的工程里加了一个规则：任何对 OLED_GRAM 的写操作，后面必须跟一次 OLED_Refresh，不然不允许合入。
4.3 引脚接反导致 CRC 校验一样玄学的“假正常”
现象：程序编译通过，SCL 和 SDA 引脚互换后，屏幕有时能亮，但显示内容错乱，偶尔还会伴随整屏闪烁。看起来像时序不稳定，其实问题出在物理连接。
原因：IIC 的 SCL 和 SDA 一旦接反，从机无法建立正确的时钟关系，驱动发送的数据全部作废。偶尔能亮是因为上电瞬间总线的杂散信号恰好满足了一次假通信。这种故障在示波器上看起来像电平不稳，容易让人误以为是延时不够，从而去改时序参数，越改越乱。
解决：先用万用表确认模块上的 SCL 和 SDA 引脚编号，再对照驱动文件里宏定义的 GPIO 配置。我在驱动文件里加了一个 OLED_GPIO_Config 函数，把引脚选择集中管理，避免在主函数里到处分散配置。连接正确后，再考虑延时和上拉电阻的问题。
4.4 上拉电阻与 GPIO 模式：模拟 IIC 的隐藏死穴
现象：单独测试屏幕没问题，和另一个 IIC 传感器接在同一对 SCL/SDA 上后，屏幕显示卡顿，甚至传感器数据也读到一半就出错。单独断开任何一方都正常。
原因：模拟 IIC 的驱动文件通常把 GPIO 配置成推挽输出，这在高电平输出时会把总线强行拉高。如果多个设备共用一个 IIC 总线，推挽输出会与其他设备的开漏输出打架。SSD1306 和大多数 IIC 设备都是开漏设计，总线必须靠外部上拉电阻才能拉高，主机也应使用开漏模式。
解决：把所有模拟 IIC 的 SCL/SDA 引脚改为开漏输出，并在外部加上 4.7KΩ 左右的上拉电阻，或者在 STM32F1 内部启用上拉。修改之后，总线上多设备通信就稳定了。这个坑在单设备场景下不会暴露，直到你尝试扩展第二个 IIC 外设时才发作。
4.5 延时函数精度：微秒延时被编译器优化掉
现象：屏幕显示时速度快到出现严重残影，有时候刷新一屏内容要花很长时间，但像素点仍然歪歪扭扭，甚至出现横线缺失。
原因：驱动文件里用到的 delay_us 如果是空循环实现，编译器在开启优化后会把整个循环优化掉，导致 IIC 时钟周期过短，SSD1306 跟不上。尤其在 Keil 默认 O0 优化时没问题，一开 O2 就翻车。
解决：延时函数不要写成“for (i = 0; i < n; i++);”这种空转形式，而要使用 DWT 或 SysTick 计数器做精确延时。或者把延时函数声明为 volatile 参数，避免被编译器优化。我在驱动文件里把 OLED_IIC_Delay 统一替换成了基于 SysTick 的 delay_us 实现，从此再没出现优化导致的时序问题。
5. 二次开发：把驱动文件改造成你要的显示方案
这段资源最大的价值在于可以当做一个显示底座来扩展。从一个只会显示固定字符的驱动，改成能显示实时曲线、菜单页或简易动画，都只需要替换或增加少量函数。
5.1 从“显示字符串”升级为“带背景的图片绘制”
原驱动只提供画点、字符和整屏刷新接口，如果你要绘制一张 128×64 的图片，最简单的做法是把图片取模后的数据按字节写入 OLED_GRAM。
void OLED_ShowPicture(const uint8_t *pic) { uint8_t i, j; for (i = 0; i < 8; i++) { for (j = 0; j < 128; j++) { OLED_GRAM[i][j] = pic[i * 128 + j]; } } OLED_Refresh(); }这段代码把一张 1024 字节的图片数据直接映射到显存缓冲区。图片取模时，建议按“列行式”或“页式”取模，否则会出现图片左右颠倒或上下翻转。取模方向与 OLED_GRAM 的页/列布局保持一致，是二次开发最容易踩的坑。
5.2 扩展菜单页面时的缓冲状态管理
做菜单时不要每次更新都把整个屏幕清掉再重绘。比较稳的做法是维护一个“当前页面 ID”，只在页面切换时清屏，平时仅更新变化区域。这样刷新闪烁会明显减少。OLED 本身刷新率足够快，但 IIC 传输 1024 字节仍需要几毫秒，频繁整屏刷新会显得拖沓。
5.3 验证方法：先跑通地址扫描，再做功能测试
二次开发完成后，我习惯先用一个最简单的 demo 验证 IIC 地址和引脚配置，再跑点亮程序，最后才测复杂显示。如果某一步不正常，按照第 4 章的排查步骤从地址、接线、延时、缓冲区四层去找问题，不要盲目调时序。
从那以后我每次拿到一块陌生 OLED 屏，都会强制走一遍“扫描地址 → 点亮单点 → 整屏刷新 → 显示字符”的流程，而不是直接套用旧驱动。这样做节省的时间远超想象，换屏和换板子都变得非常轻松。希望这份驱动文件的拆解记录能帮你在做显示功能时少走些弯路，也祝你一次点亮。
本文还有配套的精品资源，点击获取
