1. 用 STM32 的 HAL 库这套代码开发工具重写 OLED 通信:先搞清楚省掉的是什么
STM32 的 HAL 库,这套代码开发工具最容易被低估的地方不是函数多,而是它把时序问题收进了几个参数里。把一块 0.96 寸 OLED 从软件模拟 I2C 换到硬件 I2C,代码量能从两百多行降到几十行,但屏幕也可能先黑上两天——地址填错、控制字节用反、超时给得太小,任意一个都能让 HAL_I2C_Master_Transmit 返回成功而屏上什么都没有。这次就把 I2C 与 SPI 两套最小实现摊开,讲清楚 CubeMX 里怎么配、写命令与写数据怎么分工、0x78 和 0x3C 到底用哪个,以及全黑、花屏、总线卡死分别往哪查。适合已经把屏点亮、想换成硬件外设或改 SPI 接线的人,也适合刚接手一块带 OLED 的板子、不想再从 GPIO 翻转开始啃的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链准备:CubeMX 里 I2C、SPI 与三个 GPIO 怎么配
这套工具链其实由三部分组成:CubeMX 负责把时钟、外设和引脚生成成初始化代码,HAL 库负责在运行期收发字节,逻辑分析仪负责在你怀疑人生的时候告诉你线上到底跑了什么。三者缺一个,调试就会退化成猜。下面按 I2C 路线和 SPI 路线分别把配置说清楚,配置错了后面代码写得再漂亮也没用。
2.1 为什么把软件模拟 I2C 换成硬件外设
软件模拟 I2C 的写法是拿两根 GPIO 手动拉高拉低,SCL 的周期靠 delay 或空循环撑着。主频一改、优化等级一变,时序就漂;中断一多,从机就可能认错位。硬件 I2C 把起始、停止、应答、时钟全交给外设,CPU 只在数据寄存器和中断上花时间。HAL 库把这套外设包成 HAL_I2C_Master_Transmit 一类函数,调用方只需要关心地址、缓冲区、长度、超时四个东西。
选它不是为了代码短,而是为了让时序不再依赖编译器和主频。代价是参数必须一次性给对:地址是 8 位还是 7 位、控制字节算不算在长度里、超时单位是毫秒还是滴答,这些在软件模拟版里由你亲手写死,在 HAL 里变成了函数入参,填错就静默失败。这也是后面几章反复围绕参数展开的原因。
2.2 I2C1 的参数:速率、7 位地址与时钟拉伸
在 CubeMX 的 Connectivity 里选 I2C1,模式选 I2C。Speed Mode 我一般放在 Fast Mode 这一档(常见 400kHz),前提是模块和走线撑得住;排线长、上拉电阻弱,就退回 Standard Mode,先点亮再提速。7 位地址模式保持默认,Dual Address 关掉,Clock No Stretch 按默认允许,不要为了“看起来干净”去关时钟拉伸,有些从机会在应答前拉低 SCL,关掉之后总线直接卡住。
生成代码后外设句柄叫 hi2c1,后面的收发都用它。CubeMX 会把 GPIO 的复用模式、开漏、上拉一并配好,不需要你再手动写 GPIO_Init。有一点要确认:I2C 引脚必须是开漏加外部上拉,很多模块板上自带上拉,杜邦线一长就得并一只小阻值电阻,否则波形上升沿爬不上去,示波器上看就是方波变成三角波。
2.3 SPI1 的参数:模式 0、8 位与软件 NSS
SPI1 选 Full-Duplex Master,数据宽度 8 位,CPOL Low、CPHA 1Edge,也就是常说的模式 0,SSD1306 这类屏一般吃这一档。如果画面整体错位半列、或者每个字节都像被移了一位,先怀疑 CPHA 选错,而不是先改驱动。NSS 选 Software,片选用普通 GPIO 手动拉,比硬件 NSS 好控,因为 OLED 的一条命令往往要连续发多个字节,硬件 NSS 会在每个字节后自动翻转,时序反而不好对齐。
预分频先给一个不高的速率,等点亮、画面稳定之后再往上提。SPI 比 I2C 快得多,但排线质量差的时候高速率会先表现为偶发花屏,而不是直接不亮,这种偶发问题最难查,所以第一次配置宁可慢一点。生成后句柄叫 hspi1,收发用 HAL_SPI_Transmit。
2.4 DC、CS、RES 三个 GPIO 与生成的工程骨架
DC、CS、RES 三个脚都配成 GPIO_Output,推挽、无上下拉、速度中低即可。上电初始电平:CS 拉高(不选中),DC 随意,RES 先低后高走一次复位。引脚宏在头文件里定好,例如 OLED_DC_PORT、OLED_DC_PIN、OLED_CS_PORT、OLED_CS_PIN,后面代码只认宏名,换板子只改这一处,不要在函数里直接写 GPIOA 和 GPIO_PIN_5。
生成工程时把“Generate peripheral initialization as a pair of .c/.h files”勾上,hi2c1、hspi1 的声明会落在对应的头文件里,主程序 #include "i2c.h"、#include "spi.h" 就能用。OLED 自己的驱动建议单独放 oled.c / oled.h,只暴露 OLED_Init、OLED_WriteCmd、OLED_WriteData 三个入口,底层走 I2C 还是 SPI 用宏切换。这样同一份上层显存代码可以复用到两种接法,不用维护两套。
3. 写命令与写数据:I2C 与 SPI 两套最小实现的逐段拆解
OLED 的通信模型只有两件事:写命令和写数据。命令用来配置对比度、页地址、开关显示;数据用来填显存。区别在于 I2C 用控制字节区分这两类,SPI 用 DC 引脚的电平区分。下面三段代码分别对应软件 I2C、硬件 I2C 和硬件 SPI,逐段看每个参数落在哪。
3.1 软件 I2C 版:每个字节都起停一次
c复制// 软件模拟 I2C,地址按模块实际修改
#define OLED_ADDR 0x78
void OLED_WriteCmd(uint8_t cmd)
{
I2C_Start();
I2C_SendByte(OLED_ADDR); // 从机地址
I2C_SendByte(0x00); // 控制字节:命令
I2C_SendByte(cmd);
I2C_Stop();
}
void OLED_WriteData(uint8_t data)
{
I2C_Start();
I2C_SendByte(OLED_ADDR);
I2C_SendByte(0x40); // 控制字节:数据
I2C_SendByte(data);
I2C_Stop();
}
这段代码的逻辑很直白:每次起始、发地址、发控制字节、发一个字节、停止。I2C_Start 和 I2C_Stop 是软件模拟层自己实现的,I2C_SendByte 里包含了一位一位的时序和应答检查。控制字节 0x00 表示“后面跟的是命令”,0x40 表示“后面跟的是数据”,这是 SSD1306 在 I2C 模式下的约定,不是 HAL 规定的。
问题在于效率:写一屏 1024 字节显存,就要起停 1024 次,每次还要等应答。初始化阶段命令少无所谓,整屏刷新时总线大半时间花在起始和停止上。这也是换硬件 I2C 的直接动机——不是为了少写代码,而是为了把多个字节拼成一次传输。
3.2 硬件 I2C 版:把控制字节和数据拼进一个缓冲区
c复制// 硬件 I2C 版本,用 HAL 库收发
void OLED_WriteBytes(uint8_t ctrl, uint8_t *buf, uint16_t len)
{
uint8_t tmp[128];
tmp[0] = ctrl;
for (uint16_t i = 0; i < len; i++) {
tmp[i + 1] = buf[i];
}
HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR, tmp, len + 1, 100);
}
逻辑说明:硬件 I2C 把控制字节和后续数据拼成一个缓冲区一次发出,减少起始停止次数,效率更高。ctrl 传 0x00 就是发命令,传 0x40 就是发数据;buf 是上层要发的字节数组,len 是数据字节数;len + 1 是因为缓冲区第 0 位被控制字节占了,真正发给总线的长度要多一个。
参数上,100 是超时毫秒数,总线异常时不会永久卡死。OLED_ADDR 是 8 位写地址,这里填 0x78,不是 7 位的 0x3C,原因在第 4 章展开。tmp 的大小要够,整屏刷新时一次最多 128 字节数据加 1 字节控制,所以 129 才够用;上面写成 128 是有隐患的,后文会讲怎么改。分页刷新时按页发更稳,每页 128 字节数据正好一次发完。
写命令可以复用同一个函数:
c复制void OLED_WriteCmd(uint8_t cmd)
{
OLED_WriteBytes(0x00, &cmd, 1);
}
void OLED_WriteData(uint8_t data)
{
OLED_WriteBytes(0x40, &data, 1);
}
这样上层只需要记住“命令用 0x00、数据用 0x40”,不用关心底层是软件还是硬件。切换接法时只改 OLED_WriteBytes 的实现,显存刷新逻辑一行不动。
3.3 SPI 版:DC 引脚决定这一字节是命令还是数据
c复制// SPI 写命令与写数据,DC 引脚区分
void OLED_WriteCmd(uint8_t cmd)
{
HAL_GPIO_WritePin(OLED_DC_PORT, OLED_DC_PIN, GPIO_PIN_RESET); // DC 低:命令
HAL_GPIO_WritePin(OLED_CS_PORT, OLED_CS_PIN, GPIO_PIN_RESET);
HAL_SPI_Transmit(&hspi1, &cmd, 1, 100);
HAL_GPIO_WritePin(OLED_CS_PORT, OLED_CS_PIN, GPIO_PIN_SET);
}
void OLED_WriteData(uint8_t data)
{
HAL_GPIO_WritePin(OLED_DC_PORT, OLED_DC_PIN, GPIO_PIN_SET); // DC 高:数据
HAL_GPIO_WritePin(OLED_CS_PORT, OLED_CS_PIN, GPIO_PIN_RESET);
HAL_SPI_Transmit(&hspi1, &data, 1, 100);
HAL_GPIO_WritePin(OLED_CS_PORT, OLED_CS_PIN, GPIO_PIN_SET);
}
SPI 版没有控制字节,命令和数据靠 DC 电平区分:DC 低表示这一字节是命令,DC 高表示是数据。CS 在每次传输前拉低、传输后拉高,保证从机只在片选有效时采样。HAL_SPI_Transmit 的第三个参数是数据长度,这里一个字节就写 1;第四个参数 100 同样是超时毫秒。
这段代码可以合并成一个带 DC 参数的内部函数,减少重复:
c复制static void OLED_SPI_Write(uint8_t dc, uint8_t data)
{
HAL_GPIO_WritePin(OLED_DC_PORT, OLED_DC_PIN, dc ? GPIO_PIN_SET : GPIO_PIN_RESET);
HAL_GPIO_WritePin(OLED_CS_PORT, OLED_CS_PIN, GPIO_PIN_RESET);
HAL_SPI_Transmit(&hspi1, &data, 1, 100);
HAL_GPIO_WritePin(OLED_CS_PORT, OLED_CS_PIN, GPIO_PIN_SET);
}
合并之后命令和数据只是 dc 传 0 还是 1 的区别,接线上 DC 接错时也更容易在同一个函数里改。SPI 的整屏刷新同样可以把一页 128 字节拼进缓冲区一次发,不必一个字节一次片选,HAL_SPI_Transmit 的长度参数直接给 128 即可,但要注意这时 DC 必须保持高电平整段不变。
4. 参数对齐:0x78、0x00/0x40 与 100ms 超时到底怎么填
同一块屏,软件模拟 I2C 能亮,换到 HAL 硬件 I2C 就不亮,九成是参数没对齐。这一章把四个最容易填错的参数单独拎出来:从机地址、控制字节、超时、缓冲区长度。每个都给出判断依据,而不是让你死记。
4.1 0x78 还是 0x3C:HAL 要的是 8 位地址
| 用途 | 值 | 说明 |
|---|---|---|
| 7 位地址 | 0x3C | 模块手册常写这个 |
| 8 位写地址 | 0x78 | 0x3C 左移一位 |
| 8 位读地址 | 0x79 | 0x3C 左移一位再加 1 |
HAL_I2C_Master_Transmit 的第二个参数是 8 位地址,直接传 0x78。如果照着手册把 0x3C 填进去,HAL 不会再帮你左移,总线上出现的地址就是 0x3C,从机不应答,函数返回 HAL_ERROR 或超时。反过来,如果你在软件模拟版里一直用 0x78,换到某些要求 7 位地址的库函数时又要右移,所以地址最好只在一个宏里定义,注释写清楚它是 8 位还是 7 位。
读地址 0x79 在 OLED 上基本用不到,SSD1306 一般只写不读。但如果你的地址扫描程序扫出 0x78 和 0x79 两个响应,说明屏在线,问题不在硬件,直接去查控制字节和初始化序列。
4.2 控制字节 0x00 与 0x40:命令和数据的分界
I2C 模式下,每次传输的第一个字节是控制字节,不是显存数据。0x00 表示后续字节全部按命令解释,0x40 表示后续字节全部按数据写进显存。这个字节由 SSD1306 定义,Co 位和 D/C# 位组合出来的常见值就是这两个。
最容易翻车的地方是把控制字节写反:初始化时用 0x40 发命令,屏会把对比度、页地址这些命令当成显存内容写进去,现象是屏幕全黑但函数返回成功;刷新显存时用 0x00 发数据,数据被当成命令,现象是花屏或者画面只动一小块。判断方法很简单:拿逻辑分析仪抓一帧,看起始条件后的第二个字节是不是 0x00 或 0x40,如果不是,先改代码再怀疑硬件。
4.3 超时 100ms 与 tmp[128] 的边界
HAL_I2C_Master_Transmit 的最后一个参数是超时,单位毫秒。给 100 的意思是:总线被拉低、从机不应答时,函数最多阻塞 100ms 就返回 HAL_TIMEOUT,不会把整个系统卡死。这个值不要给 0(有的 HAL 版本里 0 表示永久等待),也不建议给几千,否则一次接线错误就能让主循环停几秒。
缓冲区的问题更隐蔽。3.2 节的代码写的是 uint8_t tmp[128],循环里 tmp[i + 1] = buf[i],当 len 等于 128 时,最后一次写的是 tmp[128],已经越过数组末尾。整屏刷新如果按 128 字节一页发,正好踩在这个边界上,现象是偶发花屏、程序跑飞,或者改一个无关变量就好了——典型的栈被写穿。改成 129 并加上长度保护:
c复制void OLED_WriteBytes(uint8_t ctrl, uint8_t *buf, uint16_t len)
{
uint8_t tmp[129];
if (len > 128) {
len = 128; // 单次最多 128 字节数据
}
tmp[0] = ctrl;
for (uint16_t i = 0; i < len; i++) {
tmp[i + 1] = buf[i];
}
HAL_I2C_Master_Transmit(&hi2c1, OLED_ADDR, tmp, len + 1, 100);
}
这样即使上层传了 200,也会被截到 128,剩下的部分由调用方分页发。截断不是万能药,但至少不会写穿栈。
4.4 整屏刷新为什么建议按页发
SSD1306 的显存是 8 页,每页 128 列,整屏 1024 字节。一次发 1024 字节需要 1025 字节的缓冲区,一般单片机不会为刷屏单独留这么大一块栈,而且 I2C 一次传太长,中途被高优先级中断打断的概率也高。按页发每次 128 字节数据加 1 字节控制,缓冲区 129 刚好,失败一页也只影响一页。
c复制/* 分页刷新:每页 128 字节,页地址与列地址命令按屏手册发 */
for (uint8_t page = 0; page < 8; page++) {
OLED_WriteCmd(0xB0 | page); /* 常见页地址命令,具体以手册为准 */
OLED_WriteCmd(0x00); /* 列低 4 位 */
OLED_WriteCmd(0x10); /* 列高 4 位 */
OLED_WriteBytes(0x40, &gram[page * 128], 128);
}
页地址和列地址命令各家的屏可能有差异,以模块手册为准,但“每页 128 字节、分 8 次发”这个结构是通用的。刷新一页大约几毫秒,肉眼看不到闪烁,CPU 占用也比一次发 1024 字节可控。
5. 避坑排查:全黑、花屏、越界与总线卡死的现象对照
调试 OLED 最怕的是“不亮”三个字,因为不亮可能是电源、复位、地址、控制字节、初始化序列里的任意一个。下面四条是按发生频率排的,每条都按现象、根因、处理三步走。遇到新问题先往这四条上靠,靠不上再动示波器。
5.1 现象:函数返回 HAL_OK,屏幕全黑
根因通常不在总线,而在控制字节或初始化序列。初始化时如果 OLED_WriteCmd 实际发的是 0x40,屏会把命令当显存数据吞掉,总线应答正常,函数返回成功,但显示配置一项都没生效。另一种情况是初始化序列根本没发完就进了主循环,屏还停在复位后的关闭状态。
处理办法是先把 OLED_WriteCmd 单独拎出来,用逻辑分析仪确认每次命令传输的第二个字节是 0x00;再确认上电后先拉低 RES 再拉高,等一小段时间再发初始化命令。如果这两步都对,最后才去查初始化命令表是不是照着手册抄全了,尤其是“开显示”那一条,漏了就是全黑。
5.2 现象:一调用就返回错误或超时
先查地址。HAL_I2C_Master_Transmit 要 8 位地址,传 0x3C 会直接超时;改成 0x78 再试。如果地址对了还是超时,用万用表量 SCL、SDA 对地电压,正常空闲时都应该是高电平,被拉死在低电平说明从机没释放总线,或者上拉电阻没接。
再查速率。Fast Mode 下排线太长、上拉太弱,波形上升沿爬不上去,从机会认错位,表现也是超时或 HAL_ERROR。临时把速率降到 Standard Mode,能通就说明是信号完整性问题,回头再调上拉和走线,而不是继续在代码里找。
5.3 现象:整屏刷新时花屏或程序跑飞
这是 4.3 节那个 tmp[128] 的典型症状。单页刷新正常,整屏刷新偶发花屏,或者刷新几秒后程序跳进 HardFault,改一个不相干的局部变量又好了——栈被写穿的经典表现。根因是 len 等于 128 时 tmp[128] 越界,写到了相邻的局部变量或返回地址。
处理办法是把缓冲区改成 129,并在函数入口加 len > 128 的截断;同时检查调用方是不是真的按 128 一页传,不要图省事一次传 1024。改完之后如果还花屏,再去看页地址命令有没有发对,那是另一个问题。
5.4 现象:SPI 接法下画面错位、花屏
先看 DC 和 CS 的时序。DC 接反的现象很好认:命令被当数据写进显存,画面是随机噪点;数据被当命令,画面只刷新一小块或者完全不动。CS 如果一直拉低不释放,多字节传输之间没有分界,屏会把整段当成一个长命令,现象也是花屏。
处理办法是用逻辑分析仪抓 SPI 的 CS、DC、SCK、MOSI 四根线,确认每个字节传输期间 CS 为低、字节之间拉高,DC 在第一个时钟沿之前就已经稳定。如果 DC 是在时钟沿之后才翻转,说明 HAL_GPIO_WritePin 和 HAL_SPI_Transmit 的顺序写反了,调整成先设 DC 再发数据。
6. 代码开发工具视角的验证:状态码、波形与一帧数据的对照法
调通之后我习惯留一套验证顺序,换屏、换接口、换板子都按这个顺序走一遍,比反复改代码快。第一步看返回值,HAL 的状态码已经把问题分成了几类;第二步抓波形,确认线上真的发了你以为发了的东西;第三步对数据,拿一帧显存和控制字节逐字节比。
| HAL 返回值 | 常见含义 | 先查什么 |
|---|---|---|
HAL_OK |
收发完成 | 地址、控制字节、DC 电平 |
HAL_ERROR |
参数或总线错误 | 地址是否 8 位、句柄是否初始化 |
HAL_TIMEOUT |
超时 | SCL/SDA 是否被拉低、上拉电阻 |
HAL_BUSY |
外设忙 | 是否在中断里重入、上次传输未结束 |
返回值只能告诉你“总线层成没成”,不能告诉你“屏收没收到”。所以第二步一定是逻辑分析仪:I2C 看起始条件后的第一个字节是不是 0x78,第二个字节是不是 0x00 或 0x40;SPI 看 CS 有没有在字节间拉高、DC 有没有在时钟沿前稳定。第三步对数据,把一页 128 字节的显存打印出来,和屏上实际显示比对,错位就查页地址和列地址,乱码就查控制字节。
还有一个习惯:每次换接口,先把 OLED_WriteCmd 和 OLED_WriteData 单独测一遍,发一条对比度命令,看屏的亮度有没有变化。亮度变了说明命令通道通了,再发数据;亮度不变就先别动显存代码,问题一定在命令通道上。从那以后我每次换屏、换接口,都先把地址和控制字节打印出来,再用逻辑分析仪抓一帧,确认无误才往下写显存刷新——这套顺序救过我很多次,也希望帮到你。
