简介面向嵌入式开发者的OLED屏驱动代码基于SSD1306/SSD1315控制器覆盖I2C/SPI两种通信方式下的初始化、像素绘制、字符与图形显示、刷新控制以及对比度与显示模式配置。资源包为zip格式共4个文件全部为.c与.h源码文件驱动控制与字库数据分模块组织大小仅13KB结构精简。已有349人学习下载。代码按模块化思路设计将硬件通信细节封装在底层与具体单片机平台保持解耦便于快速移植开发者既能直接嵌入小型便携设备或智能穿戴项目也可对照控制器手册逐步理解显示驱动的寄存器映射与调用流程。由于OLED像素可独立控制、无需背光这类驱动还能帮助学习者掌握灰度等级显示、局部刷新的实现思路为后续图形界面、菜单动画等功能扩展打下基础。 前两天帮朋友调一块0.96寸OLEDI2C接口背面的丝印清清楚楚写着SSD1315。我图省事直接套用以前那套SSD1306的驱动代码结果屏幕只亮了下半截换一个牌子的屏又一切正常。这种“同一份驱动代码在不同OLED模块上表现不一致”的毛病搞嵌入式的人多少都撞见过。今天干脆把OLED驱动代码SSD1306/SSD1315从原理到STM32 HAL库落地完整写一遍把我验证过的初始化序列、踩过的地址坑、汉字显示思路全部放出来给准备用STM32、GD32这类MCU驱动0.96寸、0.91寸、1.3寸OLED显示模块的朋友做个参考。文章不追求把每个寄存器都翻一遍重点是把驱动代码真正拆开看明白I2C怎么发指令、GDDRAM怎么对应像素、初始化序列每一条在干什么以及最后两批屏幕放一起显示不一致时怎么处理。1. 选型之前先搞清楚SSD1306与SSD1315到底差在哪1.1 两颗芯片的关系和常见模块很多同学把SSD1315当成SSD1306的“马甲”这个理解不算准确但也不能说全错。SSD1306是Solomon Systech早年推出的单色OLED驱动IC支持128x64和128x32两种常见分辨率SSD1315是它的低功耗改进版本主要面向便携设备、电池供电场景。两者在内核逻辑上非常接近GDDRAM组织方式一致绝大多数指令也互相兼容因此市面上0.96寸、0.91寸、1.3寸模块用同一份驱动代码基本都能点亮。“基本能点亮”这个说法本身就埋着坑。你从不同店铺买回三块看起来一模一样的0.96寸屏实际主控可能是SSD1306可能是SSD1315还有可能是国产兼容芯片甚至同一型号屏幕不同批次用的主控也不一样。背面的丝印能参考但别全信。最稳妥的做法是拿到模块后先按SSD1306的标准初始化跑一遍再针对性测试几个SSD1315容易出问题的寄存器值而不是上来就怀疑自己的I2C代码写错了。1.2 指令集与初始化序列的兼容边界从驱动代码的角度看SSD1315对SSD1306的大部分指令做了兼容但不是无条件照单全收。实测下来差异最容易集中在显示初始化里那几个模拟电路相关的寄存器上典型的就是0x8D Charge Pump、0xDB VCOMH电平选择。SSD1306常见的VCOMH值是0x40但部分SSD1315批次对这个值更敏感容易出现整体发虚、重影、或者某个区域亮度不均匀改成0x30反而一切正常。另一个高频差异是分辨率配置。如果你的模块是0.91寸128x32初始化里0xA8后面跟的Multiplex Ratio要从0x3F改成0x1F0xDA后面的COM引脚硬件配置要从0x12改成0x02扫描方向通常也要用0xC0而不是0xC8。不改的话症状就是只亮上半屏或者显示内容上下颠倒、位置错乱。这跟驱动函数本身没关系是初始化序列没有适配屏的物理行数。我整理了这两颗芯片在驱动层面最值得关注的对比写驱动前可以先扫一眼对比项SSD1306SSD1315常见模块0.96寸128x64、1.3寸128x640.91寸128x32、0.96寸低功耗版显存组织128x64128x32或128x64视具体型号指令体系I2C/SPI与SSD1306兼容功耗表现常规低功耗优化睡眠电流更低驱动代码常见坑VCOMH取值在不同国产屏上手感不同0xDB取值敏感128x32需改MUX和COM配置1.3 驱动能力与功耗的取舍代码里体现不出来的还有功耗。SSD1315的低功耗特性主要体现在进入睡眠模式后的电流控制SSD1306在这块确实要差一些。如果产品是纽扣电池或者小容量锂电池供电同样一块0.96寸屏选SSD1315型号能明显延长待机时间。但如果只是开发板、仪器面板这类外接电源场景这两者在点亮状态下电流差距不大没必要为了这点差异过度纠结选型反而应该把精力放在初始化序列的兼容性上。2. 驱动代码的三块基石I2C指令通道、GDDRAM映射与初始化序列2.1 区分命令与数据I2C通道的第一规则OLED的I2C通信和普通传感器不太一样。传感器一般是“寄存器地址数据”OLED则是“控制字节数据”。控制字节0x00表示后面跟的是命令0x40表示后面跟的是显存数据。很多新手拿着逻辑分析仪抓包看到一长串0x00、0x40、0xA8、0x3F这些十六进制数第一反应是数据乱了其实0xA8、0x3F就是一条“设置多路复用比”的命令只是前面那个0x00告诉屏幕“下面这个是命令”。用STM32 HAL库写驱动最简单的方式是借用HAL_I2C_Mem_Write把控制字节当成“寄存器地址”传进去看起来有点投机取巧但实际效果完全正确也省去自己拼I2C起始、停止、NACK这些底层的麻烦#define OLED_I2C_ADDR 0x78 // 7位地址0x3C左移一位HAL库用8位地址格式 void OLED_Write_Cmd(uint8_t cmd) { HAL_I2C_Mem_Write(hi2c1, OLED_I2C_ADDR, 0x00, I2C_MEMADD_SIZE_8BIT, cmd, 1, 100); } void OLED_Write_Data(uint8_t data) { HAL_I2C_Mem_Write(hi2c1, OLED_I2C_ADDR, 0x40, I2C_MEMADD_SIZE_8BIT, data, 1, 100); }调用OLED_Write_Cmd(0xA8)等价于在总线上发送设备地址0x78、控制字节0x00、命令字节0xA8。屏幕收到后就知道0xA8是命令接下来再收到0x3F也知道这是刚才那条命令的参数。后面写显存数据时把MemAddress换成0x40同样一次发送多字节屏幕就会把后面的数据都当成像素内容写进GDDRAM。2.2 GDDRAM怎么变成屏幕上的点SSD1306/SSD1315内部有1KB显存但它不是按我们直觉的“一行一行”来排的。整个显存被分成8个Page每个Page代表8行像素每个Page里又横向排列128列。也就是说Page 0对应第0到第7行Page 1对应第8到第15行以此类推。往某个Page、某一列写入一个字节这个字节的bit0对应的是该Page里的最上面一行bit7对应最下面一行。这个结构直接决定了写驱动函数的方式。要在屏幕上打一个点比如坐标(x, y)不能像写TFT那样直接给两个字节坐标需要把y坐标换算成Page编号page y / 8然后在别人写的驱动里经常看到OLED_SetPos(page, x)这种函数本质是往显存“定位光标”。理解了GDDRAM的分页结构再去看各种开源驱动的SetPos函数就不会觉得那段0xB0、0x00、0x10的地址计算是天书了。void OLED_SetPos(uint8_t page, uint8_t x) { // 页地址0xB0~0xB7 OLED_Write_Cmd(0xB0 page); // 列地址低4位 OLED_Write_Cmd(0x00 (x 0x0F)); // 列地址高4位 OLED_Write_Cmd(0x10 ((x 4) 0x0F)); }2.3 初始化序列的逐条解读很多人的驱动代码是从网上下载的直接OLED_Init()就完事从没想过那一串寄存器到底在干什么。真出问题的时候都不知道该改哪里。下面这段是我在多个SSD1306和SSD1315模块上验证过的初始化序列每条都写了注释void OLED_Init(void) { uint8_t cfg[] { 0xAE, // 关闭显示初始化期间避免花屏 0xD5, 0x80, // 显示时钟分频/振荡频率 0xA8, 0x3F, // 多路复用比0x3F表示64行 0xD3, 0x00, // 显示偏移不偏移 0x40, // 显示起始行第0行 0x8D, 0x14, // 开启Charge Pump升压 0x20, 0x02, // 页寻址模式 0xA1, // 列地址127映射到SEG0 0xC8, // COM扫描方向重映射 0xDA, 0x12, // COM引脚硬件配置 0x81, 0xCF, // 设置对比度 0xD9, 0xF1, // 预充电周期 0xDB, 0x40, // VCOMH电平SSD1315发虚时改0x30 0xA4, // 整屏显示跟随显存内容 0xA6, // 正常显示不反色 0xAF // 打开显示 }; for (int i 0; i sizeof(cfg); i) OLED_Write_Cmd(cfg[i]); OLED_Clear(); }这里重点说三个容易出问题的点。第一0x20后面的寻址模式0x02是页寻址适合写字符和简单图形后来自动翻页的横向寻址0x00更适合整屏图片刷新但绘制函数要跟着改逻辑。第二0xA1和0xC8是屏幕镜像控制的组合拳如果显示内容左右或上下颠倒基本就是这两条和屏的接线方向不匹配。第三0xDB后面的VCOMH值是SSD1306和SSD1315差异最容易爆发的地方后面专门讲兼容性问题时会再展开。2.4 打点与清屏一切绘制的基础有了初始化剩下就是最底层的打点和清屏。清屏本质上就是往整块GDDRAM写0x00。用页寻址模式的话从Page 0到Page 7每页连续写128个字节0就能清干净void OLED_Clear(void) { uint8_t zero[128] {0}; for (uint8_t i 0; i 8; i) { OLED_SetPos(i, 0); HAL_I2C_Mem_Write(hi2c1, OLED_I2C_ADDR, 0x40, I2C_MEMADD_SIZE_8BIT, zero, 128, 100); } }这样一次事务就把一整页128列全部刷成0比循环调用128次OLED_Write_Data(0)快得多。打点函数无非就是在对应Page里把某个bit位置1或清零但要注意一点在没有读回显存能力的普通I2C OLED上想单独改一个点最好先维护一份软件缓冲再整体刷新区域否则你得先把原来那8个bit读回来再做“或/与”操作。这也是很多高级驱动干脆用1KB数组存一份显存镜像的原因。3. STM32 HAL库落地一套能直接跑通且方便移植的驱动3.1 CubeMX里最容易忽略的三个配置如果你用STM32CubeMX生成工程先别急着写代码I2C参数有三个地方非常容易踩坑。第一个是I2C速度CubeMX默认可能是100kHz有些教程让你硬改到400kHz模块用短杜邦线连开发板没问题一旦线拉长到10厘米以上400kHz下偶发通信错误屏幕就会出现随机雪花点、局部不刷新。我的习惯是默认先用100kHz把功能跑起来再根据硬件环境决定是否提速。第二个是设备地址。这里信息密度很高很多新手在这里反复横跳屏幕背面的丝印如果写的是0x78那是包含写位的8位地址对应7位地址0x3CHAL库的DevAddress参数直接填0x78如果丝印写0x7A说明SA0引脚被拉高对应7位地址0x3DHAL库填0x7A。千万不要填完0x78又看到某些例程写0x3C就迷茫其实是不同库对“设备地址”的定义不同。第三个是引脚和上拉。OLED模块一般板载I2C上拉电阻但有些超薄模块为了省成本没有贴。如果总线一直卡在HAL_I2C_GetState上或者屏幕能亮但第一个字符偶尔乱码优先检查SDA/SCL上拉电阻不要急着怀疑代码逻辑。3.2 接口约定与文件组织驱动代码最好分成两层底层只负责“往I2C总线上发一个字节/一段数据”上层负责显示逻辑。这样以后换MCU平台或者把I2C换成SPI接口屏只需要改底层两三个函数上层完全不用动。头文件里的宏定义和组织方式可以参考这样#ifndef __OLED_H #define __OLED_H #define OLED_I2C_ADDR 0x78 void OLED_Init(void); void OLED_Clear(void); void OLED_SetPos(uint8_t page, uint8_t col); void OLED_ShowChar(uint8_t x, uint8_t y, char ch, uint8_t size); void OLED_ShowString(uint8_t x, uint8_t y, char *str, uint8_t size); void OLED_ShowCHinese(uint8_t x, uint8_t y, const uint8_t *font); #endif上面这套接口里x、y坐标的语义要统一。有些开源库用的是“页列”坐标有些用“像素坐标”混用时极容易错位。我的建议是统一用像素坐标第0列到第127列、第0行到第63行内部在SetPos这一层再做page y / 8的换算。这样到了显示字符串和汉字的阶段逻辑清晰很多。另外提一个和OLED_I2C_ADDR有关的移植细节某些版本的HAL实现要求DevAddress传7位地址0x3C而不是0x78第三方库更是各写各的。移植时先确认I2C通信是否返回HAL_OK如果一直返回HAL_ERROR大概率就是地址格式问题。用HAL_I2C_IsDeviceReady快速检测一下能少走很多弯路。3.3 进一步优化整屏缓冲与DMA思路基础驱动能跑通以后如果你的应用要做菜单切换、翻页动画、动态波形建议引入整屏缓冲。在STM32F103这种RAM有20KB的芯片上拿出1KB给OLED做显存镜像毫无压力。界面逻辑先在缓冲里改数据需要刷新时一次性把整个缓冲或者改动过的Page刷过去这样能避免“打一个点刷一次屏”导致的闪屏和I2C总线拥挤。更进一步可以用DMA配合I2C做异步刷新。先用CPU把要显示的整块数据放到内存再启动I2C DMA传输CPU继续干别的活传输完成再进中断收尾。不过DMA刷新有个细节OLED一次数据传输最好不要跨越1KB边界否则部分DMA外设配置要额外处理我就见过刷新到一半画面突然花掉的情况排查半天才发现是DMA跨边界问题。4. 汉字显示这样做字模提取、编码解析与存储取舍4.1 ASCII字模的存放与绘制先解决英文字符。大家常说的“16x16字体”和“8x16字体”并不是把每个像素存成1个bit而是按列或按行打包成字节。以8x16字符为例每个字符占16个字节每两个字节代表一列像素一个字节的bit0对应最上方像素。驱动里维护一张const uint8_t F8x16[][16]表显示字符时先用ch - 0x20算出在表中的偏移再把对应的字节依次写到当前Page的每一列void OLED_ShowChar(uint8_t x, uint8_t y, char ch, uint8_t size) { uint8_t i, page y / 8; const uint8_t *p (size 16) ? F8x16[ch - 0x20] : F6x8[ch - 0x20]; for (i 0; i size; i) { OLED_SetPos(page, x i); OLED_Write_Data(p[i]); } }看着简单但ASCII字体表生成时有两种完全不同的取模方向。一种是逐行取模字节的每一位横着排列一种是逐列取模字节的每一位竖着排列。如果显示出来的字符是“躺着的”或者扭曲的不用怀疑别的地方就是取模方向和你绘制代码不匹配。4.2 16x16汉字字模是怎么来的汉字和ASCII最大的区别在于字形复杂不搞矢量字库的话工程上最常用的就是点位阵字模。一个16x16的汉字按行扫描、每行16个点、2个字节一行一共16行总共32个字节。这32个字节里前16个字节对应汉字上半部分的8行后16个字节对应下半部分的8行。绘制时先写上方Page再把坐标切到下方Page继续写16列void OLED_ShowCHinese(uint8_t x, uint8_t y, const uint8_t *font) { uint8_t i; for (i 0; i 16; i) { OLED_SetPos(y / 8, x i); OLED_Write_Data(font[i]); } for (i 0; i 16; i) { OLED_SetPos(y / 8 1, x i); OLED_Write_Data(font[i 16]); } }这里有个前提y必须是8的整数倍也就是刚好落在Page边界上。实际显示菜单标题的时候大家也基本会把y设计成0、8、16这样的值所以这个限制在绝大多数项目里不影响使用。如果你非要让汉字显示在非8对齐的位置就得用位运算把相邻两个Page的数据拼起来复杂度上升不少除非是画游戏画面否则完全没必要。4.3 UTF-8转区位码的解析逻辑字模数据拿到后程序怎么知道你字符串里那个“中”字对应哪32个字节这里要看编译环境。Keil MDK里默认的中文字符串常量是GB2312/GBK编码一个汉字在字符串里占两个字节每个字节都大于0x80。你的字模如果按GB2312区位码顺序存放就能通过下面这种计算方式直接定位index (buf[i] - 0xA1) * 94 (buf[i 1] - 0xA1)。但如果你的工程用了UTF-8编码字符串里的汉字占三个字节就不能直接套用上面的区位码公式了。我自己的做法是先按UTF-8规则把三个字节还原成Unicode码点再通过码点表转换成GB2312区位。这个转换表比较笨重工程里如果只是显示固定菜单项更推荐用另一种方案——在源码里维护一张结构体数组typedef struct { char index[3]; // “中”的UTF-8编码或GBK编码 uint8_t font[32]; // 对应的16x16字模 } HZ_ITEM; const HZ_ITEM hz_table[] { {{0xD6, 0xD0}, { ... }}, // “中” {{0xCE, 0xC4}, { ... }}, // “文” };显示时把字符串里的两个字节逐个和表里的index比较匹配到就绘制对应字模。这种做法适合字库规模不大、只需要显示几十个常用汉字的场景简单粗暴也不用引入庞大的汉字编码转换库。4.4 字模放Flash还是外置存储最后说存储。32字节一个汉字看着不多但GB2312全量的6763个汉字加起来超过216KBSTM32内部Flash往往是512KB或1MB放全量字库理论上放得下但留给固件的空间会被压缩一般不建议这样干。更合理的做法是把最常用的几十个到几百个汉字做成子集放在内部Flash覆盖菜单、参数、报警信息这些固定文本如果产品需要任意汉字和水位都能显示再把全汉字字库放到外部SPI NOR Flash里按区位码偏移读取每次读32字节即可。上面热搜里提到的那些外挂Flash驱动芯片本质就是为了解决这个存储问题而不是OLED本身需要额外芯片。5. 踩过的坑与兼容性写法不同批次OLED屏一起点亮5.1 现象同一份固件两块屏一块正常一块发虚这是我在实际项目中遇到的第一个能逼疯人的问题。两块0.96寸OLED同一批货固件完全相同一块显示清晰另一块整体发虚、部分区域还有淡淡的残影。排查到最后问题出在0xDB寄存器。这块发虚的屏VCOMH值用0x40时驱动能力过强改成立即数0x30后画面立刻干净了。必须说明的是SSD1306老驱动里0xDB 0x40是行业默认写法网上大多数代码都这么写。但遇到SSD1315尤其是新批次这个值就成了“薛定谔的寄存器”。我现在的做法是初始化序列里不再硬编码这些参数而是在驱动头文件里给出一组可配置宏适配不同屏幕时只改宏不改逻辑#define OLED_MUX 0x3F // 128x64用0x3F, 128x32用0x1F #define OLED_VCOMH 0x30 // 发虚/重影时在0x40和0x30之间切换 #define OLED_COM_CFG 0x12 // 128x64用0x12, 128x32用0x02 #define OLED_SCAN_DIR 0xC8 // 上下颠倒时改0xC05.2 现象I2C地址对不上总线忙但屏幕全黑第二个高频问题是地址。之前提过模块丝印上的0x78和0x7A是8位地址对应7位地址0x3C和0x3D。问题在于有些模块SA0引脚被设计成可配置用跳线或电阻选择了高电平地址就会从0x78变成0x7A。你拿着默认0x78的驱动去点屏幕纹丝不动I2C通信又看似正常因为每次发送都收不到ACKHAL库反复重试后返回超时但裸眼的看逻辑分析仪又看不出明显错误。排查方法很简单上电后先调用HAL_I2C_IsDeviceReady(hi2c1, 0x78, 1, 100)如果返回HAL_ERROR再试0x7A。两个地址都试过还不行才需要考虑接线问题。我见过有人把SDA和SCL接反了同样一个地址反复调浪费了一整个下午。5.3 现象显示错位、只亮一半、上下颠倒这一类问题基本都能在初始化序列的0xA8、0xDA、0xC8、0xA1这几个寄存器上找到答案。0.91寸128x32屏用128x64的初始化序列最常见的症状就是只点亮上半屏因为屏幕物理上只有32行但MUX设置成了64行地址扫描越界。1.3寸屏如果出现显示内容整体偏移几列往往不是代码的坐标问题而是模块的SEG映射方向不同需要调整0xA0/0xA1的段重映射或者在0xD3显示偏移里做微调。这类问题最忌讳的是直接在绘制函数里加“偏移常量”去硬凑。我接过一个项目前任工程师因为屏显示偏了2个像素直接在所有坐标后面减2结果换一版屏幕之后整个UI又全部错位。正确的做法是把差异收敛到初始化序列的配置宏里让底层负责适配物理屏上层界面函数完全不用关心用的是哪家屏。5.4 现象能点亮但随机乱码、闪屏如果你已经能正常显示只是偶尔乱码、闪烁问题大概率不在初始化序列而在通信时序。先把I2C时钟从400kHz降到100kHz排除信号完整性问题再把模块的RESET引脚接一个GPIO上电后做一次至少1ms的低电平复位排除上电顺序问题。很多OLED模块上的RST引脚悬空也能工作但电源上电瞬间如果VCC爬升太慢屏内部状态机没准备好就会随机出现初始化后花屏或者显示错乱。另外提一个经验有些国产兼容SSD1306的芯片对I2C起始条件要求比较苛刻如果用软件模拟I2C切换SDA/SCL顺序时务必加延时用硬件I2C则注意总线空闲时间连续刷屏不要刷得太快否则在总线异常时HAL库可能卡在重试逻辑里。多花一点时间在通信稳健性上比事后追查随机乱码省心得多。5.5 兼容性写法的最终建议把上面的经验汇总成一句话就是OLED驱动代码的“上层”也就是画点、画字、画图逻辑在SSD1306和SSD1315之间是完全可以复用的真正的差异全部集中在初始化序列的少数寄存器上。与其写一堆#ifdef分支不如设计一份结构体配置把MUX、VCOMH、COM配置、扫描方向、列偏移这些差异抽出来做成一屏一配置。这样以后来了新屏照着屏幕的数据手册改一份配置实例就能点亮不需要动任何绘制代码。我自己现在的做法是维护一个OledCfg结构体每个屏对应一个静态实例初始化时把结构体里的值逐条映射成寄存器命令。新到的屏幕先点几个简单的显示项如果水平镜像、垂直翻转或者亮度异常按表调配置基本十分钟内都能搞定不用再对着数据手册翻寄存器翻到头晕。OLED驱动这件事说难不难说简单也不简单关键就是先把原理吃透再把变化点收敛在一个可控的位置剩下的无非就是多准备几块不同批次的屏幕多踩几次看起来一模一样的坑。本文还有配套的精品资源点击获取