STM32 OLED显示汉字实战：I2C驱动+字库调用全流程（附源码）

STM32 OLED显示汉字实战：I2C驱动+字库调用全流程（附源码）

在嵌入式设备开发中，一块小小的OLED屏幕往往能极大地提升产品的交互体验。无论是显示设备状态、实时数据，还是简单的菜单界面，中文显示都是本地化应用绕不开的需求。然而，对于许多初次接触STM32和OLED的开发者来说，从硬件连接到软件驱动，再到汉字字库的生成与调用，每一步都可能遇到意想不到的“坑”。这篇文章，我将结合自己多次在物联网设备上实现中文显示的经验，为你梳理一条清晰的路径，从GPIO配置、I2C时序模拟，到字库制作与缓存管理，手把手带你打通STM32驱动OLED显示中文的全流程。我会提供可直接使用的源码，并重点剖析那些容易出错的细节，让你在项目中能快速应用。

1. 硬件连接与I2C通信基础

在开始写代码之前，正确的硬件连接是第一步。我们常用的0.96寸或1.3寸OLED模块，大多采用SSD1306驱动芯片，并通过I2C接口通信。这种接口只需要两根线（SDA数据线和SCL时钟线），极大地节省了宝贵的IO资源。

硬件连接示意（以STM32F103C8T6为例）

注意：部分OLED模块还带有RES复位引脚和DC数据/命令选择引脚，那是用于SPI接口的。对于I2C接口的模块，通常只需要连接VCC、GND、SCL、SDA四根线。如果你的模块有RES，可以接一个GPIO进行硬件复位，但软件复位通常也够用。

I2C通信协议本身并不复杂，但对于没有硬件I2C外设的型号，或者为了追求极致的时序控制，我们常使用GPIO模拟（软件I2C）。其核心就是控制这两根线的时序。下面是一个最基本的GPIO模拟I2C起始信号函数：

/** * @brief 模拟I2C起始信号 * @param None * @retval None */ void I2C_Start(void) { OLED_SDA_OUT(); // 设置SDA为输出模式 OLED_SDA_HIGH(); OLED_SCL_HIGH(); delay_us(5); // 建立时间 OLED_SDA_LOW(); delay_us(5); // 保持时间 OLED_SCL_LOW(); // 钳住总线，准备发送数据 }

这里的关键在于时序的微秒级延时。SSD1306的I2C时序要求并不严苛，但必须保证信号建立（Setup）和保持（Hold）时间。过快可能导致通信失败，过慢则影响刷新率。根据我的实测，在STM32F103（72MHz）上，delay_us(5)是一个比较稳妥的值。你可以根据主频调整，或者直接使用HAL_Delay的微秒级实现。

2. SSD1306 OLED驱动初始化与基础绘图

成功建立I2C通信后，下一步就是配置SSD1306驱动芯片。这需要发送一系列初始化命令，设置对比度、显示模式、扫描方向、内存地址模式等。这个过程比较固定，但有几个参数需要根据你的屏幕型号调整。

核心初始化命令解析

void OLED_Init(void) { // ... GPIO初始化代码 ... delay_ms(100); // 等待OLED上电稳定 OLED_WR_Byte(0xAE, OLED_CMD); // 关闭显示 OLED_WR_Byte(0xD5, OLED_CMD); // 设置显示时钟分频比/振荡器频率 OLED_WR_Byte(0x80, OLED_CMD); // 建议值 0x80 OLED_WR_Byte(0xA8, OLED_CMD); // 设置多路复用率 OLED_WR_Byte(0x3F, OLED_CMD); // 对于128x64的屏幕，此为0x3F (1/64 duty) OLED_WR_Byte(0xD3, OLED_CMD); // 设置显示偏移 OLED_WR_Byte(0x00, OLED_CMD); // 无偏移 OLED_WR_Byte(0x40, OLED_CMD); // 设置显示起始行 (行0) OLED_WR_Byte(0x8D, OLED_CMD); // 电荷泵设置 OLED_WR_Byte(0x14, OLED_CMD); // 使能电荷泵（必须，否则屏幕不亮） OLED_WR_Byte(0x20, OLED_CMD); // 设置内存地址模式 OLED_WR_Byte(0x00, OLED_CMD); // 水平地址模式 OLED_WR_Byte(0xA1, OLED_CMD); // 段重映射设置 (0xA1 列地址127映射到SEG0) OLED_WR_Byte(0xC8, OLED_CMD); // 行扫描方向设置 (0xC8 从COM[N-1]到COM0) OLED_WR_Byte(0xDA, OLED_CMD); // 设置COM引脚硬件配置 OLED_WR_Byte(0x12, OLED_CMD); // 对于128x64，此为0x12 (Alternative COM pin config) OLED_WR_Byte(0x81, OLED_CMD); // 设置对比度控制 OLED_WR_Byte(0xCF, OLED_CMD); // 对比度值 (0x00~0xFF) OLED_WR_Byte(0xD9, OLED_CMD); // 设置预充电周期 OLED_WR_Byte(0xF1, OLED_CMD); // 建议值 OLED_WR_Byte(0xDB, OLED_CMD); // 设置VCOMH电压倍率 OLED_WR_Byte(0x40, OLED_CMD); // 建议值 OLED_WR_Byte(0xA4, OLED_CMD); // 关闭全局显示开启 (使用RAM内容) OLED_WR_Byte(0xA6, OLED_CMD); // 设置正常显示 (非反色) OLED_WR_Byte(0xAF, OLED_CMD); // 开启显示 OLED_Clear(); // 清屏 }

这里有几个容易踩坑的点：

1. 电荷泵 (0x8D, 0x14)：这个命令必须发送，否则屏幕没有驱动电压，一片漆黑。
2. 多路复用率 (0xA8)：对于常见的128x64屏幕，值必须是0x3F(63)。如果设置错误，显示会错乱或只有一部分。
3. COM引脚配置 (0xDA, 0x12)：这个值也跟屏幕硬件有关，0x12是128x64的常见值，128x32的屏幕可能是0x02。

初始化完成后，我们操作的是OLED的显示缓存(GDDRAM)。SSD1306的GDDRAM结构比较特殊，它被分为8个页（Page），每页128列，每列8个像素（即一个字节）。所以整个128x64的屏幕对应一个128 x 8的字节数组。我们所有的绘图操作，都是先修改这个内存数组，然后通过OLED_Refresh()函数一次性刷到屏幕上。

定义显存与画点函数

// 定义显存，对应128列 x 8页，每页8行 uint8_t OLED_GRAM[128][8]; // 在(x,y)坐标画点 (0<=x<128, 0<=y<64) void OLED_DrawPoint(uint8_t x, uint8_t y) { uint8_t page, bit_mask; if(x >= 128 || y >= 64) return; // 边界检查 page = y / 8; // 计算在哪一页 (0~7) bit_mask = 1 << (y % 8); // 计算在该字节的哪一位 OLED_GRAM[x][page] |= bit_mask; // 置1，点亮像素 }

这个OLED_DrawPoint函数是所有高级图形（线、圆、字符）的基础。理解page = y / 8和bit_mask = 1 << (y % 8)是理解OLED驱动原理的关键。它巧妙地将二维的(x,y)坐标映射到了一维的字节数组和位操作上。

3. 汉字字库的制作与嵌入式

显示英文和数字相对简单，因为ASCII字符集小，可以直接把点阵数组放在代码里。但汉字数量庞大，全字库动辄几百KB，对于资源有限的STM32来说不现实。因此，我们通常采用提取项目所需汉字，制作小型自定义字库的方案。

第一步：获取汉字点阵数据你需要一个取模软件。这类软件很多，比如“PCtoLCD2002”。设置好字体（如宋体）、大小（如16x16）、取模方式（至关重要）后，输入你需要的汉字，软件会生成对应的十六进制数组。

取模方式设置（必须与代码匹配）

• 扫描方式：逐列式（纵向取模，字节倒序）或逐行式（横向取模）。这取决于你后续的显示算法如何解析数据。
• 取模走向：顺向（高位在前）或逆向（低位在前）。
• 输出格式：C语言格式，十六进制。

假设我们取模“温度”两个16x16的汉字，软件可能生成如下数据：

// 汉字"温" 16x16 点阵，逐列式，字节倒序 const unsigned char wen_16x16[] = { 0x10,0x60,0x02,0x8C,0x00,0x00,0xFE,0x92,0x92,0x92,0x92,0x92,0xFE,0x00,0x00,0x00, 0x04,0x04,0x7E,0x01,0x40,0x7E,0x42,0x42,0x7E,0x42,0x7E,0x42,0x42,0x7E,0x40,0x00 }; // 汉字"度" 16x16 点阵 const unsigned char du_16x16[] = { 0x00,0x00,0xFC,0x24,0x24,0x24,0xFC,0x25,0x26,0x24,0xFC,0x24,0x24,0x24,0x04,0x00, 0x40,0x30,0x8F,0x80,0x84,0x4C,0x55,0x25,0x25,0x25,0x55,0x4C,0x80,0x80,0x80,0x00 };

一个16x16的汉字需要32个字节（16列 * 2字节/列）。第一行16字节是汉字的上半部分（前8行），第二行16字节是下半部分（后8行）。

第二步：组织字库数组为了便于索引，我们通常会把所有需要的汉字点阵放在一个二维数组里，并建立一个索引表（比如，通过汉字的GB2312内码或自定义序号来查找）。

// 将多个汉字的点阵数据按顺序放入一个二维数组 const unsigned char HZK16[][32] = { // "温" {0x10,0x60,0x02,0x8C,0x00,0x00,0xFE,0x92,0x92,0x92,0x92,0x92,0xFE,0x00,0x00,0x00, 0x04,0x04,0x7E,0x01,0x40,0x7E,0x42,0x42,0x7E,0x42,0x7E,0x42,0x42,0x7E,0x40,0x00}, // "度" {0x00,0x00,0xFC,0x24,0x24,0x24,0xFC,0x25,0x26,0x24,0xFC,0x24,0x24,0x24,0x04,0x00, 0x40,0x30,0x8F,0x80,0x84,0x4C,0x55,0x25,0x25,0x25,0x55,0x4C,0x80,0x80,0x80,0x00}, // ... 更多汉字 }; // 汉字索引枚举，方便代码调用 typedef enum { HZ_WEN = 0, // "温" HZ_DU = 1, // "度" // ... } HZ_INDEX;

第三步：编写汉字显示函数显示函数的核心是遍历字模数据的每一个字节的每一位，根据其是1还是0，在显存对应位置画点或清点。

/** * @brief 在指定位置显示一个汉字 * @param x: 起始列坐标 (0~127) * @param y: 起始行坐标 (0~63) * @param index: 汉字在字库数组中的索引 * @param size: 字体大小 (16, 24, 32等，需与字库匹配) * @retval None */ void OLED_ShowChinese(uint8_t x, uint8_t y, uint8_t index, uint8_t size) { uint8_t i, j, temp; uint8_t x0 = x, y0 = y; const unsigned char *pHz; // 指向汉字点阵数据的指针 if(size != 16) return; // 本例仅以16x16为例 if(index >= sizeof(HZK16)/32) return; // 防止数组越界 pHz = HZK16[index]; // 获取该汉字的点阵数据首地址 for(j=0; j<16; j++) { // 遍历16列 temp = *pHz++; // 读取上半部分8行数据 for(i=0; i<8; i++) { // 处理一个字节的8位 if(temp & 0x01) { OLED_DrawPoint(x, y); } else { OLED_ClearPoint(x, y); // 清点函数，实现类似 } temp >>= 1; // 移向下一位 y++; } temp = *pHz++; // 读取下半部分8行数据 for(i=0; i<8; i++) { if(temp & 0x01) { OLED_DrawPoint(x, y); } else { OLED_ClearPoint(x, y); } temp >>= 1; y++; } x++; // 移动到下一列 y = y0; // y坐标复位到起始行 if((x - x0) == size) { // 如果一列画完（针对size>16的情况） x = x0; y0 = y0 + 16; // 对于16x16，这里应该是+16？注意逻辑，本例是逐列画完32行。 // 实际上，对于16x16，我们一次处理两字节（16行），所以y0在循环外不变。 // 此判断和重置逻辑更适用于将一列的多字节分次画的情况。 } } }

注意：上面的示例函数逻辑是针对“逐列式、字节倒序”取模方式的。如果你的取模软件设置不同（例如横向取模），那么遍历数据的方式（先遍历行还是列）、字节中位的顺序（高位在前还是低位在前）都需要相应调整。务必保证取模设置与显示代码逻辑严格匹配，这是汉字显示成功的关键。

4. 显示缓存管理与高级应用技巧

直接操作显存数组OLED_GRAM，然后调用OLED_Refresh()刷屏，是一种简单有效的方式。但为了做出更流畅、更复杂的UI效果，我们还需要一些进阶技巧。

双缓冲与局部刷新频繁的全屏刷新（OLED_Refresh会发送128x8=1024字节）在低速I2C下可能导致闪烁。一种优化策略是局部刷新：只更新屏幕上发生变化的部分区域。

// 局部刷新函数示例（刷新指定页的指定列范围） void OLED_Refresh_Partial(uint8_t page, uint8_t start_col, uint8_t end_col) { uint8_t i; if(page > 7 || start_col > 127 || end_col > 127 || start_col > end_col) return; OLED_WR_Byte(0xB0 + page, OLED_CMD); // 设置页地址 OLED_WR_Byte(((start_col & 0xF0) >> 4) | 0x10, OLED_CMD); // 设置列地址高4位 OLED_WR_Byte(start_col & 0x0F, OLED_CMD); // 设置列地址低4位 for(i = start_col; i <= end_col; i++) { OLED_WR_Byte(OLED_GRAM[i][page], OLED_DATA); } }

当你只修改了显存中某一页的几列数据时，调用这个函数可以大大减少I2C通信量，实现无闪烁更新。

字符串显示与混排在实际项目中，我们经常需要显示动态字符串，比如“温度：25.6℃”。这就需要混合显示ASCII字符和汉字。

// 显示混合字符串（需提前实现OLED_ShowChar和OLED_ShowChinese） void OLED_ShowMixedString(uint8_t x, uint8_t y, char *str) { while(*str != '\0') { if((*str & 0x80) != 0) { // 判断是否为汉字（GBK编码高位为1） // 假设我们有一个函数将GBK编码映射到字库索引 uint8_t hz_index = GetHzIndex(*str, *(str+1)); if(hz_index != 0xFF) { OLED_ShowChinese(x, y, hz_index, 16); x += 16; // 汉字占16列宽 str += 2; // GBK汉字占2字节 } else { // 字库中未找到该汉字，跳过或显示问号 str += 2; } } else { // ASCII字符 OLED_ShowChar(x, y, *str, 16); // 显示16点阵ASCII x += 8; // ASCII字符通常占8列宽 str++; } // 简单换行处理（超出屏幕宽度则换行） if(x > 120) { x = 0; y += 16; } } }

这个函数的关键在于编码识别。在单片机中处理中文，常用GB2312/GBK编码。一个汉字由两个字节（且都大于0x7F）组成。你需要根据这两个字节去你的自定义字库中查找对应的点阵数据。GetHzIndex函数就需要你建立一个从GBK码到字库数组索引的映射表。

性能优化表格为了帮助你根据项目需求选择策略，这里有一个简单的对比：

在我的一个环境监测设备项目中，屏幕需要每秒更新一次温湿度数据。最初使用全屏刷新，在400kHz的I2C速率下能感觉到轻微的闪烁。后来改为局部刷新，只重写变化的数字区域，闪烁问题立刻消失，整体感觉流畅了许多。

5. 实战：构建一个完整的显示例程

现在，我们把所有模块组合起来，创建一个完整的示例。这个例子会在OLED上显示一个简单的界面，包括标题、动态更新的数值和单位。

主程序框架 (main.c)

#include "stm32f1xx_hal.h" #include "oled.h" #include "font.h" // 包含字库和ASCII字模 #include "sensor.h" // 假设的传感器读取头文件 // 定义要显示的汉字索引（根据你的字库顺序） #define HZ_WEN 0 #define HZ_DU 1 #define HZ_SHI 2 #define HZ_KONG 3 int main(void) { float temperature, humidity; char num_str[10]; HAL_Init(); SystemClock_Config(); OLED_Init(); // 显示静态标题 OLED_ShowChinese(0, 0, HZ_WEN, 16); OLED_ShowChinese(16, 0, HZ_DU, 16); OLED_ShowString(32, 0, ":", 16); OLED_ShowChinese(48, 0, HZ_SHI, 16); OLED_ShowChinese(64, 0, HZ_DU, 16); OLED_ShowString(80, 0, ":", 16); while (1) { // 读取传感器数据（示例） temperature = Read_Temperature(); humidity = Read_Humidity(); // 在指定位置显示温度值 sprintf(num_str, "%.1f", temperature); OLED_ShowString(32, 2, num_str, 16); OLED_ShowString(32+strlen(num_str)*8, 2, " C", 16); // 注意单位符号位置计算 // 在指定位置显示湿度值 sprintf(num_str, "%.1f", humidity); OLED_ShowString(80, 2, num_str, 16); OLED_ShowString(80+strlen(num_str)*8, 2, " %", 16); // 局部刷新：只刷新数值所在的区域，避免全屏闪烁 // 假设数值显示在第2行（页1和页2），从第32列到第127列 OLED_Refresh_Partial(1, 32, 127); OLED_Refresh_Partial(2, 32, 127); HAL_Delay(1000); // 每秒更新一次 } }

工程结构与关键文件说明一个组织良好的项目结构能让后续维护和功能扩展更容易。建议按如下方式组织：

Your_Project/ ├── Core/ │ ├── Inc/ │ │ ├── oled.h │ │ ├── font.h │ │ └── ... │ ├── Src/ │ │ ├── oled.c │ │ ├── font.c │ │ └── ... │ └── main.c ├── Drivers/ └── ...

• oled.h/c：包含所有OLED底层驱动函数，如I2C时序、初始化、画点、画线、刷新等。
• font.h/c：存放所有字模数据（ASCII和汉字）以及字符/汉字显示函数。可以将不同大小的字体用条件编译分开管理。
• main.c：应用层逻辑，调用显示函数组织界面。

在调试时，如果屏幕显示乱码或全白，可以按以下步骤排查：

1. 检查硬件连接：用万用表测量VCC和GND，确认SCL和SDA线没有接反或虚焊。
2. 验证I2C时序：用逻辑分析仪或示波器抓取SCL和SDA波形，看起始、停止、应答信号是否正常，时钟频率是否在SSD1306允许范围内（通常最高400kHz）。
3. 确认初始化序列：特别是电荷泵命令0x8D, 0x14是否发送。
4. 核对取模方式：这是汉字显示失败的最常见原因。务必确保取模软件的设置（扫描方式、字节顺序）与OLED_ShowChinese函数中的数据处理逻辑完全一致。一个简单的测试方法是先显示一个英文字母或数字，如果正常，则硬件和基础驱动是好的，问题大概率出在字模数据或显示算法上。
5. 检查坐标计算：确保显示的起始坐标(x, y)没有超出屏幕范围（128x64）。

最后，分享一个我遇到的真实问题：在一次使用24x24字体时，显示总是错位。后来发现是OLED_ShowChinese函数中，对于不同字体大小，计算每列所需处理的字节数和y坐标复位逻辑有误。对于24x24字体，每列需要3个字节（24行），代码中需要循环3次来处理一列，并且y坐标的复位和换行逻辑也要相应调整。所以，当你扩展支持多种字体大小时，一定要仔细核对这部分算法。