STM32IIC实战-OLED模板

在掌握了基础的单片机控制和通信之后，是时候为你的项目添加一块小巧而酷炫的显示屏了。OLED (Organic Light-Emitting Diode) 屏幕因其自发光、高对比度、低功耗和宽视角等优点，在嵌入式项目中越来越受欢迎。

本教程将重点介绍如何驱动基于 SSD1306 控制芯片的单色 OLED 显示屏，这种屏幕通常分辨率为 128x64 或 128x32，常用于显示文本、简单图形和状态信息。

我们将使用 STM32 HAL 库，通过 I2C (Inter-Integrated Circuit) 接口与 OLED 模块通信，并详细介绍如何移植一个常用的 SSD1306 驱动库。

一，SSD1306 控制芯片

SSD1306 是一款广泛用于单色 OLED 显示屏的控制器驱动芯片。了解它的基本特性有助于我们更好地进行驱动开发。

1， 主要特性

显示类型: 单色（通常为白色、蓝色或黄蓝双色）被动矩阵 OLED (PMOLED)。
分辨率: 最大支持 128x64 像素。常见的模块有 128x64 (0.96英寸) 和 128x32 (0.91英寸)。
接口: 支持多种通信接口，包括 I2C、SPI (3线或4线) 和并行接口。本教程聚焦于 I2C 接口。
内部 RAM (GDDRAM): 芯片内置图形显示数据 RAM (Graphic Display Data RAM)，大小通常为 128x64位 (1KB)。MCU 通过接口将要显示的像素数据写入 GDDRAM，SSD1306 负责根据 GDDRAM 的内容点亮屏幕上的像素点。
工作电压: 逻辑电压通常为 3.3V 或 5V，但屏幕驱动电压可能需要内部电荷泵升压。
控制方式: 通过发送一系列命令来配置显示参数（如对比度、显示开关、地址模式等），并通过发送数据来更新 GDDRAM 内容。

2，I2C 通信协议

当使用 I2C 接口时，SSD1306 模块通常表现为一个 I2C 从设备，拥有一个固定的设备地址（通常是 0x78 或 0x7A，可能通过模块上的跳线选择）。

与 SSD1306 的 I2C 通信包含两种主要类型的传输：

写命令 (Write Command): MCU 向 SSD1306 发送控制字节，用于设置显示模式、对比度等。
写数据 (Write Data): MCU 向 SSD1306 发送数据字节，这些字节会被写入 GDDRAM，用于更新屏幕显示内容。
SSD1306 通过一个特定的控制字节来区分接收到的数据是命令还是数据。通常，控制字节的格式为：

命令: 0x00 (Co=0, D/C#=0) + Command Byte
数据: 0x40 (Co=0, D/C#=1) + Data Byte
因此，MCU 在发送命令或数据前，需要先发送对应的控制字节。

3， 显示原理

SSD1306 驱动的是被动矩阵 OLED (PMOLED)。屏幕由水平的行线 (Common Electrodes, SEG) 和垂直的列线 (Segment Electrodes, COM) 交叉构成。每个交叉点就是一个像素 (一个 OLED 发光点)。

GDDRAM 映射: 芯片内部的 GDDRAM (图形显示数据 RAM) 存储了每个像素的开关状态。对于 128x64 的屏幕，GDDRAM 通常是 1KB (128 * 64 / 8 = 1024 bytes)。GDDRAM 中的每一位 (bit) 对应屏幕上的一个像素：‘1’ 表示点亮，‘0’ 表示熄灭。
扫描与驱动: SSD1306 通过快速、分时地扫描 COM 线，并根据 GDDRAM 中的数据控制 SEG 线上的电平，来逐行（或逐页）点亮对应的像素。由于人眼的视觉暂留效应，我们感觉整个屏幕是同时亮的。
页面结构: GDDRAM 通常按"页 (Page)"组织。对于 128x64 屏幕，通常分为 8 页 (Page 0 ~ Page 7)，每页包含 128 列 x 8 行像素 (128 bytes)。写入数据时，通常需要先设置目标页地址和列地址。
理解 GDDRAM 与像素的映射关系以及页面结构，对于直接操作显存或编写底层驱动至关重要。

4， 控制流程

与 SSD1306 交互通常遵循以下基本流程：

初始化序列 (Initialization Sequence): 上电后，需要向 SSD1306 发送一系列特定的命令来配置其工作状态。这通常包括：
解锁命令（如果需要）。
关闭显示 (0xAE)。
设置显示时钟分频系数和振荡器频率。
设置 MUX 复用比 (决定扫描行数，如 64 行对应 0xA8, 0x3F)。
设置显示偏移 (0xD3, 0x00)。
设置起始行 (0x40 | 0x00)。
配置电荷泵 (Charge Pump) 以产生 OLED 所需的高电压 (0x8D, 0x14)。
配置内存地址模式 (水平、垂直或页面地址模式，0x20, 0x00/0x01/0x02)。
设置 SEG/COM 引脚硬件配置 (0xDA, 0x12)。
设置对比度 (0x81, 0xCF)。
设置预充电周期 (0xD9, 0xF1)。
设置 VCOMH 电压 (0xDB, 0x40)。
设置整个屏幕显示来自 GDDRAM (0xA4) 或强制点亮 (0xA5)。
设置正常/反相显示 (0xA6 / 0xA7)。
开启显示 (0xAF)。

这个初始化序列非常关键，通常由驱动库的 OLED_Init() 函数完成。命令和参数的具体值可能因模块或驱动库而异。

设置地址指针: 在写入像素数据之前，需要发送命令设置 GDDRAM 的目标页地址和列地址 (例如，使用页面地址模式时，发送 0xB0 | page_num, 0x00 | (col & 0x0F), 0x10 | (col >> 4))。
写入数据: 发送写数据指令 (控制字节 0x40) 和随后的像素数据字节。数据会根据设置的地址模式自动写入 GDDRAM，并且地址指针通常会自动递增。
重复 2 和 3: 根据需要更新屏幕的不同区域。
例如，清屏操作本质上就是将 GDDRAM 的所有字节都设置为 0x00。

5， 开发思路

在项目中集成 OLED 显示时，有几种常见的开发策略：

直接命令操作: 直接根据 SSD1306 数据手册发送 I2C/SPI 命令和数据。这种方式最灵活，但也最复杂，需要深入理解芯片细节。适用于资源极其受限或需要高度定制的场景。
封装底层驱动库: 编写或移植一个基础驱动库（如此教程第 4 节示例）。该库封装初始化序列、基本的写命令/数据函数，以及一些基础绘图函数（如清屏、设置点、显示字符/字符串）。这是比较常见的做法，在复杂度和易用性之间取得平衡。
使用图形库 (如 u8g2): 对于需要绘制复杂图形、使用多种字体或构建用户界面的应用，强烈推荐使用成熟的图形库（如此教程第 5 节的 u8g2）。这些库提供了丰富的 API，屏蔽了底层的硬件细节，开发者可以专注于应用逻辑。缺点是会占用更多的 Flash 和 RAM 资源。
显存管理策略:

全缓冲 (Full Buffer): 在 MCU 的 RAM 中创建一个与 OLED 显存同样大小的缓冲区。所有绘图操作先更新 RAM 缓冲区，最后一次性将整个缓冲区发送到 OLED。优点是绘图灵活，避免闪烁；缺点是占用较多 RAM (例如 128x64 屏需要 1KB RAM)。u8g2 的 _f 后缀模式即为此。
页缓冲 (Page Buffer / Partial Buffer): 只在 MCU RAM 中创建一页或几页大小的缓冲区。绘图时按页进行，绘制完一页就发送一页。优点是 RAM 占用少；缺点是绘图逻辑相对复杂，跨页绘制需要特殊处理。u8g2 的 _1 (单页) 或 _2 (双页) 后缀模式属于此类。
无缓冲 (Direct Draw): 不在 MCU 中创建缓冲区，直接计算像素位置并发送命令/数据到 OLED。RAM 占用最少，但绘图效率最低，且容易产生闪烁，通常只适用于非常简单的静态显示。
选择哪种开发思路和显存管理策略，需要根据项目需求、MCU 资源限制以及开发效率要求来权衡。

二，HAL I2C API 解析

STM32 HAL 库为我们提供了方便的函数来操作 I2C 外设，从而与 SSD1306 进行通信。以下是驱动 OLED 时常用的一些 HAL I2C API。

I2C 相关 API

1，

I2C_HandleTypeDef (句柄)

这是 I2C 外设的"控制器"结构体。它包含了 I2C 的配置信息（如时钟速度、地址模式、使用的引脚等）、运行时状态和错误代码。所有 I2C 相关的 HAL 函数都需要传递一个指向该类型结构体的指针（例如 &hi2c1）。该结构体通常由 CubeMX 自动生成和初始化。

2，

HAL_StatusTypeDef HAL_I2C_Init(I2C_HandleTypeDef *hi2c)

用途: 根据 I2C_HandleTypeDef 结构体中的配置信息初始化 I2C 外设。
参数: hi2c - 指向 I2C 句柄的指针。
返回: HAL_OK (成功), HAL_ERROR, HAL_BUSY。
说明: 通常在系统启动时由 CubeMX 生成的 MX_I2C1_Init() (或类似) 函数内部调用。我们一般不需要手动调用它。

3，

HAL_StatusTypeDef HAL_I2C_Master_Transmit(I2C_HandleTypeDef *hi2c, uint16_t DevAddress, uint8_t *pData, uint16_t Size, uint32_t Timeout)

用途: 以 Master 模式通过 I2C 发送数据到指定的从设备地址。
参数:
hi2c: 指向 I2C 句柄的指针。
DevAddress: 目标从设备的 7 位地址。注意： HAL 库通常需要传入左移一位的地址（即包含读写位的 8 位地址格式，但最低位会被函数内部处理）。例如，如果 OLED 地址是 0x3C (7位)，则应传入 0x3C << 1 或 0x78。具体请参考 HAL 库文档或示例。驱动库内部通常会处理好地址。
pData: 指向要发送的数据缓冲区的指针。
Size: 要发送的数据字节数。
Timeout: 发送超时时间（毫秒）。
返回: HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT。
说明: 这是向 OLED 发送命令或数据的主要方式之一。pData 缓冲区通常需要包含 SSD1306 需要的控制字节 (0x00 或 0x40) 以及后续的命令/数据字节。

4，

HAL_StatusTypeDef HAL_I2C_Mem_Write(I2C_HandleTypeDef *hi2c, uint16_t DevAddress, uint16_t MemAddress, uint16_t MemAddSize, uint8_t *pData, uint16_t Size, uint32_t Timeout)

用途: 向 I2C 从设备的指定内存地址写入数据。这个函数在很多 I2C 设备驱动中常用，对于 SSD1306 来说，它可以巧妙地用来发送命令和数据。
参数:
hi2c: 指向 I2C 句柄的指针。
DevAddress: 目标从设备的 7 位地址 (同样需要注意左移)。
MemAddress: 目标内存地址。对于 SSD1306，这个参数可以被用来传递控制字节 (0x00 用于命令, 0x40 用于数据)。
MemAddSize: 内存地址的大小，对于传递控制字节，通常设置为 I2C_MEMADD_SIZE_8BIT。
pData: 指向要写入的数据缓冲区的指针 (实际的命令字节或像素数据)。
Size: 要写入的数据字节数。
Timeout: 超时时间（毫秒）。
返回: HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT。
说明: 许多 SSD1306 驱动库（包括我们将要移植的库）会使用 HAL_I2C_Mem_Write 来发送命令和数据。例如，发送一个命令字节 CMD，会调用 HAL_I2C_Mem_Write(&hi2c1, OLED_ADDR, 0x00, I2C_MEMADD_SIZE_8BIT, &CMD, 1, TIMEOUT)。发送一个数据字节 DATA，会调用 HAL_I2C_Mem_Write(&hi2c1, OLED_ADDR, 0x40, I2C_MEMADD_SIZE_8BIT, &DATA, 1, TIMEOUT)。这种方式简化了驱动代码。

5，

HAL_StatusTypeDef HAL_I2C_IsDeviceReady(I2C_HandleTypeDef *hi2c, uint16_t DevAddress, uint32_t Trials, uint32_t Timeout)

用途: 检查指定的 I2C 从设备是否在线并响应其地址。
参数:
hi2c: 指向 I2C 句柄的指针。
DevAddress: 要检查的从设备地址 (同样需要注意左移)。
Trials: 尝试发送地址的次数。
Timeout: 每次尝试的超时时间。
返回: HAL_OK (设备响应), HAL_ERROR, HAL_BUSY, HAL_TIMEOUT (设备未响应)。
说明: 在初始化 OLED 之前，可以调用此函数来确认 OLED 模块是否正确连接并且 I2C 通信正常。有助于调试硬件连接问题。

理解这些基本的 I2C 通信函数，特别是 HAL_I2C_Master_Transmit 或 HAL_I2C_Mem_Write 如何被用来发送命令和数据，是成功驱动 OLED 的关键。

三，移植 SSD1306 驱动

1，获取并放置驱动文件

1，在你的项目文件夹（例如 Keil 项目根目录）下，创建一个用于存放第三方组件的文件夹，例如 Components。

2，在 Components 文件夹内，再创建一个 Oled 文件夹。
创建 Oled 文件夹

3，从下面 Github 仓库下载驱动文件（通常是一个 ZIP 压缩包）。
https://github.com/yangjinhaoaa/OLED0.91-SSD1306-HAL

4，解压下载的文件。找到包含驱动源文件（如 oled.c, oled.h, oledfont.h 等）的文件夹（根据文档描述，可能是名为 0.91OLED-SSD1306-STM32HAL 的文件夹）。

5，将该文件夹中的所有 .c 和 .h 文件复制到你之前创建的 Components/Oled 文件夹中。

二，CubeMX 配置 I2C

1，确定引脚: 查阅你的开发板原理图或 OLED 模块说明，确定连接到 STM32 的 I2C SCL (时钟) 和 SDA (数据) 引脚。文档示例使用的是 PB8 (SCL) 和 PB9 (SDA)。

再CubeMX中找到IIC1，先不要使能，先根据上面原理图选择配置的引脚

模式选择为IIC模式，在下方的配置区域 (Configuration)，确认 I2C 的参数设置。标准模式 (Standard Mode) 速度 100kHz 或快速模式 (Fast Mode) 400kHz（这里选择快速模式用于后面的u8g2移植） 通常都可以。其他参数可以暂时保持默认。

确保对应的 SCL 和 SDA 引脚已在右侧芯片图上正确分配给所选的 I2C 功能。
生成代码

四，移植与配置驱动代码

1，添加文件到工程:

在 Keil 的 Project 窗口中，右键点击你的目标分组（或新建一个分组，如 Components），选择 “Add Existing Files to Group…”。
导航到 Components/Oled 文件夹，选择 oled.c 文件并添加。

2，添加头文件路径:

点击魔术棒图标 (Options for Target)。
切换到 “C/C++” 选项卡。
在 “Include Paths” 旁边的文本框后面的 “…” 按钮点击。
添加 Components/Oled 文件夹的路径。

3，包含头文件:

在你项目的主要头文件（例如 main.h 或一个自定义的 mydefine.h）中，添加 #include "oled.h"。

4，修改 I2C 句柄:

打开 oled.c 文件。找到驱动代码中使用 I2C 发送函数的地方（通常是调用 HAL_I2C_Mem_Write 或类似函数）。将代码中使用的 I2C 句柄（文档示例中是 &hi2c2）修改为你项目中实际使用的 I2C 句柄（由 CubeMX 生成，例如 &hi2c1）。
CubeMX生成的iic文件中，有一个hi2c1句柄

但组件库中使用的是hi2c2句柄，将组件库的句柄修改为我们实际使用的句柄

同时确保组件库中的iic设备地址与我们使用的芯片地址相同

五，创建应用层接口与任务

1，创建应用文件

在你的应用代码文件夹（例如 APP 或 Application）中，创建 oled_app.c 和 oled_app.h 文件。将 oled_app.c 添加到 Keil 工程中。

2，编写应用代码

将文档中提供的 oled_app.h 和 oled_app.c 的内容复制到对应文件中。Oled_Printf 函数提供了一个方便的、类似 printf 的接口来在 OLED 上显示格式化字符串。oled_task 是一个示例任务，用于显示简单文本。

/* oled_app.h */
#ifndef __OLED_APP_H__
#define __OLED_APP_H__#include "main.h" // 或者你的主要头文件 "mydefine.h"
#include  // 需要包含 stdarg.h 用于 va_list
#include   // 需要包含 stdio.h 用于 vsnprintf
#include "oled.h"   // 包含底层 OLED 驱动头文件int Oled_Printf(uint8_t x, uint8_t y, const char *format, ...);
void oled_task(void);#endif/* oled_app.c */
#include "oled_app.h"// 假设 OLED 宽度为 128 像素，使用 6x8 字体
// 每行 8 像素高，最多 64/8 = 8 行 (y=0~7) 或 32/8 = 4 行 (y=0~3)
// 每列 6 像素宽，最多 128/6 = 21 个字符 (x=0~20? 驱动库可能基于像素位置)
// **注意:** Oled_Printf 的 x, y 参数单位需要参考 OLED_ShowStr 实现，可能是字符位置或像素位置
// 文档中的注释 (0-127, 0-3) 暗示可能是 128x32 屏幕的像素 x 坐标和字符行 y 坐标/*** @brief	使用类似printf的方式显示字符串，显示6x8大小的ASCII字符* @param x  起始 X 坐标 (像素) 或 字符列位置 (需要看 OLED_ShowStr)* @param y  起始 Y 坐标 (像素) 或 字符行位置 (需要看 OLED_ShowStr, 0-3 或 0-7)* @param format, ... 格式化字符串及参数* 例如：Oled_Printf(0, 0, "Data = %d", dat);
**/
int Oled_Printf(uint8_t x, uint8_t y, const char *format, ...)
{char buffer[128]; // 缓冲区大小根据需要调整va_list arg;int len;va_start(arg, format);len = vsnprintf(buffer, sizeof(buffer), format, arg);va_end(arg);// 假设 OLED_ShowStr 使用像素坐标 x 和字符行 yOLED_ShowStr(x, y, (uint8_t*)buffer, 8); // 将 buffer 转为 uint8_t*return len;
}/* Oled 显示任务 */
void oled_task(void)
{// 清屏通常是需要的，否则旧内容会保留OLED_Cls();Oled_Printf(0, 0, "Hello World!!!");Oled_Printf(0, 2, "Welcome to MCU!");// 刷新显示到屏幕 (如果驱动库需要)// OLED_Refresh_Gram(); // 取决于驱动库是否有显存刷新机制
}

注意： 上述 Oled_Printf 的实现假设 OLED_ShowStr 的 y 参数是像素坐标。如果 OLED_ShowStr 的 y 参数是字符行号，则调用应改为 OLED_ShowStr(x, y, (uint8_t*)buffer, 8);。请查阅你移植的 oled.c 中 OLED_ShowStr 函数的注释或实现来确认。同时，可能需要调用清屏函数 OLED_Cls() 和刷新函数（如果驱动库有缓冲区机制）。

3，包含应用头文件

在你的主要头文件（例如 main.h 或 mydefine.h）中添加 #include "oled_app.h"。

六，集成与测试

1，调用初始化: 在 main.c 文件的 main 函数中，在 I2C 初始化 (MX_I2C1_Init()) 之后，调用 OLED 初始化函数。

2，集成到任务调度器 (如果使用): 如果你使用了任务调度器（如文档中的 scheduler.c），将 oled_task 添加到任务列表中，并设置合适的执行周期（例如 100ms 或 500ms，取决于刷新需求）。

3，编译和下载: 编译整个工程，并将生成的目标文件下载到你的 STM32 开发板。
4，观察结果: 如果一切顺利，你的 OLED 屏幕应该会显示 “Hello World!!!” 和 “Welcome to MCU!”。

调试提示： 如果屏幕没有显示或显示异常：
检查硬件连接： 确认 SCL, SDA, VCC, GND 连接牢固且正确。
检查 I2C 地址： 确认驱动代码中的 OLED_ADDRESS 与模块地址匹配。
检查 I2C 句柄： 确认 oled.c 中使用的 I2C 句柄 (&hi2c1?) 与 CubeMX 生成的一致。
使用 HAL_I2C_IsDeviceReady： 在 OLED_Init() 之前调用此函数检查设备是否响应。
查看 OLED_Init()： 确保初始化函数被成功调用。
确认 Oled_Printf 实现： 检查 OLED_ShowStr 的参数含义，调整 Oled_Printf 中的调用。
清屏与刷新： 确保在显示前调用了清屏函数，并在需要时调用了刷新函数（如果驱动库有缓冲区机制）。