简介基于STM32F103RCT6的CubeMX HAL库工程包完整实现0.96寸OLED屏的IIC驱动与内容显示主要面向STM32入门与嵌入式显示应用开发者解决硬件IIC通信、OLED初始化及字符图形显示等问题。工程使用单片机硬件IIC通过OLED_Write_Cmd与OLED_Write_Dat函数封装指令和数据写入接线方式清晰VCC接3.3V、GND接GND、SDA接PB7、SCL接PB6。资源包共996个文件以C源文件559个、头文件245个为主辅以STM32CubeMX工程配置ioc、uvprojx、链接脚本icf/sct、编译输出axf/hex与文档整体约22.69MB目录结构完整便于直接打开工程或按模块查阅学习。目前已有383人学习可从中获得完整源码、CubeMX配置思路、硬件IIC驱动框架以及OLED屏常见操作接口适合快速验证显示方案或在此基础上二次开发。1. 从一块不亮的屏说起IIC 驱动 OLED 到底难在哪0.96 寸 OLED 只有 4 根线看起来比 SPI 接口的屏简单得多但很多人恰恰在这块屏上翻车上电后屏幕毫无反应用万用表量 SDA 和 SCL 也有波形可屏幕就是黑着。问题多半不是代码而是把 IIC 的时序、地址、上拉电阻和初始化序列当成了“默认能跑”的东西。这个标题要解决的就是用 STM32F103RCT6 搭配 CubeMX 生成的 HAL 库工程通过硬件 IIC 把 0.96 寸 SSD1306 驱动起来并且能稳定显示字符、汉字和图片。适合正在做毕设、入门嵌入式或者想把手头模块快速点亮的人按这套流程走一小时以内就能看到画面。2. 先把硬件接对RCT6 引脚、0.96 寸 OLED 和上拉电阻2.1 STM32F103RCT6 与 0.96 寸 OLED 的接线对应关系STM32F103RCT6 是 LQFP64 封装比常见的 C8T6 多 16 个引脚Flash 256KB、SRAM 48KB驱动一块 128x64 的 OLED 绰绰有余。查 STM32F103RCT6 引脚图及功能表能看到 I2C1 的复用引脚有两组PB6/SCL 与 PB7/SDAPB8/SCL 与 PB9/SDA。I2C2 则挂在 PB10/PB11 上。我一般用 PB8/PB9 接 OLED因为这两个引脚在最小系统板上引出得比较规整而且和 SWD 调试口不冲突。OLED 引脚单片机引脚说明VCC3.3V模块供电注意别接 5VGNDGND共地必须接SDAPB9I2C1 数据线SCLPB8I2C1 时钟线有一个容易忽略的点CubeMX 里把 PB8/PB9 配置成 I2C1 后引脚会被锁定为复用功能代码里不需要再手动初始化 GPIO。如果用了软件模拟 IIC那才需要把引脚配成开漏输出。本项目标题明确写的是 HAL 库 IIC 驱动所以直接走硬件外设连线就按上表来。还有一点提醒OLED 模块上的丝印有时会把 SDA 和 SCL 标反接线前用万用表蜂鸣档对着模块背面的 SSD1306 引脚确认一下别盲目相信丝印。2.2 I2C 上拉电阻取多大内部上拉为什么不够IIC 总线是开漏结构SCL 和 SDA 必须靠上拉电阻拉高。STM32 内部虽然有上拉但典型值在 30kΩ 到 50kΩ 之间强度太弱。IIC 协议规定400kHz 快速模式下信号上升时间要小于 300ns内部上拉很难满足会导致波形边沿变缓通信不稳定甚至完全失败。常见做法是外接 4.7kΩ 上拉到 3.3V。如果 OLED 模块板载了上拉电阻多数 0.96 寸模块会焊 4.7kΩ 或 10kΩ那就不需要额外接。判断方法很简单用万用表电阻档量模块上 SDA 引脚对 VCC 的阻值有数值说明板载上拉存在显示无穷大就必须自己在 SDA 和 SCL 上各接一个 4.7kΩ 电阻到 3.3V。电阻取大了总线上升沿变缓通信速率上不去取小到 1kΩ 以下灌电流过大可能拉低 VCC。4.7kΩ 是兼顾功耗和速度的折中值。2.3 供电别踩3.3V 和 5V 的坑0.96 寸 OLED 模块的 SSD1306 芯片工作电压范围大约在 2.8V 到 3.6V 之间模块上通常会带一个稳压芯片常见的是 RT9167 或类似 LDO因此部分模块标称支持 5V 供电。但如果你手里的模块是裸屏或者没有稳压电路直接接 5V 大概率烧毁驱动芯片。安全起见统一接 3.3V和 STM32F103RCT6 的电源域保持一致这样 IIC 电平也是匹配的不用做电平转换。另一个供电教训是OLED 的驱动电流不算大全亮时也就 20mA 左右但不要把它和电机、舵机、继电器共用一个电源输出。电机启动瞬间的电压跌落会让 OLED 花屏或者重启。我在调试倒车雷达显示时遇到过屏幕频繁复位最后发现是超声波模块和 OLED 共用了一个 LDO把供电分开后问题消失。3. CubeMX 配置 I2C1时钟树、引脚复用和参数设置3.1 从安装到新建工程的三个关键选择CubeMX 安装本身不复杂但有两个坑一是安装时需要联网下载 STM32F1 系列固件包网络不好会卡在下载界面二是安装路径不要带中文和空格否则后面生成 MDK 工程时编译器可能报错。装好后新建工程在 MCU 选择器里输入 STM32F103RCT6注意不要选成 STM32F103RCT6Tx 以外的型号。Sys 里一定要使能 Serial Wire 调试否则下载一次程序后 SWD 口被禁用就只能用串口 ISP 救砖了。RCC 设置里把 HSE 选为 Crystal/Ceramic Resonator这样板载 8MHz 晶振会被启用。时钟树里把 HCLK 配到 72MHzAPB1 分频得到 36MHz——这个数字很重要I2C1 的时钟源就是 APB1它决定了 IIC 通信速率的计算基准。3.2 I2C 外设参数速率、占空比与上升时间在 Connectivity 里打开 I2C1Pinout 会自动把 PB8/PB9 分配为 I2C1 的 SCL/SDA。I2C1 的参数配置页有四个关键项参数推荐值说明I2C Speed ModeFast Mode选 Standard 就只有 100kHzI2C Clock Speed400000 Hz快速模式上限Rising Time300 ns默认即可Falling Time100 ns默认即可Fast Mode 下 CubeMX 会按 I2C 时钟占空比自动计算寄存器值。F103 的 I2C 外设在快速模式支持 16:9 和 2:1 两种 Tlow/Thigh 占空比CubeMX 会根据目标速率和 APB1 时钟自动选一个能满足的配置不需要手动调。但是要注意如果 APB1 不是 36MHz而是被配成了 18MHz那么 400kHz 可能无法精确达到实际输出会偏慢。此时可以把目标速率改成 350000通信依然稳定对 OLED 这种低速外设完全够用。也有人玄学地说“400kHz 就是会花屏降到 100kHz 就好”这多半是上拉电阻和时序的问题不是速率本身的问题先调硬件再降速。3.3 生成 MDK 工程HAL 库的代码结构Toolchain 选 MDK-ARM V5固件包选最新版即可。生成后会得到如下关键文件Core/Src/main.c存放 I2C 初始化代码Core/Src/i2c.cHAL I2C 底层初始化Core/Inc/main.h引脚定义和时钟参数main.c 里会自动生成 MX_I2C1_Init() 函数内容大致是static void MX_I2C1_Init(void) { hi2c1.Instance I2C1; hi2c1.Init.ClockSpeed 400000; /* 400kHz 快速模式 */ hi2c1.Init.DutyCycle I2C_DUTYCYCLE_2; /* 快速模式占空比 2:1 */ hi2c1.Init.OwnAddress 0; /* 主机模式自身地址无关紧要 */ hi2c1.Init.AddressingMode I2C_ADDRESSINGMODE_7BIT; hi2c1.Init.DualAddressMode I2C_DUALADDRESS_DISABLE; hi2c1.Init.GeneralCallMode I2C_GENERALCALL_DISABLE; hi2c1.Init.NoStretchMode I2C_NOSTRETCH_DISABLE; if (HAL_I2C_Init(hi2c1) ! HAL_OK) { Error_Handler(); } }这里 DutyCycle 是 I2C_DUTYCYCLE_2对应快速模式下 Tlow/Thigh 为 2:1。NoStretchMode 保持 DISABLE也就是允许从机拉低时钟进行展频SSD1306 在内部处理数据时需要这个机制。如果把它打开OLED 在连续刷屏时可能丢数据。生成工程后先编译一次确认零错误再往下写驱动。4. HAL 库驱动 OLED从写命令到显示汉字4.1 理解 SSD1306 的 IIC 时序控制字节与寄存器地址SSD1306 的 IIC 接口把“命令”和“数据”区分在一个控制字节里。一帧完整的 IIC 写操作是起始位、7 位设备地址加写位、ACK、控制字节、ACK、内容数据、ACK、停止位。控制字节 0x00 表示后续字节是命令0x40 表示后续是显存数据。HAL 库的 HAL_I2C_Mem_Write 函数恰好把控制字节当作内存地址来用uint8_t cmd 0xAF; /* SSD1306 开显示命令 */ HAL_I2C_Mem_Write(hi2c1, 0x78, 0x00, I2C_MEMADD_SIZE_8BIT, cmd, 1, 100);第一个参数是 I2C 句柄第二个参数 0x78 是设备地址第三个参数 0x00 是控制字节命令第五个参数是命令内容最后一个 100 是超时毫秒数。注意 DevAddress 传的是 8 位地址 0x78它由 7 位地址 0x3C 左移一位得到。如果 OLED 模块的 SA0 引脚被拉高地址会变成 0x3D对应 8 位地址 0x7A这也是常见的 IIC 扫描不到设备的元凶。写数据时把第三个参数改成 0x40 即可。4.2 初始化序列一个命令都不能少SSD1306 上电后必须按顺序写完初始化命令屏幕才能正常工作。命令序列直接从 SSD1306 数据手册拿来用我用的是经过验证的完整版void OLED_Init_Commands(void) { uint8_t cmds[] { 0xAE, /* 关闭显示进入设置阶段 */ 0xD5, 0x80, /* 显示时钟分频建议值 */ 0xA8, 0x3F, /* 多路复用比64 行 */ 0xD3, 0x00, /* 显示偏移 0 */ 0x40, /* 显示起始行 0 */ 0x8D, 0x14, /* 电荷泵开启必须 */ 0x20, 0x00, /* 水平寻址模式 */ 0xA1, /* 段重映射列地址 127-0 */ 0xC8, /* COM 扫描方向从上到下 */ 0xDA, 0x12, /* COM 引脚硬件配置 */ 0x81, 0xCF, /* 对比度 0xCF */ 0xD9, 0xF1, /* 预充电周期 */ 0xDB, 0x40, /* VCOMH 电平 */ 0xA4, /* 显存内容显示 */ 0xA6, /* 正常显示非反色 */ 0xAF /* 打开显示 */ }; HAL_I2C_Mem_Write(hi2c1, 0x78, 0x00, I2C_MEMADD_SIZE_8BIT, cmds, sizeof(cmds), 200); }这里最容易漏的是 0x8D 0x14 电荷泵开启命令如果漏掉屏幕就算初始化成功也不会亮。0xA8 0x3F 是 64 行模式0xDA 0x12 是 SSD1306 128x64 的 COM 引脚配置这两条错了屏幕会显示错位但不完全黑屏。0x81 后面跟的 0xCF 是对比度觉得亮度不够可以往上调但超过 0xFF 无效超过实际硬件范围也没意義。4.3 显存操作清屏、画点、字符与汉字SSD1306 内部有 128x64 位的显存按 8 行划分成 8 个 page每个 page 有 128 字节。想要显示内容本质是把数据写进这块显存。0.96 寸 OLED 的 IIC 接口一次可以连续写多个字节所以先准备好 1KB 的显存缓冲区再把缓冲区整体刷到屏幕效率最高。uint8_t OLED_Buffer[8][128]; /* 8 页 x 128 列 */ void OLED_Clear(void) { memset(OLED_Buffer, 0x00, sizeof(OLED_Buffer)); OLED_UpdateScreen(); } void OLED_UpdateScreen(void) { uint8_t i; for (i 0; i 8; i) { uint8_t cmd[] { 0xB0 i, 0x00, 0x10 }; /* 页地址 列低字节 列高字节 */ HAL_I2C_Mem_Write(hi2c1, 0x78, 0x00, I2C_MEMADD_SIZE_8BIT, cmd, 3, 50); HAL_I2C_Mem_Write(hi2c1, 0x78, 0x40, I2C_MEMADD_SIZE_8BIT, OLED_Buffer[i], 128, 200); } }0xB0i 是页地址命令0x00 和 0x10 分别把列地址低 4 位和高 4 位清零这样每次写页都是从第 0 列开始。显示字符时把 ASCII 字模按列取出写入缓冲区即可void OLED_ShowChar(uint8_t page, uint8_t col, char ch) { uint8_t i; uint8_t idx ch - 32; for (i 0; i 6; i) /* 6x8 字符宽度 6 字节 */ { OLED_Buffer[page][col i] Font6x8[idx][i]; } }汉字显示稍微复杂一点。16x16 汉字占用 32 字节在 8 页结构的显存里要拆成上下两半分别写到相邻的两个 page。取模软件 PCtoLCD2002 里设置“逐列式、阳码、十六进制输出”取出来的数据直接按列刷进去就行。STM32F103RCT6 的 48KB SRAM 放几个字模数组毫无压力不用为了省 RAM 做各种压缩。4.4 HAL 库 IIC 的返璞归真超时与错误状态机HAL 库的 I2C 封装了一个状态机每次调用 HAL_I2C_Mem_Write 之后调用方应该检查返回值。返回值有四种HAL_OK、HAL_ERROR、HAL_BUSY、HAL_TIMEOUT。我维护的 OLED 驱动里会把返回值包装一层uint8_t OLED_WriteCmd(uint8_t cmd) { HAL_StatusTypeDef status; status HAL_I2C_Mem_Write(hi2c1, 0x78, 0x00, I2C_MEMADD_SIZE_8BIT, cmd, 1, 100); if (status ! HAL_OK) { /* 打印错误码方便定位 */ printf(I2C err: %d\r\n, status); return 1; } return 0; }很多人遇到 IIC 通信失败第一反应是换线、换屏但 HAL 库的返回值已经告诉你了HAL_BUSY 是总线被占用多半是上一笔通信没结束或者总线被从机拉死HAL_TIMEOUT 是超时没收到 ACK多半是地址错或者上拉电阻缺失。把错误码通过串口打印出来比盲猜高效得多。如果不想用串口可以在 HAL_I2C_ErrorCallback 里放一个断点跑飞时直接停在回调里看调试器寄存器窗口也能定位。5. OLED 不亮与花屏4 个高频踩坑记录5.1 屏完全不亮扫描地址找不到设备现象上电后屏幕没有任何反应连背光都不亮IIC 扫描函数返回不到 0x3C 这个地址。原因这类问题排在第一位的是接线错误其次是设备地址不对再往后是上拉电阻缺失。0.96 寸 OLED 的丝印 SDA 和 SCL 标反的情况并不少见VCC 和 GND 接反会直接烧模块所以第一步不是改代码而是断电后用万用表核对每条线。第二步确认 SA0 引脚的状态SA0 悬空或接地时地址是 0x3C接 VCC 时是 0x3D对应 HAL 库里的 DevAddress 分别要传 0x78 和 0x7A。解决写一个最简单的 IIC 地址扫描函数依次向 0x30 到 0x50 范围内的每个地址发送一个字节看哪个地址能收到 ACK。能扫到就说明硬件链路通问题在软件扫不到就回到硬件检查。我遇到过一块模块的 SA0 引脚出厂就焊在 VCC 上按 0x78 怎么都调不通改成 0x7A 立刻亮。5.2 上电花屏或者显示乱码现象屏幕能亮但显示的内容缺行、错位或者初始化瞬间出现随机条纹刷新几次后才正常。原因初始化命令顺序不对或漏了关键命令比如 0x20 寻址模式没设置导致后续数据写入时列地址自增方向错乱。另一个常见原因是电源纹波OLED 和 STM32 共用电源时如果板上有 DC-DC 或者大电流负载电压跌落会让 SSD1306 内部状态机重置。解决核对初始化命令序列确认 0x20 0x00 水平寻址模式、0xA1 段重映射、0xC8 扫描方向这三条和你的接线方向匹配。如果屏幕镜像了把 0xA1 改成 0xA0、0xC8 改成 0xC0 即可。供电问题上用万用表测 OLED 的 VCC 在刷新时的电压波动低于 3.0V 就换独立供电或者在 VCC 和 GND 之间并一颗 10uF 钽电容。5.3 跑一段时间后 I2C 卡死复位后才能恢复现象系统运行十几秒或几十秒后屏幕不再刷新程序卡在 HAL_I2C_Mem_Write 里单步调试发现返回值一直是 HAL_BUSY。原因STM32F103 的硬件 I2C 有一个著名的坑——总线忙标志位可能被卡住。总线上出现异常停止条件、从机响应超时或者主机在错误的时机检测到 BUSY都可能让外设进入不可恢复状态。HAL 库的 I2C 状态机在遇到这类情况时如果没做错误恢复就会一直停在忙状态。解决在每次写操作失败后做一次外设复位void OLED_I2C_Recover(void) { HAL_I2C_DeInit(hi2c1); HAL_I2C_Init(hi2c1); }HAL_I2C_DeInit 会把 I2C 外设寄存器恢复到复位值再调用 Init 重新配置。实测中这个操作能让卡死的外设恢复通信代价是大约 1ms 的时间。另一个更彻底的方案是 GPIO 翻转法把 SCL 和 SDA 配置成普通开漏输出手动翻转 9 次 SCL让挂在总线上的从机复位状态机。这个操作在 Linux 内核的 i2c-gpio 驱动里也有类似实现本质上是在总线层面清掉异常状态。注意 Recover 函数里要加足够长的延时让总线上所有的从机都能检测到停止条件我一般加 5ms。5.4 显示亮度低、有残影或对比度不足现象屏幕能显示但整体发暗白字不够白黑底不够黑切换画面时上一帧的内容还隐隐可见。原因驱动芯片的电荷泵没有打开到足够电压或者对比度寄存器值设得太低。还有一种情况是清屏时只清了缓冲区没有把全部显存刷成 0SSD1306 内部显存残留了旧数据。解决初始化命令里确认 0x8D 0x14 已经执行0x81 后面的对比度值设在 0x80 到 0xFF 之间低于 0x80 会明显变暗。清屏要保证 OLED_Clear 后调用 OLED_UpdateScreen把 8 页共 1024 字节全部写 0。如果仍然有残影在初始化末尾加一条 0xA4 命令恢复显存内容显示它能把硬件内部标志位复位。6. 进阶验证用逻辑分析仪抓 IIC 时序再做一屏动画当屏幕能显示字符后下一步不是急着写 UI而是用逻辑分析仪确认 IIC 通信质量。把 CH0 接 SCLCH1 接 SDA触发方式设为下降沿采样率 5MHz 以上抓一帧 HAL_I2C_Mem_Write 的波形。重点看三件事起始位后设备地址是否带写位0x78 末尾是 0、每个字节后有没有 ACK 低电平、停止位是否完整。如果 ACK 缺失波形上会显示 NACK这时查上拉电阻和地址如果时钟频率明显低于 400kHz在 CubeMX 里核对 APB1 是不是 36MHz。时序确认无误后可以做一屏滚动动画验证驱动的稳定性。SSD1306 支持硬件垂直滚动不需要 MCU 参与刷屏uint8_t scroll_cmd[] { 0x26, /* 垂直右滚动 */ 0x00, /* 起始页 0 */ 0x00, /* 滚动间隔 5 帧 */ 0x07, /* 结束页 7 */ 0x00, /* 滚动偏移 0 */ 0xFF, /* 每帧垂直滚动 1 行 */ 0x2E /* 激活滚动 */ }; HAL_I2C_Mem_Write(hi2c1, 0x78, 0x00, I2C_MEMADD_SIZE_8BIT, scroll_cmd, 7, 100);滚动命令设置完成后SSD1306 自动在内部搬移显存MCU 可以完全释放去处理其他逻辑。这个功能适合做菜单提示、报警信息滚动展示。0xFF 参数表示一次滚动一页实际滚动速度非常慢改成 0x01 会快得多。如果滚动后想停止发送 0x2E 的相反命令 0x2F 即可。再有一个实战中常用的技巧用 DMA 刷新显存。HAL_I2C_Mem_Write 是阻塞式的一次刷新 8 页要阻塞好几毫秒。改为 HAL_I2C_Mem_Write_DMA 后配合一个刷新完成信号量可以在屏幕刷新的同时让主循环继续处理按键和传感器数据。F103RCT6 的 DMA1 通道 7 可以挂 I2C1_TX在 CubeMX 里把 I2C1 的 DMA 请求勾上代码里把 UpdateScreen 函数替换为 DMA 版本注意每次 DMA 传输前要等上一次传输完成否则会覆盖缓冲区。这个方案我从显示数字温度开始一路做到图形化菜单和动态波形。最后说一句习惯每次新屏点亮我做的第一件事永远是固定接线、固定地址、固定初始化序列然后把它们写进一个注释文件里。这块 0.96 寸屏的驱动代码几乎在所有项目里都能复用前端显示逻辑怎么改都不影响底层稳定希望这套流程能帮你在 IIC OLED 上少走几趟弯路。本文还有配套的精品资源点击获取