1. 从一块小屏幕说起：OLED 显示模块到底能做什么
如果你玩过单片机、做过嵌入式小项目，大概率绕不开一块巴掌大的小屏幕——OLED 显示模块。它不像 LCD 那样需要背光板，通电就能自己发光，黑色部分是真的黑，对比度高得离谱，在强光下也能看清字。我第一次用它是给一个温湿度采集器做本地显示，当时图便宜买了一块 0.96 寸的 I2C 接口 OLED，四根线一接，代码一烧，屏幕上跳出数字的那一刻，确实有点小激动。
OLED 全称是有机发光二极管，每个像素点自己发光，不需要背光层，所以模块可以做得很薄、很省电。常见的规格有 0.96 寸、1.3 寸，分辨率多为 128×64 或 128×32，接口分 I2C 和 SPI 两种。I2C 只要两根信号线，接线简单，适合引脚紧张的项目；SPI 速度快，刷屏流畅，适合做动画或高频刷新。驱动芯片常见的是 SSD1306、SH1106，前者最普遍，后者在 1.3 寸屏上更常见，两者指令集略有差异，代码不能直接混用。
这篇文章面向的是刚上手单片机、想给项目加一块本地显示屏的朋友，也适合已经用过 OLED 但想搞清楚底层驱动逻辑、优化刷新效率的开发者。我会从选型、接线、驱动原理讲到 HAL 库和 CH32V307 平台下的实操代码，把踩过的坑和调试技巧一并分享出来。不管你是用 STM32 还是国产 RISC-V 芯片，核心思路是相通的。
2. 选型与硬件设计：别让一块屏拖垮整个项目
2.1 尺寸、分辨率与接口的取舍逻辑
选 OLED 模块，第一件事是确定尺寸和分辨率。0.96 寸 128×64 是最常见的入门款，显示 4 行 16 点阵汉字或 8 行 ASCII 字符，做参数显示足够用。1.3 寸同样是 128×64，但像素点更大，可视角度更好，价格贵几块钱。如果你要做波形显示或简单 UI，128×64 是底线，128×32 只能显示两行，做菜单会很憋屈。
接口方面，I2C 和 SPI 的选择要看项目需求。I2C 标准速率 100kHz，快速模式 400kHz，刷一屏 128×64 的 1KB 数据大概需要 20 到 80 毫秒，做静态显示没问题，但做动画会明显卡顿。SPI 可以跑到 10MHz 以上，刷屏时间缩短到几毫秒，流畅度完全不是一个级别。我一般建议：如果引脚够用、又需要动态效果，直接上 SPI；如果只是显示几个传感器数值，I2C 足够，还省两根线。
还有一个容易忽略的点是驱动芯片。SSD1306 和 SH1106 的初始化指令有差异，SH1106 的显存是 132×64，但屏幕只显示中间 128 列，如果按 SSD1306 的代码驱动 SH1106，画面会偏移两列。买模块时一定要问清楚芯片型号，或者看商品详情页的说明。我吃过这个亏，一块 1.3 寸屏用 SSD1306 库驱动，左边总是缺两个像素，折腾了半天才发现是芯片不匹配。
2.2 供电与电平匹配的注意事项
OLED 模块一般支持 3.3V 和 5V 供电，但逻辑电平要特别注意。SSD1306 的 I2C 引脚是开漏输出，理论上可以容忍 5V，但很多模块内部没有电平转换电路，直接接 5V 单片机会有风险。稳妥的做法是：如果单片机是 3.3V 系统，OLED 也接 3.3V；如果是 5V 系统，最好加一个电平转换模块，或者确认模块自带稳压和电平转换。
供电电流方面，0.96 寸 OLED 全亮时大概 20mA 左右，显示内容少时只有几毫安，对大多数开发板来说不是负担。但要注意，OLED 的电流会随点亮像素数量变化，如果和敏感模拟电路共用电源，最好加一个 100nF 的去耦电容，减少干扰。我在一个音频项目里就遇到过 OLED 刷新时喇叭有轻微噪声，后来在电源脚并了电容才解决。
接线长度也有讲究。I2C 的 SDA 和 SCL 线如果超过 20 厘米，最好用双绞线或屏蔽线，否则通信容易出错。SPI 的时钟线更敏感，线长了要降低时钟频率。这些细节在面包板上测试时可能没问题，但做成成品后就会暴露，提前注意能省不少返工时间。
3. 驱动原理拆解：显存、页地址与刷新机制
3.1 显存映射与页结构
OLED 模块内部有一块显存，大小对应屏幕分辨率。以 128×64 为例，显存是 128 列 × 64 行，但组织方式不是按行连续存放，而是分成 8 个页，每页 8 行，共 64 行。每个页有 128 个字节，每个字节的 8 个位对应这一页的 8 行。也就是说，显存地址由页地址和列地址共同决定，写入一个字节就控制了 8 个像素点。
这种页结构是 SSD1306 的设计特点，理解它才能正确写驱动。比如你要在坐标 (x, y) 画一个点，先算出它属于第几页：页号 = y / 8，页内行号 = y % 8，然后找到对应的列 x，把该字节的第 (y % 8) 位置 1。如果要在同一列画多个点，需要读改写，或者用显存缓冲区的做法：在单片机内存里开一块 1KB 的数组，所有绘图操作先改数组，最后一次性刷到 OLED。这样效率高，也避免频繁读 OLED 显存。
我刚开始写驱动时，直接往 OLED 写点，结果画一个字符要几十毫秒，屏幕闪烁严重。后来改成显存缓冲方案，画完整屏再统一刷新，速度提升明显，代码也更好维护。这个思路在 HAL 库和 CH32V307 上都适用，区别只是 I2C 或 SPI 的发送函数不同。
3.2 初始化序列与关键指令
OLED 上电后不能直接显示，需要发送一串初始化指令。这些指令配置了对比度、扫描方向、时钟分频、电荷泵等参数。电荷泵是必须开启的，否则屏幕不亮。SSD1306 的初始化序列通常包括：关闭显示、设置时钟、设置多路复用率、设置显示偏移、设置起始行、开启电荷泵、设置内存寻址模式、设置段重映射、设置扫描方向、设置对比度、开启显示。
内存寻址模式有三种：页模式、水平模式和垂直模式。页模式每次写完一页要手动换页，水平模式可以自动换行，适合连续写入整屏数据。我一般用水平模式，配合显存缓冲区，一次发送 1024 字节就能刷新全屏。初始化里的段重映射和扫描方向决定了屏幕的旋转方向，如果显示是镜像的，改这两个指令就能翻转。
对比度设置影响亮度和功耗，默认 0x7F 左右，太高会缩短 OLED 寿命，太低在强光下看不清。我通常设在 0xCF 到 0xEF 之间，兼顾亮度和寿命。这些参数没有绝对标准，要根据实际屏幕和外壳透光率调整。
4. HAL 库驱动 OLED 完整实操
4.1 硬件连接与 CubeMX 配置
以 STM32 为例，用 HAL 库驱动 I2C OLED，第一步是接线。OLED 的 VCC 接 3.3V，GND 接 GND，SCL 接单片机的 I2C 时钟脚，SDA 接数据脚。比如 STM32F103C8T6 的 I2C1 是 PB6 和 PB7，接上就行。如果模块背面有地址选择电阻，默认地址通常是 0x78 或 0x7A，对应 7 位地址 0x3C 或 0x3D。
CubeMX 里开启 I2C1，模式选 I2C，速度设 400kHz 快速模式。GPIO 不用手动配，CubeMX 会自动设置开漏和上拉。生成代码后，HAL 库会初始化 I2C 外设，我们只需要调用HAL_I2C_Mem_Write或HAL_I2C_Master_Transmit发送数据。注意 OLED 的 I2C 从机地址要左移一位，HAL 库要求 8 位地址，所以 0x3C 要写成 0x78。
#define OLED_ADDR 0x78 uint8_t init_cmds[] = { 0x00, 0xAE, 0x20, 0x00, 0xB0, 0xC8, 0x00, 0x10, 0x40, 0x81, 0xCF, 0xA1, 0xA6, 0xA8, 0x3F, 0xA4, 0xD3, 0x00, 0xD5, 0x80, 0xD9, 0xF1, 0xDA, 0x12, 0xDB, 0x40, 0x8D, 0x14, 0xAF }; HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR, init_cmds, sizeof(init_cmds), 100);这段代码里，第一个字节 0x00 是控制字节，表示后面跟的是命令。如果发数据，控制字节要改成 0x40。初始化序列里的 0xAE 是关显示，0xAF 是开显示，0x8D 0x14 是开启电荷泵，这几个是关键，少了屏幕不亮。
4.2 显存缓冲区与刷新函数实现
在单片机内存里开一个 1024 字节的数组作为显存缓冲区：
uint8_t oled_buffer[8][128];然后实现画点、画线、显示字符的函数，所有操作都改这个数组。最后写一个刷新函数，把数组按页发送到 OLED：
void OLED_Refresh(void) { for (uint8_t page = 0; page < 8; page++) { uint8_t cmds[] = {0x00, 0xB0 + page, 0x00, 0x10}; HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR, cmds, 4, 100); uint8_t data[129]; data[0] = 0x40; memcpy(&data[1], oled_buffer[page], 128); HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR, data, 129, 100); } }这里每页先发命令设置页地址和列地址，再发 128 字节数据。数据前加 0x40 控制字节，表示后面是显存数据。整个刷新过程 8 次传输，每次 129 字节，在 400kHz I2C 下大概 20 多毫秒，肉眼看不到闪烁。
显示字符需要字库。常用的是 8×16 点阵 ASCII 字库，每个字符 16 字节。把字库数组放在代码里，显示时根据字符编码取模。中文显示需要 16×16 点阵，字库更大，一般放在外部 Flash 或通过取模软件生成。我建议初学者先用 ASCII 字库，跑通流程后再加中文。
4.3 CH32V307 平台的 I2C 适配要点
CH32V307 是 RISC-V 内核的单片机，主频高，外设丰富，用 I2C 驱动 OLED 的思路和 STM32 类似，但寄存器操作有差异。如果用官方库，I2C 初始化流程差不多，注意时钟配置和引脚复用。CH32V307 的 I2C 支持硬件和软件两种方式，硬件 I2C 效率高，但调试时如果遇到总线锁死，软件模拟 I2C 更灵活。
软件模拟 I2C 只需要两个 GPIO，通过拉高拉低模拟时序。优点是移植方便，任何单片机都能用；缺点是速度受 CPU 主频影响，刷屏比硬件 I2C 慢。CH32V307 主频 144MHz，软件模拟也能跑到几百 kHz，做静态显示完全够用。我实测过，软件模拟刷一屏 128×64 大概 30 毫秒，比硬件 I2C 稍慢，但代码更可控。
移植时注意延时函数的精度。软件 I2C 的时序靠延时控制，延时太长速度慢，太短通信失败。可以用示波器看波形，或者用逻辑分析仪抓 I2C 数据，确认时序正确。CH32V307 的 GPIO 翻转速度很快，延时几个时钟周期就够了，具体值要实际调试。
5. 常见问题与排查技巧实录
5.1 屏幕不亮、花屏、偏移的排查思路
OLED 调试最常见的问题是屏幕完全不亮。先查供电，用万用表量 VCC 和 GND 之间是不是 3.3V，再看电荷泵指令有没有发。如果供电正常、初始化也发了，还是不亮，可能是 I2C 地址不对。用逻辑分析仪抓一下 SDA 和 SCL，看有没有应答位。没有应答说明地址错了，或者接线反了。
花屏通常是初始化序列不完整或显存数据错乱。检查初始化里有没有设置多路复用率和显示偏移，这两个参数不对会导致显示区域错位。另外，如果显存缓冲区没有清零，上电后显示随机数据，看起来就是花屏。在初始化后加一个清屏函数，把缓冲区全部置零再刷新。
显示偏移两列是 SH1106 芯片的典型问题。SH1106 的显存是 132 列，屏幕只显示中间 128 列，所以列地址要从 2 开始，而不是 0。如果按 SSD1306 的代码从 0 开始写，画面就会左移两列。解决办法是在设置列地址时加 2，或者换用 SH1106 专用的驱动库。
5.2 I2C 通信失败与总线锁死的处理
I2C 通信失败的原因很多，最常见的是上拉电阻缺失。I2C 总线需要上拉电阻，通常 4.7kΩ 到 10kΩ。很多 OLED 模块自带 10kΩ 上拉，但如果接多个 I2C 设备，上拉电阻并联后阻值变小，可能导致上升沿太陡，通信不稳定。这时候可以去掉模块上的上拉，只在主控端加一对 4.7kΩ。
总线锁死是另一个头疼的问题。如果单片机在通信过程中复位，而从机还在等待时钟，SDA 可能被拉低，导致总线死锁。解决办法是在初始化前手动发送 9 个时钟脉冲，让从机释放 SDA。具体操作是把 SCL 配置为推挽输出，拉高拉低 9 次，然后再切换回 I2C 模式。这个技巧在 HAL 库和 CH32V307 上都适用。
还有一个隐蔽的问题是电源纹波。OLED 刷新时电流突变，如果电源质量差，电压会瞬间跌落，导致 I2C 通信出错。在 OLED 的 VCC 和 GND 之间并一个 10μF 电解电容和一个 100nF 陶瓷电容，能明显改善。我在一个电机控制项目里就遇到过，电机启动时 OLED 花屏，加了电容后问题消失。
5.3 刷新速度优化与功耗平衡
如果觉得刷屏慢，可以从几个方面优化。第一，提高 I2C 时钟频率，从 100kHz 提到 400kHz，速度翻四倍。第二，减少刷新区域，只刷新变化的部分，而不是整屏。第三，用 SPI 接口替代 I2C，速度提升一个数量级。第四，优化代码，把显存缓冲区的操作放在 RAM 里，避免频繁访问 OLED。
功耗方面，OLED 的功耗和点亮像素数量成正比。如果做电池供电的项目，可以降低对比度、减少刷新频率、在不需要显示时关闭屏幕。SSD1306 支持睡眠模式，发 0xAE 指令关显示，电流降到微安级。我做过一个手环项目，平时屏幕关闭，按按键才亮几秒，续航从几天延长到几周。
注意：降低对比度虽然省电，但太低会影响可读性。建议在 0xCF 到 0xEF 之间找平衡，实际观察屏幕效果再定。
6. 进阶玩法：从静态显示到简单 UI
6.1 多级菜单与按键交互设计
有了 OLED 和几个按键，就能做多级菜单。核心思路是维护一个菜单状态机，每个状态对应一屏内容，按键切换状态。比如主菜单显示“温度”“湿度”“设置”，按上下键移动光标，按确认键进入子菜单。光标可以用反白显示，即把对应区域的像素取反，视觉上很直观。
实现时，把菜单项和对应的处理函数放在一个结构体数组里，状态机根据当前索引调用。按键处理要做消抖，可以用定时器扫描，或者简单的延时消抖。我一般用 20 毫秒延时消抖，简单可靠。菜单切换时只刷新变化的部分，避免整屏刷新带来的闪烁。
6.2 波形显示与数据可视化
OLED 做波形显示很实用，比如显示传感器采集的曲线。思路是维护一个数据数组，每次新数据进来，数组左移，新数据放最右，然后根据数值映射到屏幕高度画点连线。128 列可以显示 128 个历史数据点，对于慢速信号足够用。
画线算法用 Bresenham 算法，效率高，不会出现断点。如果数据变化快，可以只画点不连线，或者降低采样率。我做过一个心率监测的小玩意，OLED 上实时显示心跳波形，效果还不错。注意波形刷新频率不要太高，否则 I2C 带宽不够，画面会撕裂。
6.3 字库裁剪与自定义图标
标准 ASCII 字库有 95 个字符，每个 16 字节，总共 1520 字节，对大多数单片机不是问题。但如果要显示中文，16×16 点阵每个字 32 字节，几百个字就占十几 KB。可以用取模软件只提取项目用到的汉字，做成小字库，节省空间。
自定义图标也很简单，用取模软件画好图形，生成点阵数组，显示时直接写入显存对应位置。比如电池图标、信号强度图标，都可以预先做好。图标尺寸建议 16×16 或 8×8，方便对齐。我习惯把常用图标和字库放在一个头文件里，用宏定义索引，代码更清晰。
7. 我在实际项目中的几点体会
OLED 模块虽然小，但细节不少。选型时多花几分钟确认驱动芯片和接口，能避免后面很多麻烦。写驱动时先把显存缓冲和刷新函数跑通，再往上堆功能，底层稳了上层才可靠。调试时逻辑分析仪比万用表好用，能直接看到 I2C 波形，定位问题快很多。
还有一点，OLED 的寿命和亮度设置有关。长期高对比度显示静态内容，容易留下残影。如果做长期运行的项目，建议定期改变显示内容，或者降低对比度。我在一个常年运行的时钟项目里，把对比度设到 0x9F，用了两年多屏幕依然均匀。
最后分享一个小技巧：如果 I2C 地址不确定，可以写一个扫描程序，遍历 0x00 到 0x7F，看哪个地址有应答。这个方法在接多个 I2C 设备时特别有用，能快速确认地址冲突。代码很简单，几行就能搞定，比翻数据手册快多了。
