简介：这份资源面向使用STM32 HAL库进行嵌入式开发的工程师与学习者，提供驱动SSD1306单色OLED显示模块的完整库文件，帮助快速实现显示屏控制，适用于物联网设备、智能家居及小型便携设备等场景。压缩包共6个文件，包含3个c源文件与3个h头文件，整体约12KB，涵盖驱动核心逻辑、字体数据与测试例程，结构精简便于移植。驱动同时支持SPI与I2C两种通信协议，SPI适合短距离高速传输，I2C则简化布线、节省引脚，并可通过宏定义切换通信方式，SPI模式下还可能支持DMA高效传输。测试例程演示了OLED初始化、显示区域设置、像素写入与文本显示等基本操作，有助于理解命令集与显示模式。目前已有2324人学习下载，适合具备HAL库、通信协议与DMA基础知识的开发者参考，能有效节省开发时间。
1. 从一堆零散驱动到一份能跑的库：SSD1306 在 STM32 HAL 下到底该怎么组织
很多人第一次在 STM32 上点 SSD1306，都是先找一份“能亮”的例程，把 I2C 地址一填、初始化一调，屏幕出字就收工。可一旦换块板子、换个 I2C 口、或者从 F1 迁到 F4，代码立刻散架：引脚宏定义埋在 .c 里、延时函数写死、显存刷新和业务逻辑搅在一起。标题里说的“库文件.zip”，真正值钱的不是那几百行驱动，而是它把“硬件抽象层怎么接、显存怎么管、刷新怎么调度”这三件事拆清楚了。这篇笔记就按这个思路，把 SSD1306 在 STM32 HAL 下的库化组织方式讲透，适合已经能点灯、能跑 I2C 扫描，但驱动代码一多就乱的嵌入式开发者。读完你能自己搭一份可移植的驱动库，而不是继续复制粘贴。
2. 先定接口再写驱动：SSD1306 库的分层与文件职责
2.1 为什么不能把 HAL_I2C_Master_Transmit 直接写进 OLED 驱动
裸写驱动最典型的翻车现场，是驱动文件里直接出现hi2c1这种全局句柄。编译能过，但换一个 I2C 实例就得改驱动源码，库就失去了“库”的意义。常见做法是抽一层通信接口，让 SSD1306 驱动只依赖函数指针，不依赖具体 HAL 句柄。
我一般把库拆成四个文件：ssd1306.h/.c放命令与显存逻辑，ssd1306_hal.h/.c放平台适配。驱动层只调用ssd1306_write_cmd()和ssd1306_write_data()，这两个函数在适配层里用 HAL 实现。这样从 I2C 换到 SPI，只改适配层，显存和绘图代码一行不动。
/* ssd1306_hal.h —— 平台适配接口，驱动层只认这几个函数 */ #ifndef SSD1306_HAL_H #define SSD1306_HAL_H #include <stdint.h> /* 返回值：0 成功，非 0 失败，便于上层判断总线异常 */ uint8_t ssd1306_hal_init(void); uint8_t ssd1306_hal_write_cmd(uint8_t cmd); uint8_t ssd1306_hal_write_data(const uint8_t *buf, uint16_t len); void ssd1306_hal_delay_ms(uint32_t ms); #endif逻辑说明：头文件只暴露四个函数，覆盖初始化、命令、批量数据、延时。参数上write_data用const uint8_t *加长度，是为了让显存整页刷新时一次传 128 字节，而不是逐字节调用，I2C 场景下能明显降低开销。延时单独抽出，是因为 SSD1306 上电后需要等待稳压，不同主频的板子延时实现不同。
2.2 显存缓冲区的尺寸与页寻址模式怎么对应
SSD1306 是 128×64 单色屏，显存按页组织，8 页、每页 128 列，每列 1 字节对应 8 个纵向像素。库文件里必须有一块uint8_t buffer[1024]，即 128×8。很多人直接写buffer[128][8]，结果刷新时行列搞反，屏幕出现竖条纹。
/* ssd1306.h —— 显存与坐标约定 */ #define SSD1306_WIDTH 128 #define SSD1306_HEIGHT 64 #define SSD1306_PAGES (SSD1306_HEIGHT / 8) /* = 8 */ typedef struct { uint8_t buffer[SSD1306_WIDTH * SSD1306_PAGES]; /* 1024 字节 */ uint8_t addr; /* I2C 从机地址，通常 0x78 或 0x7A */ uint8_t initialized; } SSD1306_Handle; /* 坐标原点在左上角，x:0~127，y:0~63 */ void ssd1306_draw_pixel(SSD1306_Handle *h, uint8_t x, uint8_t y, uint8_t on); void ssd1306_refresh(SSD1306_Handle *h);逻辑说明：buffer用一维数组，索引公式是buffer[x + (y / 8) * 128]，位偏移是y % 8。这样写比二维数组更贴近 SSD1306 的页寻址顺序，刷新时可以直接按页整段发送。addr放进句柄而不是宏，是为了同一套代码能挂两块屏。initialized标志用于防止未初始化就刷新导致总线卡死。
2.3 初始化命令序列里哪几条不能省
SSD1306 上电后必须按顺序发一批命令，少一条就可能黑屏或花屏。库文件里通常把这段做成常量数组，逐条下发。
/* ssd1306.c —— 初始化命令序列（节选关键项） */ static const uint8_t init_cmds[] = { 0xAE, /* 关闭显示，配置期间必须关 */ 0xD5, 0x80, /* 时钟分频，0x80 是常用值 */ 0xA8, 0x3F, /* 多路复用比 1/64，对应 64 行 */ 0xD3, 0x00, /* 显示偏移 0 */ 0x40, /* 显示起始行 0 */ 0x8D, 0x14, /* 电荷泵使能，不开发光不起来 */ 0x20, 0x00, /* 内存寻址模式：水平寻址 */ 0xA1, /* 段重映射，决定左右方向 */ 0xC8, /* 扫描方向，决定上下方向 */ 0xDA, 0x12, /* COM 引脚配置，128x64 用 0x12 */ 0x81, 0xCF, /* 对比度，0xCF 偏亮 */ 0xD9, 0xF1, /* 预充电周期 */ 0xDB, 0x40, /* VCOMH 电压 */ 0xA4, /* 恢复显示内容 */ 0xA6, /* 正常显示，非反色 */ 0xAF /* 开启显示 */ };逻辑说明：0x8D,0x14电荷泵是最容易漏的一条，漏了屏幕完全无反应，很多人误判为 I2C 没通。0xA1和0xC8决定显示方向，如果字是镜像的，先查这两条。0x20,0x00选水平寻址，刷新时只需设置一次窗口，后续数据自动按列递增，比页寻址少发很多命令。参数上对比度0xCF可按电源调整，电池供电时降到0x8F更省电。
3. 把库接进 HAL 工程：I2C 适配层与刷新调度
3.1 用 HAL_I2C_Mem_Write 实现命令与数据写入
适配层是库和 HAL 的唯一接触面。SSD1306 的 I2C 从机地址通常是 0x3C 或 0x3D，左移一位后是 0x78 或 0x7A。控制字节 0x00 表示后面是命令，0x40 表示后面是数据。
/* ssd1306_hal.c —— 基于 HAL 的 I2C 适配 */ #include "ssd1306_hal.h" #include "main.h" /* 由 CubeMX 生成，含 hi2c1 声明 */ extern I2C_HandleTypeDef hi2c1; #define SSD1306_I2C_ADDR (0x3C << 1) /* 7 位地址左移，HAL 要求 */ #define SSD1306_CTRL_CMD 0x00 #define SSD1306_CTRL_DATA 0x40 #define SSD1306_TIMEOUT 100 uint8_t ssd1306_hal_write_cmd(uint8_t cmd) { /* Mem_Write 会在地址后自动插入控制字节 */ HAL_StatusTypeDef st = HAL_I2C_Mem_Write( &hi2c1, SSD1306_I2C_ADDR, SSD1306_CTRL_CMD, I2C_MEMADD_SIZE_8BIT, &cmd, 1, SSD1306_TIMEOUT); return (st == HAL_OK) ? 0 : 1; } uint8_t ssd1306_hal_write_data(const uint8_t *buf, uint16_t len) { HAL_StatusTypeDef st = HAL_I2C_Mem_Write( &hi2c1, SSD1306_I2C_ADDR, SSD1306_CTRL_DATA, I2C_MEMADD_SIZE_8BIT, (uint8_t *)buf, len, SSD1306_TIMEOUT); return (st == HAL_OK) ? 0 : 1; } void ssd1306_hal_delay_ms(uint32_t ms) { HAL_Delay(ms); }逻辑说明：HAL_I2C_Mem_Write的第二个参数是 8 位从机地址，HAL 内部会左移并补读写位，所以宏里先左移。I2C_MEMADD_SIZE_8BIT表示控制字节占 8 位。超时设 100ms，是因为整屏 1024 字节在 100kHz I2C 下约需 90ms，设太小会误报失败。如果总线被拉死，这个超时能让程序退出而不是死等。
3.2 整屏刷新为什么要按页发送而不是一次 1024 字节
有人图省事，把 1024 字节一次性传给write_data。在 400kHz 下勉强能跑，但 100kHz 下单次传输过长，中间一旦被打断就整屏撕裂。稳妥做法是按页发送，每页 128 字节，页间设置页地址。
/* ssd1306.c —— 按页刷新，兼容低速率 I2C */ void ssd1306_refresh(SSD1306_Handle *h) { if (!h->initialized) return; for (uint8_t page = 0; page < SSD1306_PAGES; page++) { /* 设置页地址：0xB0 | page */ ssd1306_write_cmd(0xB0 | page); /* 列地址低 4 位、高 4 位，从 0 开始 */ ssd1306_write_cmd(0x00); ssd1306_write_cmd(0x10); /* 发送该页 128 字节显存 */ ssd1306_write_data(&h->buffer[page * SSD1306_WIDTH], SSD1306_WIDTH); } }逻辑说明：0xB0|page定位页，0x00和0x10把列地址归零。每页 128 字节，100kHz 下约 11ms，8 页约 90ms，刷新率约 11fps，做文本界面足够。如果要动画，得换 SPI 或提高 I2C 速率。参数上SSD1306_WIDTH固定 128，若用 128×32 屏，页数改成 4，其余不变。
3.3 在 main 里怎么调用才不阻塞业务
库写好后，主循环里只做两件事：改显存、调刷新。不要在刷新前后加长延时，也不要在中断里刷新。
/* main.c —— 典型调用节奏 */ SSD1306_Handle oled; int main(void) { HAL_Init(); SystemClock_Config(); MX_I2C1_Init(); oled.addr = 0x3C; ssd1306_init(&oled); /* 内部会调 hal_init 和命令序列 */ ssd1306_clear(&oled); ssd1306_draw_string(&oled, 0, 0, "STM32 SSD1306", 1); ssd1306_refresh(&oled); while (1) { /* 业务逻辑，比如读传感器 */ /* 需要更新时再改显存并刷新，不必每圈都刷 */ HAL_Delay(100); } }逻辑说明：ssd1306_init内部先调ssd1306_hal_init，再逐条发初始化命令，最后把initialized置 1。刷新只在内容变化时调用，静态界面每 100ms 刷一次是浪费，改成事件驱动更合理。参数上draw_string的最后一个参数 1 表示前景色点亮，0 表示擦除。
4. 避坑与排查：SSD1306 库化过程中最容易翻车的五件事
4.1 屏幕全黑但 I2C 扫描能扫到地址
现象：逻辑分析仪能看到地址应答，屏幕就是不亮。原因：初始化序列里漏了电荷泵命令0x8D,0x14，或者0xAF开启显示没发。解决：把初始化命令逐条打印出来核对，重点确认0x8D和0xAF都在。我一般会在ssd1306_init里加一个返回值，任何一条命令写失败就返回错误码，而不是静默继续。
4.2 显示内容上下颠倒或左右镜像
现象：字能显示，但方向不对。原因：0xA1段重映射和0xC8扫描方向配反了。解决：这两条命令组合决定四个方向，交换0xA1/0xA0翻转左右，交换0xC8/0xC0翻转上下。改完要重新上电，因为这两条在初始化时生效。
4.3 刷新时屏幕出现随机竖条纹
现象：部分列亮暗错乱。原因：显存索引算错，常见于把buffer[x + (y/8)*128]写成buffer[y + (x/8)*128]。解决：用单像素测试，在 (0,0)、(127,0)、(0,63)、(127,63) 四个角各画一个点，看是否落在正确位置。四个角对了，索引就对了。
4.4 换到 SPI 接口后库编译不过
现象：驱动文件里直接引用了hi2c1，换 SPI 后找不到符号。原因：适配层没抽干净，驱动层混入了平台相关代码。解决：检查ssd1306.c里是否出现任何HAL_或hi2c字样，有就挪到ssd1306_hal.c。驱动层只应包含ssd1306.h和标准库头文件。
4.5 长时间运行后屏幕卡死不再刷新
现象：跑几小时后画面冻结，复位才恢复。原因：I2C 总线被从机拉低，HAL 超时后没有恢复机制。解决：在ssd1306_hal_write_cmd返回失败时，调用HAL_I2C_DeInit再MX_I2C1_Init重新初始化总线，并给 SSD1306 重新发一次初始化序列。这个恢复逻辑放在应用层，不要塞进驱动。
5. 让这份库真正可复用：显存局部刷新与字体裁剪
库能跑之后，下一步是让它省资源。整屏刷新 1024 字节，如果只改了一个数字，没必要全发。我一般加一个脏矩形机制：记录本次修改的最小页范围和列范围，刷新时只发这几页。
/* ssd1306.c —— 脏页标记，只刷有变化的页 */ static uint8_t dirty_pages; /* 位图，bit0~bit7 对应 8 页 */ void ssd1306_mark_dirty(uint8_t page) { dirty_pages |= (1 << page); } void ssd1306_refresh_dirty(SSD1306_Handle *h) { for (uint8_t page = 0; page < SSD1306_PAGES; page++) { if (!(dirty_pages & (1 << page))) continue; ssd1306_write_cmd(0xB0 | page); ssd1306_write_cmd(0x00); ssd1306_write_cmd(0x10); ssd1306_write_data(&h->buffer[page * SSD1306_WIDTH], SSD1306_WIDTH); } dirty_pages = 0; }逻辑说明：dirty_pages用位图记录哪几页被改过，draw_pixel内部根据 y 坐标自动置位。刷新时跳过干净页，只改一行文字时通常只涉及 1 到 2 页，数据量从 1024 字节降到 128 到 256 字节。参数上如果做滚动字幕，整屏都在变，脏页机制退化成全刷，这时直接调ssd1306_refresh更省判断。
字体方面，库文件里常带一个 6×8 或 8×16 点阵。6×8 字体每字符 6 字节，128 列能放 21 个字符。裁剪字体时只保留用到的字符，用脚本从完整字模里抽取，能把 Flash 占用从几 KB 降到几百字节。我习惯把字模放在单独的font.c里，用const修饰，链接时自动进 Flash 而不是 RAM。
验证方法很简单：在屏幕上交替显示全亮、全灭、棋盘格三种图案，各刷 100 次，观察有没有残影或闪烁。棋盘格能暴露列地址错位，全亮全灭能暴露电荷泵不稳。这套验证跑通，库基本就能进项目了。血泪经验是，别在没做局部刷新前就上动画，I2C 带宽会教你做人。希望帮到你。
本文还有配套的精品资源，点击获取
