简介这份压缩包整理了 OLED12864 显示屏在多种单片机平台下的程序例程面向广大嵌入式开发者和电子爱好者尤其适合需要快速在不同主控上驱动 OLED 的初学者。例程统一采用软件模拟 SPI 方式与屏幕通信不依赖硬件 SPI便于在没有对应外设的单片机上移植同时能帮助读者深入理解 SPI 的时序构成。包内包含 890 个文件以 C 源文件、头文件为主另含 hex、obj、编译配置等工程产物整体约 11.8 MBrar 压缩包内文件类型多样便于按需查阅。目前已有 757 人浏览学习。通过学习这套例程读者可以掌握 OLED12864 的初始化、绘图与文本显示流程理解软件模拟 SPI 的时序与引脚配置、宏定义修改方法并能针对不同单片机的引脚映射快速完成驱动代码移植直接用于课程设计或个人项目不同系列主控间只需调整管脚定义即可复用大部分代码。1. oled12864各种单片机的例程一套驱动模板解决点屏重复劳动oled12864各种单片机的例程说白了就是给128×64点阵OLED屏幕配套的一套驱动模板覆盖常见驱屏IC比如SSD1306这类的初始化、画点、清屏、显字和绘图流程。你不需要从数据手册的时序图开始啃把例程拷贝进自己的工程改几个引脚宏就能点亮屏幕。这套资源适合三类人刚拿到屏幕不知道怎么接线的初学者从51单片机换到其他内核想快速上手的老手以及做小项目需要半天内出样、不想在显示驱动上多花时间的开发者。OLED12864例程最大的价值不是某一两个函数而是把初始化顺序、通信时序、取模格式、坐标映射这些最容易出错的地方全部固化成了可移植的工程模板。我用过不少类似例程最能让你翻车的往往不是代码本身而是接口选错、取模方向不一致、初始化顺序被压缩这三个地方。2. 硬件连接与驱动原理I2C/SPI接口的时序差异OLED12864这个尺寸的屏幕市面上绝大多数模组把驱动芯片的接口选项通过模块背面电阻固定下来。引脚多的是并行/SPI复用版引脚少的是I2C版。例程包一般会把相同驱动函数按这两类接口各写一份工程你可以从引脚数量判断该看哪份例程。有人拿着SPI版屏幕去跑I2C例程焊了半天不亮最后发现是模块本身不支持I2C这种错属于接口选型问题代码写得再对也救不回来。2.1 两种主接口的选择依据与例程里的对应工程拿到例程包先别急着编译看手头屏幕的丝印和引脚。屏幕模组上引出的是GND、VCC、SCL、SDA四根线基本就是I2C版本如果多出CS、DC、RST那多半是SPI版本。有些模组同时标了两种接口位置但由背面电阻选择默认接法只能选一种。例程包里通常分两个目录I2C工程和SPI工程各一套千万不要只看一个目录就下手。接口类型物理引脚典型速率适合场景I2CVCC/GND/SCL/SDA有时加RST400kbps以内引脚紧张、只刷简单界面SPIVCC/GND/SCK/MOSI/CS/DC/RST最高可达10Mbps以上动画、频繁刷新、图形界面并行8080数根数据线加控制线速度快高端开发板低管脚单片机不实用从实用角度看I2C接线最少但刷全屏时速率瓶颈明显SPI更适合显示动态数据。两者的驱动IC内部寄存器是一致的差别只在传输层。例程里I2C版和SPI版的上层函数名往往一模一样改接口时真正要动的是底层发送函数和引脚初始化。2.2 模拟I2C写命令/写数据的代码拆解例程里的I2C实现有两种硬件I2C和模拟I2C。模拟I2C最常见因为它不依赖芯片内部外设随便找两个GPIO就能工作。核心是把时序用GPIO拉高拉低模拟出来#define OLED_I2C_ADDR 0x3C // 常见地址模块SA0接地时是0x3C static void i2c_start(void) { OLED_SDA_H(); OLED_SCL_H(); delay_us(5); OLED_SDA_L(); // SCL高电平时SDA拉低产生起始条件 delay_us(5); OLED_SCL_L(); } static void i2c_stop(void) { OLED_SDA_L(); OLED_SCL_H(); delay_us(5); OLED_SDA_H(); // SCL高电平时SDA拉高产生停止条件 delay_us(5); }注意起始和停止条件的顺序起始是“SCL高、SDA由高变低”停止是“SCL高、SDA由低变高”。很多人把顺序写反总线上其他设备也会被带乱。延时5us是保守值I2C标准模式下SCL频率100kbps这个延时足够如果MCU主频高可以缩短到2us但第一次调试建议保留余量。写完时序紧接着是写一个字节和组装命令帧static void oled_write_byte(uint8_t dat) { uint8_t i; for (i 0; i 8; i) { if (dat 0x80) // 从最高位开始发送 OLED_SDA_H(); else OLED_SDA_L(); dat 1; OLED_SCL_H(); delay_us(2); OLED_SCL_L(); delay_us(2); } } static void oled_write_cmd(uint8_t cmd) { i2c_start(); oled_write_byte(OLED_I2C_ADDR 1); // 7位地址左移最低位写0 oled_write_byte(0x00); // 控制字节0x00表示命令 oled_write_byte(cmd); i2c_stop(); }第一个字节是设备地址加写标志第二个字节叫控制字节它决定后面跟的是命令还是显示数据。OLED这类屏要求先发地址再发控制字节最后才是实际内容。如果把0x00误写成0x40后续字节全被当成显示数据写进显存屏幕上会出现一片乱码。例程里oled_write_data和oled_write_cmd的差别就在这个控制字节移植时不要合并成一个函数。2.3 硬件SPI的初始化配置与D/C、RST引脚处理SPI版本的例程一般优先用硬件SPI因为刷屏效率高。初始化时不同内核的寄存器名不一样但位含义是通用的void oled_spi_init(void) { /* 寄存器按你所用平台的实际定义调整这里只展示关键位 */ SPI_CR1 0; SPI_CR1 | (1 2); // MSTR1主机模式 SPI_CR1 | (1 6); // SPE1使能SPI /* CPOL和CPHA按模式0或模式3配置两者二选一 */ /* LSBFIRST必须为0保持MSB First */ }SPI模式0和模式3都能驱动这片屏但不能选模式1或模式2否则采样时序对不上。我一般先配成模式0即CPOL0、CPHA0调通后再尝试模式3。还有一个必须盯住的是字节序OLCD驱屏IC要求MSB First如果芯片默认LSB First显示的字会左右镜像看起来像取模取错了。SPI版多出两个引脚DC和RST。DC为高时写数据为低时写命令相当于I2C模式里控制字节的作用。RST建议用软件控制上电后先拉低至少10ms再拉高比单纯依赖上电自动复位稳妥。CS引脚低有效例程里通常初始化完直接拉低一直保持选中省得每次传数据都切换。3. 移植例程到实际项目配置项与屏幕初始化流程把例程从演示工程搬到自己的项目里不是把c文件拖进来编译就完事。你需要先理解它的代码分层再按清单改配置最后跑通初始化流程。这套动作熟练后五分钟能完成但对新手来说最容易漏掉的是GPIO时钟使能这类看起来不起眼的配置。3.1 例程目录结构的分层思路一套能跨平台用的OLED例程代码组织一定不是把所有逻辑堆在main.c里。我拆过不少类似工程效果比较好的是分成三层平台层、驱动层、应用层。project/ ├── platform/ # 平台层延时、GPIO、I2C/SPI初始化 │ ├── board.c │ └── board.h ├── driver/ # 驱动层OLED初始化、画点、清屏、显字 │ ├── oled.c │ └── oled.h └── app/ └── main.c # 应用层演示流程平台层负责跟单片机硬件打交道比如引脚宏、延时函数、外设时钟驱动层只调用平台层提供的接口应用层只调驱动层API。换单片机时理论上是重写platform目录driver和app原样保留。实际移植中如果例程的驱动层里直接写了寄存器操作那移植量会大不少这也是筛选例程质量的一个参考点。3.2 移植配置头文件时要动的几个参数例程通常会有一个配置文件集中管理可调项。我见过的典型写法是类似下面这样/* oled_config.h */ #define OLED_IF_I2C 1 // 1:I2C0:SPI #define OLED_I2C_ADDR 0x3C // I2C设备地址 #define OLED_SPI_MODE 0 // SPI模式0或3 #define OLED_INIT_DELAY_MS 100 // 上电后等待电源稳定 #define OLED_SCL_PIN P5 // 替换成实际引脚 #define OLED_SDA_PIN P4 #define OLED_RES_PIN P6 // 复位引脚SPI版才有 #define OLED_DC_PIN P7 // 数据/命令选择SPI版才有这里最需要注意的是OLED_IF_I2C这个开关。它决定了底层发送函数走I2C分支还是SPI分支改错的话编译能过但屏幕完全没反应。I2C地址0x3C和0x3D的差别在于SA0引脚电平模块上电阻默认多为0x3C如果地址不对I2C总线上根本收不到ACK。SPI模式下I2C地址参数不起作用但DC和RST引脚必须正确配置否则命令和数据混在一起。3.3 初始化上电时序与常规命令序列OLED的初始化命令序列比很多人想象得敏感。顺序不能乱延时不能省尤其是刚上电那几百毫秒。常规流程是步骤操作说明1延时100ms等电源稳定2RST拉低10ms再拉高硬件复位3写0xAE关闭显示4写0xD5,0x80设置显示时钟分频5写0xA8,0x3F设置驱动路数6写0xD3,0x00显示偏移7写0x8D,0x14使能电荷泵8写0x20,0x00内存寻址模式水平寻址9写0x81,0x7F设置对比度10写0xAF开启显示对应到代码一般是void oled_init(void) { OLED_RES_L(); delay_ms(10); OLED_RES_H(); delay_ms(50); oled_write_cmd(0xAE); // 关显示 oled_write_cmd(0xD5); // 显示时钟分频 oled_write_cmd(0x80); oled_write_cmd(0xA8); // 多路复用率 oled_write_cmd(0x3F); oled_write_cmd(0xD3); // 显示偏移 oled_write_cmd(0x00); oled_write_cmd(0x8D); // 电荷泵 oled_write_cmd(0x14); // 开启电荷泵 oled_write_cmd(0x20); // 寻址模式 oled_write_cmd(0x00); // 水平寻址 oled_write_cmd(0x81); // 对比度 oled_write_cmd(0x7F); oled_write_cmd(0xAF); // 开显示 oled_clear(); }这里最容易踩的坑是电荷泵那两条命令。0x8D后面的参数必须紧跟0x14不能写成0x10否则屏幕背光亮但内容完全不显示。对比度0x7F是常规值如果调得太低比如写成0x00屏幕看起来就像坏了一样。初始化最后加一次清屏很有必要因为屏内RAM上电时是随机值直接开显示会出现噪点。3.4 初始化后先跑哪个自检函数初始化完成不要马上刷业务UI先跑三个函数确认链路是通的oled_clear(); // 显存和屏幕都清空 oled_fill(0xFF); // 全屏点亮 delay_ms(300); oled_clear(); oled_show_string(0, 0, OLED OK); // 显示字符验证全屏点亮是判断初始化是否成功的最快方式。如果全屏能亮说明通信、复位、电荷泵都正常如果某一页不亮问题多半在寻址模式或坐标换算而不是硬件。跑字符显示时如果英文正常而中文乱码问题在字库取模不在驱动这一点先记下来后面会详细说。4. 常见问题排查花屏、白屏、残影与地址设置五大坑4.1 白屏上电顺序与对比度现象是背光能亮屏幕却一个字都不显示。先别怀疑屏坏了最常见原因是初始化序列里RST没拉高芯片一直停在复位状态其次是电荷泵没使能OLED驱动IC内部升压电路不工作像素无法点亮还有一种情况是对比度被写成0x00内容其实有只是肉眼看不见。处理方式按顺序排查用万用表量RST引脚电平确认上电后是稳定的高电平检查0x8D后面跟的是不是0x14检查0x81后面的对比度参数是不是在0x40到0x7F之间。很多例程初始化前有100ms延时这一步不要为了省时间删掉尤其用开关电源供电时上电波动会持续几十毫秒。4.2 花屏SPI模式与字节序现象是屏幕能亮但显示内容闪烁、错位或者字是镜像的。花屏的原因集中在三个地方SPI速率太高、CPOL/CPHA配置错误、LSB First被打开。SPI速率太高时用杜邦线连接模组会受到干扰画面闪烁但不规律字节序错了则固定表现为字符左右镜像。处理方式是把SPI分频调到最低比如1MHz排除速率问题后再逐步提速。确认CPOL和CPHA两项模式0或模式3都可以但不能混用。最后检查LSBFIRST位OLED必须MSB First。如果用了硬件SPI还花屏逻辑分析仪会显示MOSI上的数据位和寄存器配置不一致多半是初始化顺序有问题SPI外设使能前就把引脚复用改了。4.3 只显示半屏或下半屏错位页寻址与坐标换算现象是上半屏正常、下半屏不更新或者画面整体在垂直方向错位。OLED显存是按页组织的每页8行整个屏幕128列分成8页。画点函数里必须用“页y3、页内位y0x07”来计算位置而很多移植代码在这个地方想当然地直接用普通二维数组下标结果坐标一超过8行就乱。处理方式是用单点遍历自检从(0,0)逐点画到(127,63)看缺失或错位出现在第几行。如果恰好第0、8、16行出问题那就是mask(1(y%8))这一步写错了。另外寻址模式命令0x20后面跟的参数决定写显存时地址是水平增长还是垂直增长如果初始化和写屏函数用的不是同一种寻址模式也会出现半屏不更新的现象。4.4 残影与烧屏长时间固定画面现象是切换页面后旧内容还隐约停留在屏幕上过一会儿才消失。OLED是自发光器件长时间显示静态画面会让对应像素老化加速残影本质是像素亮度衰减不一致。对比度寄存器调得过高会让这个问题更早出现。处理方式是控制对比度在0x40到0x7F之间不要一味追求亮。需要长时间固定显示时可以在驱动层加一个定时反色逻辑每几十秒调用0xA6/0xA7命令切换显示极性或者做成整体滚动几个像素再滚回来让每个像素都有机会处于不同亮灭状态。关机前执行一次清屏避免下次上电直接显示上一次的残留内容。4.5 I2C总线无响应地址与电平现象是逻辑分析仪能看到主机发送波形但SDA上一直等不到ACK屏幕白屏。原因无外乎三类设备地址不对、总线没有上拉电阻、模块根本不支持I2C。地址0x3C和0x3D之间的选择由模块上SA0电阻决定例程默认0x3C如果模块设计成0x3D你在代码里改地址即可。I2C总线需要上拉电阻一般4.7kΩ某些模块板载了上拉某些没有。处理方式是把SDA和SCL各接一个4.7kΩ电阻到VCC再跑一次I2C扫描例程。如果模块是SPI版却接了I2C怎么扫描都无ACK这时只能换接口。电平问题也常见屏是3.3V供电单片机是5V IO直接连接会让IG芯片处于非正常工作范围建议加电平转换或确认屏的IO引脚是否兼容5V。5. 字体与坐标系统中文字库、滚动与取模技巧屏幕点亮只是开始真正让界面能看的是字体和坐标系统。OLED12864的驱动层通常自带ASCII字库和中文字库但很多花屏、镜像、乱码问题都出在取模格式和驱动层不一致。这一章把字库怎么选、坐标怎么算、滚动反色怎么做说明白。5.1 取模设置与字模在代码中的存放中文显示依赖字模数组。同一个汉字取模软件里设置不同生成的字节就完全不一样。正常情况下应使用逐行取模、每行8位、高位在前的格式生成的16×16汉字数组长这样const uint8_t hanzi_16x16[] { 0x00, 0x00, 0x00, 0x08, 0x1C, 0x18, 0x30, 0x70, 0x18, 0x18, 0x0C, 0x0C, 0x04, 0x00, 0x00, 0x00, /* 第二行数据按实际取模输出 */ };例程里oled_show_chinese函数会按这个数组的排列顺序绘制像素。如果更换取模工具或者手动调整过取模设置务必检查“逐行式”和“高位在前”这两项。常见的翻车现场是例程代码没动换了一批字模后中文全乱根源就是新字模是横向取模或低位在前。遇到这种情况不要急着改代码先把取模设置对齐再试。5.2 点阵绘制函数与坐标边界驱动层最核心的底层函数是画点。OLED12864的显存用二维数组缓存常见写法是8页×128列正好1KBstatic uint8_t oled_gram[8][128]; // 8页每页128列 void oled_set_pixel(uint8_t x, uint8_t y, uint8_t on) { uint8_t page, mask, col; if (x 127 || y 63) return; // 越界直接丢弃 page y 3; // 页号 y / 8 col x; mask 1 (y 0x07); // 页内位 y % 8 if (on) oled_gram[page][col] | mask; else oled_gram[page][col] ~mask; }这段函数里有三个关键点坐标越界必须返回否则数组越界会破坏内存页号计算用右移而不是除法因为编译器针对8位单片机可能生成低效代码页内掩码用与运算取低3位。如果例程里的缓存数组是[128][8]所有下标都要反过来写。判断方法是看oled_refresh函数里发送显存时是先遍历页还是先遍历列两者必须一致。5.3 中文字库的裁剪与存储策略中文字库占空间的问题在8位单片机上尤其明显。一个16×16汉字占32字节存300个汉字就接近10KB内部Flash往往不够。常见做法是只裁剪界面用到的汉字建立内码到字模的映射表typedef struct { uint16_t code; // 汉字内码 const uint8_t *bitmap; // 字模指针 } glyph_t; const glyph_t font_table[] { {0xD0C5, hanzi_16x16}, // “啊”的GB2312内码仅示意 /* 工程中由脚本自动生成 */ };例程里通常默认把所有字模塞进一个头文件。如果你要做一个十几个界面的菜单建议写个小脚本把需要的汉字从全字库里抽出来生成精简字体表。抽取逻辑不复杂扫描界面源码里的中文字符串去重后按内码排序再对应到字模数据。内存实在不够时把字模放外部Flash或SD卡按内码偏移读取代价是每次显示要额外读一次外部存储。5.4 滚动与反色的实现细节滚动和反色是OLED界面常用的两个效果。滚动命令的代码在驱动层一般这样封装void oled_scroll_h(uint8_t direction, uint8_t start_page, uint8_t end_page, uint8_t speed) { oled_write_cmd(0x26 | (direction 0x01)); // 0x26向右0x27向左 oled_write_cmd(0x00); // 虚列 oled_write_cmd(start_page); // 起始页0~7 oled_write_cmd(speed); // 速度0x00~0x07 oled_write_cmd(end_page); // 结束页0~7 oled_write_cmd(0x00); oled_write_cmd(0xFF); oled_write_cmd(0x2F); // 启动滚动 }speed参数的数值和滚动速度相关而且方向不同时对应关系会变。这里尤其要注意滚动只改变显示位置不改变显存内容所以执行停止滚动命令后画面会跳回原始位置。反色更简单驱动IC支持全局反色命令void oled_invert(uint8_t inv) { oled_write_cmd(inv ? 0xA7 : 0xA6); }这个命令不经过MCU改显存只是翻转显示极性非常适合做待机屏保。如果需要局部反色就得对显存里对应区域的字节做异或0xFF再刷新那一页。6. 进阶玩法菜单框架、进度条与双缓冲实现把例程的驱动层跑通后我通常先做一个表驱动的菜单框架再往上加功能。菜单用状态机结构体数组实现而不是一屏一屏地叠if-else。定义菜单项结构体把标题和处理函数放进数组里按键事件只改当前索引刷新函数根据当前索引调对应绘制方法。新增一个页面就是加一行数组记录维护成本很低也不会出现按键跳页面的低级错误。进度条这类组件不复杂关键是别让刷屏函数成为性能瓶颈。我的习惯是先在显存缓存里把填充列算好再按脏区块一次性刷新而不是每画一列就调一次SPI发送。双缓冲的做法是在RAM里维护一份oled_gram[8][128]业务代码只写这份缓存需要刷新时才把整帧或脏页推到屏幕。RAM足够时用整帧刷新RAM紧张就按页标记脏区这样既避免闪烁也能把刷屏耗时降下来。要验证这套流程我一般用逻辑分析仪抓SCL/MOSI确认时序再跑一遍坐标遍历自检和全屏填充。说实话例程本身已经省了很多事但真正接屏时配置头文件还是得自己从头过一遍。有一次我改了SDA引脚却忘了改SCL查了半天波形最后发现就是一行的错误。从那以后我每次接新屏都强制走一遍“查配置→测复位→刷全屏→跑字符→抓时序”这五步基本能避开绝大多数显示问题。希望帮到你。本文还有配套的精品资源点击获取