
简介面向STM32嵌入式开发者这份资源提供SSD1306 OLED屏幕的完整驱动代码解决单片机驱动OLED时的初始化配置、字符显示及字模调用问题适用于各类基于STM32的显示交互项目。压缩包共3个文件含2个C源文件和1个头文件整体仅9KB代码精简且便于直接移植到现有工程。已有989人学习下载验证了其在常见开发场景中的实用价值。资源不仅包含显示屏底层驱动主体还提供ASCII字模库支持常用字符与基础图形的显示头文件则清晰暴露接口函数方便快速集成对于刚接触OLED驱动的入门者可参照代码理解屏幕驱动时序控制思路对于进阶开发者也能作为精简驱动框架的参考。整体来看这是一份小巧实用的STM32外设驱动示例适合需要快速点亮OLED屏幕并完成基础显示功能的开发者。1. 一块 128x64 的黑白屏为什么让无数工程卡在初始化序列上调一块 SSD1306 的 OLED最典型的翻车现场是代码编过了上电一看黑屏把对比度调到最大还是黑屏翻遍资料最后发现是初始化序列里电荷泵开关没开。SSD1306 这块 128x64 黑白屏驱动逻辑其实很直白——先配寄存器再往显存写数据芯片自己把显存扫到屏上。用 STM32 接它难点不在 I2C 或 SPI 时序本身而在几件没人提前说清的事I2C 地址到底要不要左移、初始化命令每个字节是什么含义、显存按页排列导致画点坐标要想一下、整帧刷新要 1KB 数据所以容易闪。这篇文章按我实际调屏的路径来写从接口选型、硬件连接、初始化代码到画点、字库和五个高频坑最后给两个把刷新率逼上去的手段。适合正在用 STM32 调 0.96 寸屏、以及准备把驱动移植到新平台的人。2. 选 I2C 还是 SPI先定传输通道再谈驱动代码2.1 两种接口的带宽、引脚与适用场景对比SSD1306 控制芯片本身支持并行 6800/8080、SPI、I2C 四种接口实际做产品时并行口要先排除8 根数据线加读写控制线挤占 GPIO 太严重新设计基本没人用。剩下 SPI 和 I2C 之争本质是带宽换引脚。I2C 是开漏输出外部要有上拉电阻标准模式 100kHz快速模式 400kHzSPI 是推挽输出时钟随便跑几 MHz。老手算一笔账就明白128x64 分辨率分成 8 个 page每 page 128 字节整帧显存正好 1KB。400kHz 的 I2C 每字节需要 9 个时钟位8 位数据加 1 位 ACK传 1KB 要 23ms 左右换算成帧率只有 40fps 出头加上 corners 和 START/STOP 开销实际 30fps 都勉强SPI 跑 4MHz 时同样的 1KB 只要 2.5ms。我习惯按场景选只做静态菜单、仪表数值、调试信息输出I2C 四根线干净利落要跑动画、滚屏、波形绘制这类连续变化内容直接上 SPI别跟带宽较劲。对比项I2CSPI数据线数量SCL SDA 两根SCLK MOSI CS DC最少四根典型时钟100kHz / 400kHz4MHz 起步上限看模块整帧 1KB 传输耗时约 23ms 400kHz约 3ms 4MHz抗干扰能力开漏加长线容易波形畸变推挽驱动强得多常见模块形态4 针VCC/GND/SCL/SDA7 针多出 RES/DC/CS推荐场景静态界面、低功耗、引脚紧张动画、高速刷新、波形绘制2.2 四针模块的连接与上拉电阻硬件错一根线都是玄学拿到最常见的 4 针 SSD1306 模块正面印着 VCC、GND、SCL、SDA。接线表看着简单坑全在细节里。VCC 接 3.3V 没问题接 5V 也没问题SSD1306 内部有稳压但 STM32 的 I2C 引脚是 3.3V 电平模块如果按 5V 逻辑设计SDA/SCL 上的 5V 高电平可能通过引脚保护二极管倒灌进 MCU稳妥做法是统一 3.3V 供电。SCL 和 SDA 默认接 PB6/PB7 还是 PB8/PB9取决于 CubeMX 里 I2C 外设分配到哪个引脚跑 I2C1 就按 CubeMX 分配的来不用照着网上例程硬抄引脚。注意 I2C 是开漏协议总线必须靠上拉电阻拉高。大多数模块板载了 4.7k 上拉接上就能用也有个别裸屏没有需要在 SCL、SDA 上各加一颗 4.7k 到 3.3V。判断方法很简单用万用表量 SDA 对 3.3V 的电压空闲时应该接近 3.3V如果量出来是 0V说明上拉缺失你在这块板上做再多软件配置都是白费。CubeMX 里 I2C 参数我常用I2C Speed Mode 选 Fast Mode400kHz时钟频率按要求保持 400KHz 以内。地址先填 0x3C 还是 0x78 先别管这里留到下一章一起说接线阶段只要保证 SCL/SDA 没接反、VCC/GND 没接反剩下的软件可以覆盖。2.3 用逻辑分析仪确认地址和时序基线调屏的第一步不是写代码而是确认线上确实有 I2C 通信。先跑一个最小的 Scan 程序或者直接在初始化函数里对地址 0x78 发一个命令然后用逻辑分析仪夹 SCL 和 SDA采样率设到 1MHz 以上抓传输波形。正常情况应该看到无数据传输时 SCL、SDA 都是高电平然后 SDA 在 SCL 高电平期间拉低产生 START接着发出地址字节。这个地址字节是关键——0x3C 的 7 位从机地址左移一位写方向就是 0x78所以逻辑分析仪解析出的第一帧应该是 0x78随后紧跟 ACK 低电平。如果只看到 START 之后地址字节发出去但 ACK 位是高电平说明地址发错了或者从机根本没上电。这一步能省掉后面 90% 的排查时间。很多人在黑屏时反复改初始化序列其实问题在硬件层逻辑分析仪一抓哪个环节断的清清楚楚。没有逻辑分析仪的话最低成本的替代方案是写一个 I2C 设备地址扫描函数把 0x00 到 0x7F 全发一遍看 0x3C 附近哪个地址有 ACK 响应快速确认从机在不在总线上。3. 读写 SSD1306 的两步走控制字节与初始化命令序列3.1 控制字节的 Co/D/C 位决定了命令和数据怎么发SSD1306 在 I2C 模式下有两条通道写命令和写显存数据区别就在控制字节上。每次 I2C 传输设备地址字节之后紧跟一个控制字节0x00 表示后续字节全是命令0x40 表示后续字节全是显存数据。这个 0x00/0x40 不是随便定的对应控制字节里的两位Co 位为 0 表示后续数据连续跟随D/C# 位为 0 表示命令、为 1 表示数据。理解这个后你就明白为什么网上所有驱动都长一个样写单个命令时发两个字节先是 0x00 再是命令值写显存时先发 0x40 再发数据。有一点容易被忽略——每次调用 HAL 的HAL_I2C_Master_Transmit都会重新产生 START 条件所以每次传输都必须从头带控制字节不能把上一帧的控制字节延续下去。频繁刷屏时这会让总线上多出一堆 START/STOP但这是 I2C 协议的代价后面会用 DMA 和局部刷新补回来。3.2 初始化序列逐条拆解9 个关键寄存器命令SSD1306 上电后不会自动进入可用状态必须按固定顺序写一串寄存器配置。网上能搜到各种版本的初始化序列有的 25 条有的 30 条其中大部分可以统一收敛成下面这个最小可靠集合命令字节参数作用0xAE无关闭显示改寄存器前必须先关屏0xA80x3F多路复用比64 行对应 64 像素高度0xD30x00显示偏移为 00x40无起始行 00x8D0x14开启电荷泵黑屏头号杀手0x200x02页寻址模式配合 1KB 显存分页操作0xA1无段重映射正常方向反了会左右镜像0xC8无COM 扫描方向正常反了会上下颠倒0xDA0x12COM 引脚硬件配置128x64 屏固定 0x120x810xCF对比度低亮度屏可往上调0xD90xF1预充电周期花屏时可调0xDB0x40VCOMH 电平对显示均匀度有影响0xA4无输出跟随 RAM 内容0xA6无正常显示0xA7 是反显0xAF无开启显示最后一步其中 0x8D 0x14 这条必须单独记电荷泵不打开屏幕永远黑着而且不会报任何错误I2C 通信一切正常就是什么都不显示。0x81 对比度、0xD9 预充电、0xDB VCOMH 这三组是玄学参数同一块屏不同批次表现都可能不同后面避坑章节会细说。0x20 0x02 选页寻址模式也重要水平寻址模式在处理跨页连续数据时行为不一样驱动里页寻址配合画点函数最直观。3.3 基于 HAL 库的最小读写代码命令、数据、初始化三件套写驱动前先把地址问题钉死。SSD1306 的 7 位从机地址由 SA0 引脚决定接地时为 0x3C接 VCC 时为 0x3D。但 STM32 HAL 库的 I2C 地址参数要求的是左移一位后的 8 位地址也就是 0x78 或 0x7A。直接把手册上的 0x3C 填进HAL_I2C_Master_Transmit实际总线上发出的地址是 0x3C 这个值对应的地址从机根本不认。#define OLED_ADDR_7BIT 0x3C /* 模块背面 SA0 焊盘接地时的值 */ #define OLED_ADDR_HAL (OLED_ADDR_7BIT 1) /* HAL 需要 8 位地址0x78 */ static uint8_t txBuf[1 128]; /* 1 字节控制字节 一页 128 字节数据 */ static HAL_StatusTypeDef SSD1306_WriteCmd(I2C_HandleTypeDef *hi2c, uint8_t cmd) { uint8_t buf[2] {0x00, cmd}; /* 控制字节 0x00 表示后续是命令 */ return HAL_I2C_Master_Transmit(hi2c, OLED_ADDR_HAL, buf, 2, HAL_MAX_DELAY); } static HAL_StatusTypeDef SSD1306_WriteData(I2C_HandleTypeDef *hi2c, const uint8_t *data, uint16_t len) { txBuf[0] 0x40; /* 控制字节 0x40 表示后续是显存数据 */ memcpy(txBuf[1], data, len); return HAL_I2C_Master_Transmit(hi2c, OLED_ADDR_HAL, txBuf, len 1, HAL_MAX_DELAY); }逻辑说明写命令函数只发 2 字节地址后直接跟 0x00 和命令值适合初始化序列里逐个命令调用。写数据函数把控制字节和数据拼进同一块连续内存一次Master_Transmit完成一整页 128 字节的传送避免逐字节调用 HAL 函数导致的总线开销爆炸。参数说明txBuf大小按 1128 设计正好匹配 SSD1306 一页的宽度len最大只能传 128超过要拆成多次HAL_MAX_DELAY表示阻塞等待传输完成简单可靠但会占着 CPU后面 DMA 会替换它。初始化函数按手册流程走完整序列。注意 0xAF 开显示必须放在显存清空之后否则上电瞬间 RAM 里的随机值会闪一下static const uint8_t ssd1306_init_cmds[] { 0xA8, 0x3F, /* 多路复用比 64 */ 0xD3, 0x00, /* 显示偏移 0 */ 0x40, /* 起始行 0 */ 0x8D, 0x14, /* 电荷泵开启 */ 0x20, 0x02, /* 页寻址模式 */ 0xA1, /* 段重映射 */ 0xC8, /* COM 扫描方向 */ 0xDA, 0x12, /* COM 引脚配置 */ 0x81, 0xCF, /* 对比度 */ 0xD9, 0xF1, /* 预充电周期 */ 0xDB, 0x40, /* VCOMH */ 0xA4, /* 输出跟随 RAM */ 0xA6 /* 正常显示 */ }; void SSD1306_Init(I2C_HandleTypeDef *hi2c) { HAL_Delay(50); /* 给模块上电稳定时间无 RES 引脚时靠它顶替硬件复位 */ SSD1306_WriteCmd(hi2c, 0xAE); /* 先关显示再改寄存器 */ for (uint16_t i 0; i sizeof(ssd1306_init_cmds); i) { SSD1306_WriteCmd(hi2c, ssd1306_init_cmds[i]); } SSD1306_ClearScreen(); SSD1306_Refresh(hi2c); SSD1306_WriteCmd(hi2c, 0xAF); /* 清完屏再开显示避免上电花屏 */ }逻辑说明初始化命令全部集中在常量数组里方便后续调参数时只改一处。HAL_Delay(50)在模块没有 RESET 引脚时是必须的没有这个延时电荷泵可能在电压没稳定时提前启动表现为偶发黑屏。代码里的SSD1306_ClearScreen和SSD1306_Refresh是下一章的函数这里先声明使用。4. 从画点到中文1KB 显存与帧缓冲方案4.1 页与列的映射关系为什么画点要先除 8SSD1306 内部有 1KB 显存但它的组织方式跟普通的二维数组不一样。它把 64 行像素分成 8 个 page每个 page 高 8 像素、宽 128 像素一个 page 正好 128 字节。往显存里写某个字节时这个字节的 bit0 对应 page 内第 0 行bit1 对应第 1 行以此类推bit7 对应第 7 行。这意味着如果你想在 (x, y) 处画一个点不能直接写坐标要先算出来这个点落在哪个 page也就是 y 除以 8 取整它在 page 内的第几位也就是 y 对 8 取余。页寻址模式下写完一个字节列地址自动加 1所以同一 page 的 128 字节可以连续发这正好匹配SSD1306_WriteData一次传一页的设计。在 MCU 内存里维护一张 8x128 的帧缓冲表所有绘图操作先改这个缓冲再一次性推到屏幕这是 SSD1306 驱动最标准的做法。直接往屏幕写单个点是灾难——清屏后再画一个点要重刷整页闪烁肉眼可见。4.2 画点、清屏、整帧刷新最基础的三个函数帧缓冲区定义成uint8_t frameBuf[8][128]第一维是 page第二维是列。画点函数负责坐标换算清屏函数用 memset 把整块缓冲清零刷新函数逐页推送到显存#define SSD1306_WIDTH 128 #define SSD1306_HEIGHT 64 #define SSD1306_PAGES (SSD1306_HEIGHT / 8) /* 8 页 */ static uint8_t frameBuf[SSD1306_PAGES][SSD1306_WIDTH]; void SSD1306_DrawPixel(uint16_t x, uint16_t y, uint8_t on) { if (x SSD1306_WIDTH || y SSD1306_HEIGHT) { return; /* 越界直接丢弃防止写穿缓冲区 */ } uint8_t page y 3; /* 等价于 y / 8取整数部分 */ uint8_t bit 1 (y 0x07); /* 等价于 y % 8取余数再移位 */ if (on) { frameBuf[page][x] | bit; } else { frameBuf[page][x] ~bit; } } void SSD1306_ClearScreen(void) { memset(frameBuf, 0x00, sizeof(frameBuf)); /* 全屏熄灭 */ } void SSD1306_Refresh(I2C_HandleTypeDef *hi2c) { for (uint8_t page 0; page SSD1306_PAGES; page) { SSD1306_WriteCmd(hi2c, 0xB0 page); /* 设置页地址 */ SSD1306_WriteCmd(hi2c, 0x00); /* 列地址低 4 位 */ SSD1306_WriteCmd(hi2c, 0x10); /* 列地址高 4 位 */ SSD1306_WriteData(hi2c, frameBuf[page], SSD1306_WIDTH); } }逻辑说明SSD1306_DrawPixel用位运算替代除法和取余是为了在 Cortex-M 上省几条指令y3 和 y0x07 是编译器最友好的写法。刷新函数先发页地址命令 0xB0page再发列地址低字节 0x00 和高字节 0x10让芯片内部列计数器归零然后整页数据一次性写入。参数说明0xB0 到 0xB7 是 8 个 page 的起始地址命令0x00、0x10 组合表示列地址从 0 开始刷新是整页 128 字节连续发中间没有额外的控制字节。4.3 字符与中文显示字模取模方向决定了坐标系显示字符的常规做法是在 flash 里存字模数组画点时按位遍历。ASCII 字符用 5x7 点阵每个字符 5 字节取模方向是逐列式——第一个字节是第 0 列从上到下的 8 个 bit第二个字节是第 1 列。这样画字符时按列展开正好落在 frameBuf 的同一 page 内const uint8_t font5x7[][5] { /* 空格 0x20 到 波浪号 0x7E 的字模数据这里省略具体值 */ }; void SSD1306_DrawChar(uint16_t x, uint16_t y, char c) { if (c 0x20 || c 0x7E) { c ?; /* 不可见字符统一显示为问号 */ } const uint8_t *glyph font5x7[c - 0x20]; for (uint8_t col 0; col 5; col) { for (uint8_t row 0; row 7; row) { if (glyph[col] (1 row)) { SSD1306_DrawPixel(x col, y row, 1); } } } } void SSD1306_DrawString(I2C_HandleTypeDef *hi2c, uint16_t x, uint16_t y, const char *str) { while (*str) { SSD1306_DrawChar(x, y, *str); x 6; /* 5 点宽加 1 点字间距 */ } SSD1306_Refresh(hi2c); /* 字符串画完统一刷一帧 */ }逻辑说明取模方向是这套代码里最容易踩坑的地方。字符字模通常是逐列式但中文 16x16 字模在不同的取模软件里默认方向不一样有的默认逐行式生成的数据直接套进DrawChar会显示成乱码或上下错位。参数说明x 6是字符步进如果字模宽度不是 5这里的间距要跟着改SSD1306_DrawString在整串画完后只刷新一次避免逐字符刷新造成闪烁。中文字模的做法同理只是 16x16 点阵占 32 字节取模时必须统一设置为逐列式、从左到右、从上到下、每个字节高位在前。我常用的套路是先在取模软件里生成一个 16x16 的测试字模依次画到屏幕四角对比方向确认方向正确后再批量生成整个字库。这一步验证花半小时能省后面所有中文显示的相关麻烦。5. 避坑手册上电不亮、花屏、闪烁与镜像的排查路径5.1 上电不亮且无 ACK地址左移和接线是两个高频原因现象程序正常运行初始化函数没有任何报错但屏幕全黑逻辑分析仪抓 I2C 波形只看到 START 后地址字节没有 ACK 低电平响应。原因最常见的是 HAL 地址参数填了手册里的 7 位地址 0x3C。手册给的是从机地址I2C 总线上实际传输的地址字节是 7 位左移加读写位写方向应该是 0x78。HAL 库的DevAddress要的是 0x78你传 0x3C 就等于请求地址 0x1E 的从机总线上的 SSD1306 自然不回应。其次是 SCL 和 SDA 接反四针模块没有防呆设计两根线颜色接近时特别容易反。解决地址参数全部改用OLED_ADDR_HAL宏也就是 0x78确认 0x3C 和 0x3D 的区分来自模块背面 SA0 焊盘改成 0x7A 再试对调 SCL/SDA 换一根杜邦线继续抓波形。上电不亮这类问题优先看波形别反复改初始化代码浪费时间。5.2 花屏与亮度异常电荷泵、对比度、预充电三个调节点现象屏幕有显示但整体偏暗或者背景有隐约的噪点颗粒甚至出现不规则的残影花斑。原因电荷泵没开是最硬的伤表现为纯黑屏如果显示存在但亮度异常则多半是 0x81 对比度值太低或者 0xD9 预充电周期、0xDB VCOMH 电平这几个参数和屏幕硬件批次不匹配。低功耗设计中有人故意压低对比度省电但压过头就是看不清。某些劣质模块的电压转换电路纹波大VCOMH 偏低还会让背景发灰。解决对比度 0x81 从 0x7F 起步往上试取模模块常见表现是 0xCF 左右最均衡预充电周期 0xD9 在 0xF1 附近调整值太小电荷预充不足会沿扫描方向出现亮度不均VCOMH 0xDB 在 0x20 到 0x40 之间试背景有噪点就调大。调这三个参数时把屏幕显示一张纯白图肉眼对比最直观。5.3 左右镜像和上下颠倒段重映射与 COM 扫描方向现象按坐标画一个矩形显示出来左右是反的或者上下颠倒偶尔两个同时反看起来像旋转了 180 度。原因SSD1306 的显示方向由两个寄存器控制——0xA0/0xA1 控制段重映射决定列地址从左还是从右开始0xC0/0xC8 控制 COM 扫描方向决定行地址从上还是从下开始。初始化序列里少写 0xA1 或者误写 0xA0屏幕就是镜像的。很多网上例程为了适配不同模块会故意写反直接抄过来就容易踩。解决用四个角定位法确认方向——在左上、右上、左下、右下各画一个点看实际显示位置哪个方向反了就改对应寄存器。0xA0 改 0xA1 解决左右0xC0 改 0xC8 解决上下两个都反就同时改。改完镜像方向后续所有绘图坐标都以实际显示为准不需要在画点函数里做额外翻转。5.4 刷新闪烁与拖影带宽是物理瓶颈现象整屏刷新时肉眼可见闪烁滚动画面对比度低的区域会拖出残影感尤其在菜单切换时上下两部分明显不同步。原因I2C 400kHz 下刷新 1KB 显存需要 23ms加上命令开销实际要 30ms一帧 33ms 勉强到 30fps 的下限。逐页发送时页面之间还有列地址重置的命令交错视觉上就容易感知到刷新过程的中间态。SPI 版本很少出现这个问题因为带宽高一个数量级。解决第一条路是局部刷新只重画变化区域第二条路是改用 SPI 或并行接口的模块第三条路是 DMA 加双缓冲把刷屏时间从 CPU 阻塞式传输里剥离出来。局部刷新的收益最直接——一个 128x16 的区域只要传 2KB 级别的数据在 400kHz 下耗时降到 5ms 左右肉眼完全感知不到。具体的脏矩形方案在下一章展开。6. 进阶技巧用 DMA 和脏矩形把刷新率逼上去6.1 DMA 传输替代阻塞式刷屏阻塞式HAL_I2C_Master_Transmit刷新一整页要占 CPU 大约 3ms8 页刷完 25ms 内 CPU 一直在等 I2C。改用 DMA 后I2C 外设自己搬运数据CPU 可以回去跑 UI 逻辑。注意 DMA 传输期间txBuf不能被改写所以每页发送后要等传输完成事件static volatile uint8_t dmaBusy 0; void HAL_I2C_TxCpltCallback(I2C_HandleTypeDef *hi2c) { dmaBusy 0; /* 当前页发送完成允许填充下一页 */ } HAL_StatusTypeDef SSD1306_RefreshPageDMA(I2C_HandleTypeDef *hi2c, uint8_t page) { while (dmaBusy) { /* 等上一页发完避免覆盖 txBuf */ } txBuf[0] 0x40; memcpy(txBuf[1], frameBuf[page], SSD1306_WIDTH); dmaBusy 1; return HAL_I2C_Master_Transmit_DMA(hi2c, OLED_ADDR_HAL, txBuf, 1 SSD1306_WIDTH); }逻辑说明dmaBusy标志位是双缓冲的雏形DMA 正在读txBuf时主程序不能写它否则画面会出现随机撕裂条纹。实际工程里会把txBuf扩成两个一个给 DMA 用一个给主程序填充完成回调里互换角色这样刷屏和绘图可以完全并行。6.2 脏矩形刷新只发送变化的部分静态界面里真正变化的往往只有时钟数字、进度条、或者一个电量图标。维护一份上一帧的缓冲每次绘图后对比当前帧和上一帧找出变化区域的边界只刷新这个矩形覆盖到的那几页void SSD1306_RefreshRect(I2C_HandleTypeDef *hi2c, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { uint8_t startPage y0 3; uint8_t endPage y1 3; for (uint8_t page startPage; page endPage; page) { SSD1306_WriteCmd(hi2c, 0xB0 page); SSD1306_WriteCmd(hi2c, 0x00); SSD1306_WriteCmd(hi2c, 0x10); SSD1306_WriteData(hi2c, frameBuf[page][x0], x1 - x0 1); } }逻辑说明页寻址模式下第 0 页到第 7 页是独立的只刷新脏矩形覆盖到的那几页每页也只从 x0 发到 x1传输量从整帧 1KB 降到几百字节。参数说明x0、y0 是左上角x1、y1 是右下角调用前要保证 x0x1、y0y1。这个函数配合系统心跳每秒刷新时钟区域 20 次I2C 负载也远低于整帧刷新。我自己的习惯是把初始化命令数组、帧缓冲、刷新函数拆成独立模块调屏时所有的玄学参数都放在初始化数组里集中改改一次记录一次现象。这样屏幕异常时不是靠猜而是翻记录对比是哪个参数动过。这套驱动写完后再回头看真正花时间的从来不是 I2C 时序而是初始化参数、取模方向和刷新策略这些一开始没意识到的细节。希望帮到你。本文还有配套的精品资源点击获取