单片机与物联网 / 系统课时
驱动 OLED 显示屏
驱动 OLED 显示屏
本课以常见的 0.96 英寸 SSD1306 OLED 为例,使用 STM32 HAL 库完成 I2C 接线、初始化、显存刷新,并在屏幕上显示字符、数字和矩形边框。完成后,你将得到一个可继续扩展字库和图形接口的最小驱动。
学习目标
- 理解 SSD1306 的 I2C 地址、控制字节和显存组织方式
- 完成 OLED 初始化、像素绘制与整屏刷新
- 能根据显示现象定位地址、接线和刷新流程问题
方案选择与接线
SSD1306 模块常见接口为 I2C 或 SPI。I2C 只需要时钟线和数据线,适合引脚紧张、刷新频率要求不高的项目;SPI 占用更多引脚,但吞吐量更高。下面选择 I2C 方案,使用 128×64 分辨率和地址 0x3C。
| 项目 | I2C | SPI |
|---|---|---|
| 信号线 | SCL、SDA | SCK、MOSI、CS、DC,部分模块还有 RST |
| STM32 配置 | I2C 主机模式 | SPI 主机模式加 GPIO |
| 适用场景 | 文本、状态页、低频刷新 | 动画、频繁整屏刷新 |
模块使用 3.3 V 供电时,SCL 和 SDA 应上拉到 3.3 V。若开发板或模块已带上拉电阻,不要重复并联过小阻值。示例采用 PB6 作为 SCL、PB7 作为 SDA,实际引脚以芯片复用表和 CubeMX 配置为准。

初始化与显存刷新
128×64 单色屏共有 8192 个像素,占用 1024 字节显存。SSD1306 按 8 个垂直像素组成一页,共 8 页;修改像素时先写入 MCU 内存中的缓冲区,再一次性发送到屏幕,可避免逐像素通信造成闪烁。
HAL 库发送地址时使用 8 位形式,因此 7 位地址 0x3C 需要左移一位得到 0x78。命令通过控制字节 0x00 发送,显存数据通过 0x40 发送。
下面是驱动核心代码。它是片段示例,依赖 CubeMX 已生成并初始化 hi2c1,文件中还需声明对应头文件和函数原型。
#include "main.h"
#include <stddef.h>
#include <stdint.h>
extern I2C_HandleTypeDef hi2c1;
#define OLED_ADDR (0x3CU << 1)
#define OLED_WIDTH 128U
#define OLED_HEIGHT 64U
#define OLED_BUFFER_SIZE (OLED_WIDTH * OLED_HEIGHT / 8U)
static uint8_t oled_buffer[OLED_BUFFER_SIZE];
typedef struct {
char ch;
uint8_t col[5];
} Glyph5x7;
static const Glyph5x7 font[] = {
{'0', {0x3E, 0x51, 0x49, 0x45, 0x3E}},
{'1', {0x00, 0x42, 0x7F, 0x40, 0x00}},
{'2', {0x42, 0x61, 0x51, 0x49, 0x46}},
{'3', {0x21, 0x41, 0x45, 0x4B, 0x31}},
{'4', {0x18, 0x14, 0x12, 0x7F, 0x10}},
{'5', {0x27, 0x45, 0x45, 0x45, 0x39}},
{'6', {0x3C, 0x4A, 0x49, 0x49, 0x30}},
{'7', {0x01, 0x71, 0x09, 0x05, 0x03}},
{'8', {0x36, 0x49, 0x49, 0x49, 0x36}},
{'9', {0x06, 0x49, 0x49, 0x29, 0x1E}},
{'S', {0x46, 0x49, 0x49, 0x49, 0x31}},
{'T', {0x01, 0x01, 0x7F, 0x01, 0x01}},
{'M', {0x7F, 0x02, 0x0C, 0x02, 0x7F}}
};
static HAL_StatusTypeDef OLED_WriteCommand(uint8_t command)
{
return HAL_I2C_Mem_Write(
&hi2c1, OLED_ADDR, 0x00, I2C_MEMADD_SIZE_8BIT,
&command, 1, 100
);
}
void OLED_Clear(void)
{
for (size_t i = 0; i < OLED_BUFFER_SIZE; ++i) {
oled_buffer[i] = 0x00;
}
}
void OLED_DrawPixel(uint8_t x, uint8_t y, uint8_t on)
{
if (x >= OLED_WIDTH || y >= OLED_HEIGHT) {
return;
}
uint16_t index = x + (uint16_t)(y / 8U) * OLED_WIDTH;
uint8_t mask = (uint8_t)(1U << (y % 8U));
if (on != 0U) {
oled_buffer[index] |= mask;
} else {
oled_buffer[index] &= (uint8_t)~mask;
}
}
void OLED_DrawRect(uint8_t x, uint8_t y, uint8_t width, uint8_t height)
{
if (width == 0U || height == 0U) {
return;
}
for (uint8_t i = 0; i < width; ++i) {
OLED_DrawPixel((uint8_t)(x + i), y, 1);
OLED_DrawPixel((uint8_t)(x + i), (uint8_t)(y + height - 1U), 1);
}
for (uint8_t i = 0; i < height; ++i) {
OLED_DrawPixel(x, (uint8_t)(y + i), 1);
OLED_DrawPixel((uint8_t)(x + width - 1U), (uint8_t)(y + i), 1);
}
}
static const uint8_t *OLED_FindGlyph(char ch)
{
for (size_t i = 0; i < sizeof(font) / sizeof(font[0]); ++i) {
if (font[i].ch == ch) {
return font[i].col;
}
}
return NULL;
}
void OLED_DrawChar(uint8_t x, uint8_t y, char ch)
{
const uint8_t *glyph = OLED_FindGlyph(ch);
if (glyph == NULL) {
return;
}
for (uint8_t col = 0; col < 5U; ++col) {
for (uint8_t row = 0; row < 7U; ++row) {
uint8_t on = (uint8_t)((glyph[col] >> row) & 0x01U);
OLED_DrawPixel((uint8_t)(x + col), (uint8_t)(y + row), on);
}
}
}
void OLED_DrawString(uint8_t x, uint8_t y, const char *text)
{
while (*text != '\0') {
OLED_DrawChar(x, y, *text++);
x = (uint8_t)(x + 6U);
}
}
HAL_StatusTypeDef OLED_Update(void)
{
const uint8_t window[] = {0x21, 0x00, 0x7F, 0x22, 0x00, 0x07};
for (size_t i = 0; i < sizeof(window); ++i) {
if (OLED_WriteCommand(window[i]) != HAL_OK) {
return HAL_ERROR;
}
}
return HAL_I2C_Mem_Write(
&hi2c1, OLED_ADDR, 0x40, I2C_MEMADD_SIZE_8BIT,
oled_buffer, OLED_BUFFER_SIZE, 500
);
}
HAL_StatusTypeDef OLED_Init(void)
{
const uint8_t init_commands[] = {
0xAE, 0xD5, 0x80, 0xA8, 0x3F, 0xD3, 0x00, 0x40,
0x8D, 0x14, 0x20, 0x00, 0xA1, 0xC8, 0xDA, 0x12,
0x81, 0x7F, 0xD9, 0xF1, 0xDB, 0x40, 0xA4, 0xA6,
0xAF
};
HAL_Delay(100);
if (HAL_I2C_IsDeviceReady(&hi2c1, OLED_ADDR, 3, 100) != HAL_OK) {
return HAL_ERROR;
}
for (size_t i = 0; i < sizeof(init_commands); ++i) {
if (OLED_WriteCommand(init_commands[i]) != HAL_OK) {
return HAL_ERROR;
}
}
OLED_Clear();
return OLED_Update();
}生效后,OLED_Init() 会完成设备探测、控制器配置和清屏;OLED_Update() 负责把 1024 字节缓冲区刷新到屏幕。若模块分辨率、扫描方向或供电电路不同,应以模块数据手册调整初始化命令。
显示字符、数字和图形
在 main.c 中完成 HAL、时钟、GPIO 和 I2C 初始化后,再调用 OLED 驱动。以下入口代码依赖 CubeMX 生成的 SystemClock_Config()、MX_GPIO_Init() 和 MX_I2C1_Init()。
#include "main.h"
void OLED_Clear(void);
void OLED_DrawString(uint8_t x, uint8_t y, const char *text);
void OLED_DrawRect(uint8_t x, uint8_t y, uint8_t width, uint8_t height);
HAL_StatusTypeDef OLED_Init(void);
HAL_StatusTypeDef OLED_Update(void);
int main(void)
{
HAL_Init();
SystemClock_Config();
MX_GPIO_Init();
MX_I2C1_Init();
if (OLED_Init() != HAL_OK) {
Error_Handler();
}
OLED_Clear();
OLED_DrawString(8, 12, "STM32");
OLED_DrawString(8, 28, "123");
OLED_DrawRect(2, 6, 60, 38);
if (OLED_Update() != HAL_OK) {
Error_Handler();
}
while (1) {
HAL_Delay(1000);
}
}预期结果如下;屏幕方向可能因模块初始化参数不同而镜像或翻转。
OLED 点亮并保持显示:
- 矩形边框
- 第一行 STM32
- 第二行 123当前字库只覆盖示例使用的字符。扩展完整 ASCII 或中文字库时,应把字模数据独立放入字体文件,并根据字宽、字高和编码方式实现新的绘制函数。
常见问题与定位
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 完全不亮 | 电源、地址、SCL/SDA | 用 HAL_I2C_IsDeviceReady() 扫描 0x3C 和 0x3D |
| 亮屏但无内容 | 未调用刷新函数 | 修改缓冲区后执行 OLED_Update() |
| 图像上下颠倒 | 扫描方向命令不匹配 | 调整 0xA0/0xA1 与 0xC0/0xC8 |
| 偶发花屏 | 上拉、线长、总线频率 | 缩短连线,先降到 100 kHz 验证 |
| 只显示部分区域 | 分辨率或窗口配置错误 | 核对 0xA8、列范围和页范围 |
排查时先确认设备能够应答,再检查初始化命令,最后检查缓冲区索引和刷新窗口。不要在地址未确认时反复修改字库或绘图算法。
验收标准
完成驱动后,应能稳定通过设备探测,复位或重新上电后自动点亮,并正确显示边框、字符和数字。连续刷新不同内容时不应出现明显残影、随机花屏或总线超时。