1. STM32CubeMX 点出来的 I2C,为什么第一屏经常是黑的
STM32CubeMX 这类代码开发工具最容易让人放松警惕:外设是勾出来的,初始化代码是自动生成的,看上去把底层细节都收走了。但真正决定一块 OLED 亮不亮的,恰恰是工具不会替你决定的那一层——I2C 帧里的从设备地址、控制字节和地址长度。我拿 STM32F103C8T6 最小系统板带一块 SSD1306 屏,从新建工程到第一行字出现在屏幕上,中间反复卡了三次,两次都跟 HAL_I2C_Mem_Write 的第二个参数有关。下面按我实际走通的顺序写:工具里怎么配、生成的代码怎么接、地址和参数为什么必须是那个值,以及屏黑着的时候先查哪四处。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的第一层配置:CubeMX 里 I2C1 该勾什么、填什么
配置这一步看起来最没技术含量,实际决定了后面所有调试的方向。外设时钟、速率、引脚、生成选项,任何一项和硬件对不上,生成出来的代码再正确也是空转。我一般会按“时钟 → 外设 → 引脚 → 生成”这个顺序走,不在中途反复回头改。
2.1 先定芯片和时钟,再碰外设
新建工程时在芯片选型框里直接输 STM32F103C8T6,选封装对得上的那条,不要用“就近选一个同系列”的方式凑合——引脚数和外设数量不一样,后面生成的初始化代码会对不上板子。
进去之后第一步不是找 I2C,而是 System Core 下面的 RCC。板子上有外部晶振,就把 HSE 设成 Crystal/Ceramic Resonator;最小系统板上那颗晶振常见是 8 MHz,按板子的实际器件填,不要凭印象。这一步的意义在于:CubeMX 算 I2C 分频系数时,用的是你在这里定下来的总线时钟,时钟页没配好就去填速率,生成出来的实际速率和你以为的数值根本不是一回事。
第二步才是 Clock Configuration 页。我一般会把 SYSCLK 拉到这颗芯片的常用上限,APB1 分频保持不变,让挂在 APB1 上的 I2C1 拿到一个稳定的输入时钟。这里不需要你手算分频值,工具会自动解,但你必须确认它解出来的结果没有红色警告——有警告说明这组时钟组合不可达,硬生成也能编译,跑起来外设就是时好时坏。
| 配置位置 | 我一般填什么 | 为什么 | 填错的后果 |
|---|---|---|---|
| RCC → HSE | Crystal/Ceramic Resonator | 板上有外部晶振 | 时钟源选成内部 RC,速率偏差累积到 I2C 上 |
| Clock Configuration | SYSCLK 拉到常用上限,APB1 分频不动 | 给 I2C1 一个确定输入 | 分频系数按错时钟算,实际波特率和设定值不符 |
| Pinout → I2C1 | I2C 模式 | SSD1306 是标准 I2C 从机 | 选成 SMBus 会带上不同的时序约束 |
这一步多花十分钟,后面能省掉一整轮“代码看起来没问题但屏就是不亮”的排查。
2.2 I2C1 的模式、速率与引脚落点
在 Pinout & Configuration 里展开 Connectivity → I2C1,I2C 那一栏选 I2C(不是 SMBus)。SSD1306 走的是最普通的 I2C 写事务,SMBus 的超时和校验规则对它没有意义,选错只会在边界情况下多出一堆莫名其妙的失败。
速率我一般先用标准模式跑通,能稳定出字之后再考虑往快速模式提。先低速的意义是排除变量:如果 100 kHz 下都点不亮,那问题一定在地址或帧格式,不在速率;反过来一上来就拉高速率,出问题时你没法判断是配错了还是时序余量不够。
引脚落点这块,F103C8T6 上 I2C1 的 SCL/SDA 默认就落在 PB6/PB7,CubeMX 使能外设时会自动把这两个脚标成绿色。如果你的板子把 OLED 接在别的脚上,那就不是“改个编号”的事——I2C 是复用功能,能不能换到别的脚要看芯片的复用表,硬改引脚编号生成出来的代码不会真的切换外设。
还有一件容易被跳过的事:确认模块板上有没有带上拉电阻。带模块的 OLED 一般已经把 SCL/SDA 的上拉做在板子上了,裸屏或者自己画的板子才需要外部补。上拉缺失的典型现象不是完全没反应,而是低速偶尔能通、高速必挂,很多人会误判成代码问题。
2.3 生成工程的选项,以及代码落在哪几个文件
Project Manager 页里,工具链按你手上的 IDE 选,Keil MDK 和 CubeIDE 都行,选完不要在生成之后又换,工程文件结构不一样。Code Generator 那一栏我一般勾上“生成对应的 .c/.h 对”,也就是每个外设单独出文件,而不是全部塞进 main.c。
生成出来一般是这个结构:Core/Src/i2c.c 里有 MX_I2C1_Init(),Core/Inc/i2c.h 里用 extern 声明了 I2C_HandleTypeDef hi2c1,main.c 的初始化段里调用一次 MX_I2C1_Init()。你后面所有 OLED 代码要用的,就是这个全局的 hi2c1 句柄。
这里有一条血泪经验:不要直接改 i2c.c。那个文件是工具生成物,下次改配置重新生成会整段覆盖,你加的代码会消失得无声无息。正确的做法是新建一对 oled.c / oled.h,在里面 include i2c.h,把读写函数和初始化序列都放进去;CubeMX 那边只在重新生成后确认 MX_I2C1_Init() 的参数没变。这样一来,配置归配置,业务归业务,重新生成多少次都不会互相踩。
OLED 自己的初始化命令序列(关显示、设时钟分频、设复用率、设起始行这些)属于屏的范畴,不是 I2C 外设的范畴,所以它们应该待在 oled.c 里,由一个 OLED_Init() 统一发出去,而不是散落在 main() 里。
3. 生成的 hi2c1 怎么接上 SSD1306:控制字节与两个封装函数
工程生成完,hi2c1 只是个配置好的句柄,它还不知道对面接的是什么设备。要让 SSD1306 认账,得按它规定的帧格式发字节,这一步没有任何工具能替你完成。
3.1 SSD1306 在 I2C 上的一帧由四段组成
SSD1306 的 I2C 写事务格式是固定的四段:起始信号 → 从设备地址(8 位写地址,0x3C 左移一位就是 0x78)→ 控制字节 → 数据字节。
第三段那个控制字节是整件事的关键,它告诉屏“我后面这一串字节是命令还是显存数据”:
| 控制字节 | 后面跟的字节含义 | 用在哪 |
|---|---|---|
| 0x00 | 命令 | 初始化序列、设置页地址、开关显示 |
| 0x40 | 显示数据 | 往 GDDRAM 里写像素 |
这个设计的好处是一条总线能同时承载命令流和数据流,坏处是控制字节一旦搞错,屏不会报错,它只会按你给的类型去理解后面的字节。把显存数据当命令发,屏会把像素值当成寄存器配置去解析;把命令当数据发,那些配置字节会直接写进显存,屏幕出现随机点亮的花屏。这两种现象看起来都像“驱动写错了”,实际只是控制字节填反。
地址这一段也要说清楚:0x3C 是 SSD1306 常用的 7 位从机地址,而 I2C 总线上实际传输的是 8 位形式,也就是把 7 位地址左移一位、最低位补上读写方向位。写操作时方向位是 0,所以 0x3C << 1 = 0x78。记住这个 0x78,后面 HAL_I2C_Mem_Write 的第二个参数就填它。
3.2 WriteCmd 与 WriteData:一次只搬一个字节
HAL 库操作 I2C 最常用的函数是 HAL_I2C_Mem_Write,它可以直接向从设备发送带“寄存器地址”的数据。SSD1306 没有真正的寄存器地址,那个位置放的就是控制字节,语义刚好能借用过来。封装两个基础函数,一个发命令,一个发数据:
c复制/* 发一条命令:控制字节 0x00 */
void OLED_WriteCmd(uint8_t cmd) {
HAL_I2C_Mem_Write(&hi2c1, 0x78, 0x00,
I2C_MEMADD_SIZE_8BIT, &cmd, 1, 100);
}
/* 发一个显示数据字节:控制字节 0x40 */
void OLED_WriteData(uint8_t data) {
HAL_I2C_Mem_Write(&hi2c1, 0x78, 0x40,
I2C_MEMADD_SIZE_8BIT, &data, 1, 100);
}
逻辑说明:两个函数的差别只有第三个参数——控制字节。hi2c1 是 CubeMX 生成的句柄;0x78 是 8 位写地址;0x00 / 0x40 决定这一帧的语义;I2C_MEMADD_SIZE_8BIT 告诉 HAL 控制字节占 8 位;&cmd 是要发的数据指针;1 是本次传输的字节数;100 是超时,单位毫秒。
参数说明:这两个函数刻意把长度固定成 1。固定成 1 的好处是排错时变量最少——帧里只有一个数据字节,出问题必定在地址、控制字节或地址长度上,不在长度上。等你确认单字节能通,再去写批量发送,故障面就小得多。
OLED_Init() 里就是一串 OLED_WriteCmd() 调用,顺序按屏的手册来;OLED_Clear() 则是对着 8 个页、每页 128 列逐字节调用 OLED_WriteData(0x00)。这套写法笨,但每一帧都短、都能单独复现,特别适合第一次点亮。
3.3 HAL_I2C_Mem_Write 的七个参数逐个对号
这个函数的签名是 HAL_I2C_Mem_Write(hi2c, DevAddress, MemAddress, MemAddSize, pData, Size, Timeout),七个参数,每一个都有明确的物理含义,没有一个可以“随便填”:
| 位置 | 参数 | 这里填什么 | 含义与填错的表现 |
|---|---|---|---|
| 1 | hi2c |
&hi2c1 |
CubeMX 生成的句柄,填错指向未初始化的句柄会直接进错误状态 |
| 2 | DevAddress |
0x78 |
8 位写地址,填 0x3C 会导致地址匹配失败、所有写入无效 |
| 3 | MemAddress |
0x00 或 0x40 |
SSD1306 语境下就是控制字节,填反则命令与数据互换 |
| 4 | MemAddSize |
I2C_MEMADD_SIZE_8BIT |
控制字节占 8 位;填 16 位会凭空多出一个字节,整帧错位 |
| 5 | pData |
&cmd / &data |
数据指针,传局部变量地址即可,函数返回前完成搬运 |
| 6 | Size |
1 |
本次事务里数据字节的个数,逐字节版固定为 1 |
| 7 | Timeout |
100 |
毫秒;总线异常时靠它把阻塞调用拉回来 |
第二和第四个参数是这套代码里最容易翻车的两处,下面单独展开。这里先记住一件事:DevAddress 要的是 8 位形式,不是 7 位地址值。我见过很多人在这个坑里卡很久,查遍所有寄存器配置都找不到问题,最后发现是地址没左移这一位。
4. 排查:地址、控制字节、地址长度、超时这四处最常翻车
屏黑着的时候最忌讳的做法是回头改初始化序列——那串命令你抄错的可能性,远小于地址和帧格式填错的可能性。我一般按下面四条的次序查,四条走完基本能定位。
4.1 现象一:调用正常返回,屏一动不动
现象:OLED_WriteCmd() 和 OLED_WriteData() 都能跑完,程序不卡死,屏上没有任何反应,连一条随机亮线都没有。
原因:DevAddress 传了 0x3C。HAL 库要求的是 8 位地址形式,它不会替你左移。0x3C 作为 8 位地址发出去,和从机自己的 7 位地址 0x3C 匹配不上,地址阶段就 NACK,后续数据一个字节都没进去。这个错误最坑的地方在于:它不改变你代码的逻辑结构,编译、下载、运行全都正常,只是总线上什么都没发生——如果你没检查返回值,这条线索就彻底丢了。
解决:把第二个参数改成 0x78,或者在 oled.h 里定义一个宏统一引用:
c复制/* 统一出口,避免每个调用点各写一遍地址 */
#define OLED_I2C_ADDR 0x78u /* 0x3C << 1,8 位写地址 */
#define OLED_CTRL_CMD 0x00u /* 后续字节是命令 */
#define OLED_CTRL_DATA 0x40u /* 后续字节是显存数据 */
改完之后先把 OLED_WriteCmd() 单独调一次、检查返回值,再往下继续。地址这一层不对,后面所有调试都是白费。
4.2 现象二:能点亮,但内容错位、命令行被当成像素
现象:屏上有反应,但显示内容乱,本来该是清屏的区域出现杂点,或者初始化之后屏的对比度、扫描方向明显不对。
原因:控制字节填反了。用 0x40 发命令时,SSD1306 会把你那条配置命令当成一个显存字节写进 GDDRAM;用 0x00 发显存数据时,像素值被当成命令解析,可能刚好命中某条“设置页地址”之类的指令,把写指针挪走。两种情况都不报错。
解决:把所有发命令的调用点收拢到 OLED_WriteCmd(),所有发像素的收拢到 OLED_WriteData(),中间不允许出现直接调 HAL_I2C_Mem_Write 的地方。这样控制字节只有一个来源,填反了改一处就够。这也是我坚持把封装做成两个函数、而不是一个带标志位的通用函数的原因——标志位传错的概率不比控制字节填反低。
4.3 现象三:换地址长度后整帧错位
现象:把 MemAddSize 改成 I2C_MEMADD_SIZE_16BIT 之后,屏的表现变成“第一条命令像是生效了,后面全乱”。
原因:16 位地址长度会让 HAL 在总线上多发一个字节作为“寄存器地址高字节”。SSD1306 那边收到的第一个数据字节其实是这个多余的高字节,它会被当成控制字节去解析,于是整帧的字节对齐全部往后挪了一位。对齐一乱,命令和数据的边界就没了。
解决:SSD1306 的控制字节就是 8 位,没有高字节,所以这里只能是 I2C_MEMADD_SIZE_8BIT。如果某个外设确实需要 16 位寄存器地址,那是那个外设的事,不要把习惯带过来。
4.4 现象四:刷屏刷到一半停住,局部花屏
现象:单条命令都正常,一旦开始整屏刷新,刷到中途卡住,或者屏幕上只有上半部分更新、下半部分还是旧内容。
原因:逐字节调用意味着每个像素字节都是一次完整事务——起始、地址、控制字节、一个数据字节、停止。一页 128 列、八页就是上千次事务,总线占用时间被拉得很长,Timeout 填 100 ms 在这种密度下很容易撞上 HAL_TIMEOUT 或 HAL_BUSY。如果你没检查返回值,看到的现象就是“刷到一半停了”。
解决:分两层处理。短期把 Timeout 放宽,先把功能跑通;长期是把同一控制字节下的连续字节合并成一次事务,也就是下一章那个 OLED_WriteBlock()。同时,所有调用点都要看返回值,别把 HAL_StatusTypeDef 丢掉——那是这套代码里唯一的黑匣子。
4.5 一套从外到内的排查顺序
把上面四条串成顺序,实际动手时按这个走,不要跳步:
- 先确认硬件:模块供电正常、SCL/SDA 没有接反、模块板上有没有上拉。这一步不用动代码。
- 抓第一帧:有逻辑分析仪就抓起始信号之后的第一个字节,看是不是
0x78。没有仪器就在代码里把DevAddress打出来核对。 - 查控制字节:确认命令走
0x00、数据走0x40,并且调用点没有绕过封装。 - 查返回值:把每次
HAL_I2C_Mem_Write的返回值收集起来,第一次出现非HAL_OK的位置就是故障点。 - 最后才怀疑初始化序列:只有前四步全部确认无误,才回头核对
OLED_Init()里的命令顺序。
这个顺序的道理是:越靠外的层越容易错,也越容易验证。先查地址和帧格式,能挡掉大部分问题;一上来就怀疑初始化序列,等于把最容易验证的部分放到最后。
5. 把逐字节写改成连续写:一次刷一页的封装与验证
单字节版本跑通之后,第一件该做的事不是加字体、加图形,而是把刷屏路径上的事务数量降下来。做法很简单:同一控制字节下,把整段字节塞进一次事务,Size 从 1 变成实际长度。
c复制/* 一次事务搬一整段:ctrl 传 0x00 发命令串,传 0x40 发显存数据 */
HAL_StatusTypeDef OLED_WriteBlock(uint8_t ctrl, const uint8_t *buf, uint16_t len) {
return HAL_I2C_Mem_Write(&hi2c1, OLED_I2C_ADDR, ctrl,
I2C_MEMADD_SIZE_8BIT,
(uint8_t *)buf, len, 100);
}
逻辑说明:和逐字节版相比,只有两处变化——第三个参数从固定的宏变成入参 ctrl,第六个参数从 1 变成 len。hi2c1、地址 0x78、地址长度 I2C_MEMADD_SIZE_8BIT、超时 100 全部不变。参数说明:ctrl 只允许传 OLED_CTRL_CMD 或 OLED_CTRL_DATA 两个宏,传别的值等于自己造了一个新帧格式;len 是一次事务里的字节数,刷一页时我一般按 128 传,正好覆盖 SSD1306 一页的列数。
改完之后有一件事必须做:验证。不是“看屏亮了就算过”,而是确认帧结构真的变了:
| 验证项 | 怎么验 | 期望结果 |
|---|---|---|
| 首字节地址 | 逻辑分析仪抓起始后第一个字节 | 0x78 |
| 控制字节 | 抓第三个字节 | 命令段为 0x00,数据段为 0x40 |
| 事务数量 | 统计一次整屏刷新的事务数 | 从上千次降到按页计的量级 |
| 返回值 | 每个调用点检查 HAL_StatusTypeDef |
全部 HAL_OK,无 HAL_TIMEOUT |
我自己的习惯是先只改清屏这一条路径,用 OLED_WriteBlock(OLED_CTRL_DATA, buf, 128) 一页一页地清,确认八页都清干净、返回值全对,再去改初始化命令串。命令串比显存数据短,出问题时不容易判断是长度还是内容的问题,放在后面改更稳。
从那以后我每次用这类代码开发工具生成 I2C 初始化,都会先做一件事:把 DevAddress 那一栏按 8 位形式填成 0x78,再看一眼控制字节是 0x00 还是 0x40。这两步加起来不到一分钟,但能挡掉我早期反复卡住的那三次。希望帮到你。
