简介面向STM32嵌入式开发者的0.96寸OLED滚动显示示例工程聚焦SSD1306/SH1106控制器驱动与文字滚动刷新机制。资源包含完整Keil工程及源码可帮助开发者快速理解GPIO、I2C/SPI通信、字符点阵取模和视口移动原理直接移植到实际仪表或交互界面项目中。压缩包共90个文件以.c/.h源代码、.uvprojx工程文件、.axf/.hex/.map编译与调试产物为主另有少量备份与日志文件整体仅1.72MB便于下载与二次开发。已有1688人学习下载适合正在学习STM32显示驱动或需要滚动字幕功能的入门及中级开发者。通过学习该示例可掌握OLED初始化命令配置、显存管理、滚动速度与方向的调节方法并获得一套可直接运行的工程模板省去从零搭建环境的时间。1. OLED滚动显示不只是清屏重画先认识SSD1306的滚动引擎滚动显示“OLED屏滚动显示文字”这个需求很多人的第一反应是在主循环里不断改显示坐标然后整屏重画。实际做出来往往有两个问题一是文字在滚动时频繁闪烁二是CPU被一个又一个HAL_Delay占满按键扫描、串口处理全部跟着卡顿。SSD1306/SSD1315这类OLED控制芯片内部其实自带一个滚动引擎只需要往寄存器里写入滚动方向、起止页、滚动间隔再用一条0x2F命令启动屏幕上的内容就会自动连续滚动主控完全不需要参与逐帧刷新。这是“硬件滚动”对应的还有一套“软件滚动”通过操作帧缓冲实现按像素甚至按单个字符移动。下面从0.91寸128*32 OLED模块最常见的I2C接线开始先解决“怎么把屏幕点亮并显示出汉字”再分别走通硬件滚动和软件滚动两条路径最后把滚动速度调节、区间选择以及“加了OLED函数卡死”这类问题一并说清。这样无论你是解压了一个现成zip工程还是打算自己从HAL库驱动OLED代码开始重写都能直接照做。2. 点亮OLED的电路基础与HAL库/ESP-IDF的I2C驱动初始化2.1 0.91寸128*32 OLED在I2C总线上怎么和主机说话0.91寸和1.3寸模块多数使用SSD1306控制器少数使用SSD1315I2C接口默认从机地址是0x3C。部分模块背面有地址选择电阻焊接位置不同可能变成0x3D如果驱动程序里写死0x3C换一块模块后可能出现初始化失败、白屏或者乱码。建议在拿到模块后先扫描一次总线确认SDA上回ACK的地址再决定驱动代码里用哪个地址。I2C通信时每个字节前面都要附带一个控制字节0x00表示后续字节是命令0x40表示后续字节是显存数据。滚动功能依赖大量命令字节所以“命令通道”和“数据通道”是否区分清楚会直接影响滚动是否能正确执行。SSD1306内部显存按页组织12832分辨率一共4个page每个page代表屏幕上一个8像素高的横向条带12864则分成8个page。水平滚动命令操作的对象是这些page不是某一个文字因此先建立“分页”概念后续配置滚动区间才不会算错。2.2 用HAL库驱动OLED代码的最小初始化序列很多OLED工程点不亮不是I2C不通而是初始化命令里少开了charge pump或者复位引脚始终处于低电平。STM32 HAL库驱动OLED时通常把RES引脚配置成普通GPIO输出初始化前拉低10ms再拉高然后等待100ms让控制器内部状态复位完成。static void oled_write_cmd(uint8_t cmd) { uint8_t buf[2] { 0x00, cmd }; HAL_I2C_Master_Transmit(hi2c1, 0x3C 1, buf, 2, 100); } static void oled_write_data(uint8_t *data, uint16_t len) { static uint8_t buf[129]; buf[0] 0x40; memcpy(buf 1, data, len); HAL_I2C_Master_Transmit(hi2c1, 0x3C 1, buf, len 1, 100); } void oled_init(void) { HAL_GPIO_WritePin(OLED_RES_GPIO_Port, OLED_RES_Pin, GPIO_PIN_RESET); HAL_Delay(10); HAL_GPIO_WritePin(OLED_RES_GPIO_Port, OLED_RES_Pin, GPIO_PIN_SET); HAL_Delay(100); oled_write_cmd(0xAE); // 关闭显示 oled_write_cmd(0xD5); oled_write_cmd(0x80); // 内部时钟分频 oled_write_cmd(0xA8); oled_write_cmd(0x1F); // 128*32的32行输出 oled_write_cmd(0xD3); oled_write_cmd(0x00); // 显示偏移0 oled_write_cmd(0x40); // 起始行0 oled_write_cmd(0x8D); oled_write_cmd(0x14); // 开启内部电荷泵 oled_write_cmd(0x20); oled_write_cmd(0x02); // 页寻址模式 oled_write_cmd(0xA1); // 列方向重映射从左到右 oled_write_cmd(0xC8); // COM扫描方向重映射 oled_write_cmd(0xAF); // 打开显示 }0xA8后面的0x1F对应32行输出如果模块是常规128*64这里要改成0x3F否则显示区域只有上半屏底下的内容会跑到不可见区域。0x20 0x02将显示控制器设置为页寻址模式这个模式每次写完一列数据后列地址自动加1页地址保持不变方便按文字宽度写入。0xD5后面的0x80与滚动速度有关它决定内部DCLK的分频基准滚动间隔寄存器只能在一定范围里调速度如果发现最低速还是很快要先回头把这一项的分频降下去。2.3 汉字按页写入的缓冲方法在页寻址模式下写16*16汉字需要把点阵拆成上下两部分上8行写入当前page下8行写入相邻的下一个page。常见误区是每写一个字节就重新设置一次列地址导致I2C数据量增加很多屏幕刷新时出现横向撕裂。更稳妥的办法是先在RAM里把当前字符的两页数据拼好再一次性发出。void oled_show_string(uint8_t page, uint8_t col, const char *text) { while (*text) { const uint8_t *bitmap font16[*text]; uint8_t top[16], bottom[16]; for (int i 0; i 16; i) { top[i] bitmap[i * 2]; // 上半部分 bottom[i] bitmap[i * 2 1]; // 下半部分 } oled_set_cursor(page, col); oled_write_data(top, 16); oled_set_cursor(page 1, col); oled_write_data(bottom, 16); col 16; text; } }oled_set_cursor需要发送三条命令页地址0xB0 | page、列低地址0x00 | (col 0x0F)、列高地址0x10 | (col 4)。开始滚动之前先把文字写到对应的page里建议用这个函数把整行文字写入一个page区域而不是分散在多个page否则设置的滚动区间会覆盖到不想滚动的部分。2.4 ESP-IDF下点亮OLED的驱动写法差异在ESP-IDF环境里I2C初始化方式和STM32 HAL库差异较大但后续命令函数可以复用。0.91 OLED在esp32 idf下的驱动核心是先安装I2C driver再调用i2c_master_write_to_device发送数据。#include driver/i2c.h #define OLED_ADDR 0x3C void oled_i2c_init(void) { i2c_config_t conf { .mode I2C_MODE_MASTER, .sda_io_num 21, .scl_io_num 22, .sda_pullup_en GPIO_PULLUP_ENABLE, .scl_pullup_en GPIO_PULLUP_ENABLE, .master.clk_speed 400000, }; i2c_param_config(I2C_NUM_0, conf); i2c_driver_install(I2C_NUM_0, I2C_MODE_MASTER, 0, 0, 0); } void oled_write_cmd(uint8_t cmd) { uint8_t buf[2] { 0x00, cmd }; i2c_master_write_to_device(I2C_NUM_0, OLED_ADDR, buf, 2, portMAX_DELAY); }clk_speed在滚动字幕场景不建议一开始就设到800kHz杜邦线较长时400kHz更稳定。portMAX_DELAY会让任务阻塞直到发送完成如果在FreeRTOS的定时器任务里反复刷新全屏会导致其它低优先级任务长时间得不到调度。更好的做法是把屏显刷新放在主循环中或者使用非阻塞的I2C API配合事件队列。3. 滚动显示文字的两种实现硬件滚动命令与软件帧缓冲滚动3.1 SSD1306硬件滚动命令0x26、0x27与0x2F怎么配合硬件滚动的优势是启动后主控不再需要参与刷新。SSD1306有专门的水平滚动设置命令0x26和0x27分别对应向左和向右滚动开启连续滚动的命令是0x2F关闭滚动用0x2E。设置滚动区间时还需要指定起始页、结束页和滚动间隔。void oled_scroll_horizontal(uint8_t dir, uint8_t start_page, uint8_t end_page, uint8_t interval) { oled_write_cmd(0x2E); // 先关闭滚动避免在配置过程中产生意外滚动 if (dir 0) { oled_write_cmd(0x26); // 左滚 } else { oled_write_cmd(0x27); // 右滚 } oled_write_cmd(0x00); // 固定无符号字节 oled_write_cmd(start_page); // 起始page地址范围0~7 oled_write_cmd(interval 0x07); // 滚动间隔档位 oled_write_cmd(end_page); // 结束page地址 oled_write_cmd(0x00); // 垂直滚动扩展空位 oled_write_cmd(0xFF); // 固定字节 oled_write_cmd(0x2F); // 启动连续滚动 }参数说明start_page和end_page决定了哪些显存区域参与滚动。以128*32的4个page为例0~0代表只滚动最上面一页0~3代表整屏滚动。注意结束page地址必须大于等于起始page地址0x2F启动前一定要先设置好滚动区间否则寄存器里残留上一次配置可能滚到哪里都不清楚。interval的四个档位对应不同的帧间隔0x00最快0x07最慢实际显示的滚动速度还受0xD5时钟分频影响。垂直滚动稍微复杂一些需要先用0xA3设置垂直滚动区域再使用垂直加水平滚动命令0x29或0x2A。在本例中水平滚动已经满足大多数文字字幕需求真需要上下循环显示时再考虑垂直滚动。3.2 软件滚动实现按像素移动文字而不是按页移动硬件滚动的最小移动单位是8像素列因为显存中一个字节横向对应8个显示点。做室内广告屏或平滑移动的文字时这种跳动会显得生硬这时候就要用软件滚动。软件滚动的常见做法是维护一块RAM帧缓冲大小等于OLED显存容量。12832需要512字节12864需要1024字节。先把文字写进帧缓冲然后在主循环里按固定时间间隔整体左移一个像素最后把缓冲区一次性提交到OLED。#define OLED_W 128 #define OLED_H 32 #define OLED_PAGES (OLED_H / 8) static uint8_t framebuf[OLED_W * OLED_PAGES]; void oled_scroll_left_pixel(void) { for (int page 0; page OLED_PAGES; page) { uint8_t carry 0; for (int col 0; col OLED_W; col) { uint8_t data framebuf[page * OLED_W col]; framebuf[page * OLED_W col] (data 1) | (carry 7); carry data 0x01; } } oled_flush(); }逻辑说明这里把每一列字节的位向右移动一位同时把上一列移出的最低位补到当前列的最高位视觉上就是整行文字向左移动了一个像素。framebuf的布局是page0前128字节、page1接下来128字节提交时要按这个布局循环调用oled_write_data。这个方案比硬件滚动灵活得多但因为需要把整个缓冲区重新写到屏幕在400kHz I2C下大约需要十几毫秒如果刷新频率超过20帧主循环会被拖得比较重。3.3 两种方案的选择边界硬件滚动适合做整条横幅字幕占用资源最少代码也稳定软件滚动适合需要1像素平滑移动、或者只滚动某个自定义区域的场景。表格对比之后可以对应滚动文字项目的不同需求对比项硬件滚动软件滚动RAM占用无额外缓冲至少512字节CPU占用启动后不占用每帧都要参与移位移动粒度8像素列1像素滚动区域按page连续区间任意矩形范围与DMA冲突不影响需要处理传输完成事件如果是0.91寸128*32模块做滚动字数不多硬件滚动足够如果是做菜单中的多行桌面横向滚动我通常会选择软件滚动并配合DMA刷新因为硬件滚动无法精确控制“只滚动某一行中的一小段文字”。4. 滚动速度与常见故障排查卡死、白屏和Proteus模拟问题4.1 滚动速度调节间隔档位和DCLK分频要一起看硬件滚动速度不是只靠一个寄存器决定的。SSD1306的滚动间隔命令有0~7档但最终速度还要乘上内部扫描频率。0xD5命令设置的是DCLK分频和显示时钟分频分频越大屏幕扫描一帧的时间越长滚动间隔所代表的“帧数”也就越慢。在调试“滚动速度调不下来”的问题时先把0xD5的参数从0x80放到0xF0再把interval设到0x07一般就能看到明显的慢速效果。interval实际观感参考0x00极快几乎无法阅读0x02~0x04常见横幅字幕速度0x07慢速接近走马灯效果这个对照表在温度、晶振不同的板卡上会有差异但可以作为起点。4.2 “加了OLED函数卡死”的定位顺序这类问题最常见的原因不是OLED函数本身而是调用环境没有许可阻塞。如果HAL_I2C_Master_Transmit里的超时参数由100改成HAL_MAX_DELAY一旦I2C总线被拉低或从机不响应主机会永远停在那里等待。排查时按照下面的顺序来比盯着一行代码乱猜要快用示波器或逻辑分析仪检查SCL和SDA空闲电平必须都是高电平任意一根被拉低都会导致发卡检查OLED模块有没有和另一个I2C设备地址冲突尤其是地址同为0x3C的器件检查是否在中断回调函数里调用了写入函数I2C在主中断优先级较高时会卡住低优先级任务如果是软件滚动整屏512字节的写入不能在定时器中断里直接执行应该放到主循环或低优先级任务里卡死时用调试器暂停查看PC指针落在哪个函数。如果停在HAL_I2C_Master_Transmit内基本可以确认是ACK超时或总线错误。4.3 矩阵按键在OLED没有反应可能是刷新把CPU时间吃光了当滚动字幕用软件实现且刷新率过高时矩阵键盘扫描函数可能长时间得不到执行。按键检测每次按下需要10到20ms的消抖窗口如果OLED刷屏一次占用15ms两个周期之间只剩几毫秒给按键逻辑消抖窗口被反复打断最终表现就是“矩阵按键在OLED没有反应”。我一般的做法是把按键扫描放进100Hz的定时器中断只更新按键状态机不在中断里做扫描显示。主循环里根据按键状态去改变滚动内容或滚动方向。这样即使用软件滚动刷屏按键状态仍然会由中断稳定更新。Proteus仿真时如果模拟SPI接口的OLED白屏多数是D/C引脚接线和SPI模式选错。SSD1306 SPI要求把D/C接到GPIO控制字节不再是0x00/0x40而是直接用D/C电平区分命令与数据。仿真时还容易遇到把I2C模型选成调试器模型的情况这时滚动命令能看到但屏幕始终不刷改用虚拟I2C时序分析来验证更接近实际操作。4.4 滚动区域与页边界为什么显示了文字却不滚动没有先发送0x2E就直接设置滚动参数SSD1306内部状态机可能保留上一次滚动配置新参数没有生效起始页和结束页写反了例如结束页小于起始页控制器会忽略这个配置滚动区域覆盖了整个屏幕但文字写在page 0其它页都是空白滚动时看到的效果是白屏中跳出一个字看起来像闪烁而不是滚动OCRAM重复写同一页文字时需要持续更新显存否则只有内存里已有的内容在循环。正确做法是先把要滚动的文字固定写入某个page再把该page设为滚动区间启动0x2F。静态背景内容写到滚动区间之外的page这样背景不闪、文字一直动。5. 验证滚动效果的技巧把静态参考线和滚动前景分到不同Page验证硬件滚动是否正常最有效的办法不是盯着文字能不能动而是观察滚动过程中是否出现抖动、拖影或撕裂。给屏幕底部一个静态参考线顶部让文字滚动这样可以快速看出滚动引擎与显存写入是否存在冲突。先初始化并显示一个固定方框然后在page 0上写一行短文字开启0x2F观察顶部文字滚动时底部方框是否抖动。如果方框出现横纹说明你的软件刷新代码和硬件滚动在共享同一个page上的显存需要把静态参考线放在page 1到page 3而滚动区间只开放page 0。实际工程里还有一个常见需求滚动文字内容会更新比如每隔几秒换一条消息。硬件滚动开启后不能直接修改显存否则会出现文字半字残影。可行做法是每次更新前先停掉滚动重写文字再立即启动void oled_update_scroll_text(const char *new_text) { oled_write_cmd(0x2E); // 停止滚动 oled_fill_region(0, 0, 0); // 只清空page 0区域 oled_show_string(0, 0, new_text); // 写新的文字内容 oled_write_cmd(0x2F); // 续滚 }这里oled_fill_region只清空滚动区域所在page不清除底部静态内容避免每次更新时背景闪烁。oled_show_string写入后内存中的新文字会在下一次滚动周期开始时从page起始位置出现。这样在I2C速度不变的前提下更新单行横幅的时间可以控制在几次命令传输内主循环几乎不会感觉到卡顿。最后再检查一点滚动区间最多包含两页时阅读效果最稳定超过两页后人眼会不自觉追字速度要调得比日常阅读慢一档才不累。本文还有配套的精品资源点击获取