ESP32开发- OLED显示“你好世界”——U8g2库完整教程

引言

在嵌入式开发中，显示屏是人机交互的重要桥梁。今天给大家分享如何使用ESP32驱动SSD1306 OLED显示屏，并用U8g2库优雅地显示中文"你好世界"。这篇文章从硬件连接到代码实现，手把手带你入门OLED显示开发。

最终效果

显示屏上会同时显示：

中文 "你好世界"（使用中文字体）
英文 "Hello World"

硬件准备

组件	型号/规格	数量
开发板	ESP32（NodeMCU-32S等）	1
OLED显示屏	SSD1306（128x64或128x32）	1
杜邦线	母对母	4根
USB线	Micro USB	1

💡 小贴士：市面上常见的0.96寸OLED多为SSD1306驱动，分辨率为128x64。

硬件连接

OLED模块通常采用I2C接口，只需连接4根线：

OLED引脚	ESP32引脚
VCC	3.3V
GND	GND
SDA	GPIO21
SCL	GPIO22

连接示意图

⚠️ 注意事项：

OLED模块通常支持3.3V供电，请勿连接到5V

I2C总线需要上拉电阻（大多数模块已集成）

部分OLED的I2C地址为0x3D，默认为0x3C

环境配置

1. 安装ESP32开发板支持

在Arduino IDE中：

文件 -> 首选项 -> 附加开发板管理器网址

添加：

复制代码

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

工具 -> 开发板 -> 开发板管理器
搜索ESP32并安装

2. 安装U8g2库

U8g2是目前最强大的OLED图形库之一，支持中文字体显示。

安装方法：

方法一：项目 -> 加载库 -> 管理库 -> 搜索U8g2 -> 安装
方法二：GitHub下载：https://github.com/olikraus/u8g2

完整代码

cpp 复制代码

#include <Wire.h>
#include <U8g2lib.h>

// 初始化OLED（I2C地址0x3C，128x64分辨率）
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* reset=*/ U8X8_PIN_NONE);

void setup() 
{
  u8g2.begin();                    // 初始化显示屏
  u8g2.enableUTF8Print();          // 启用UTF-8支持（显示中文必需）
  
  u8g2.setFont(u8g2_font_wqy12_t_chinese3);  // 设置文泉驿中文字体(12x12)
  u8g2.setFontDirection(0);        // 设置文字方向（0=正常）
  
  // 绘制屏幕内容
  u8g2.firstPage();
  do {
    u8g2.setCursor(0, 20);         // 设置光标位置(x=0, y=20)
    u8g2.print("你好世界");         // 显示中文
    
    u8g2.setCursor(0, 45);         // 设置光标位置(x=0, y=45)
    u8g2.print("Hello World");     // 显示英文
  } while (u8g2.nextPage());
}

void loop() 
{
  // 内容静态显示，无需更新
}

代码解析

1. U8g2对象初始化

cpp 复制代码

U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* reset=*/ U8X8_PIN_NONE);

这个构造函数包含几个重要参数：

U8G2_SSD1306_128X64_NONAME_F_HW_I2C：指定OLED型号和通信方式
- SSD1306：驱动芯片型号
- 128X64：屏幕分辨率
- F：全缓冲区模式（占用更多内存但速度更快）
- HW_I2C：使用硬件I2C
U8G2_R0：屏幕旋转角度（R0=不旋转，R2=旋转180°）
reset：复位引脚（使用U8X8_PIN_NONE表示不用）

2. 初始化设置

cpp 复制代码

u8g2.begin();              // 必须调用，初始化显示屏
u8g2.enableUTF8Print();    // 启用UTF-8编码支持（中文必备）

3. 字体设置

cpp 复制代码

u8g2.setFont(u8g2_font_wqy12_t_chinese3);

wqy12_t_chinese3是文泉驿12x12中文字体，支持常用汉字。

4. 绘制循环

cpp 复制代码

u8g2.firstPage();
do {
  // 在此放置所有绘制命令
} while (u8g2.nextPage());

这是U8g2的标准绘制模式：

firstPage()：准备第一页
nextPage()：切换到下一页，返回false时表示绘制完成

5. 输出文字

cpp 复制代码

u8g2.setCursor(x, y);  // 设置起始坐标（左上角为原点，y向下为正）
u8g2.print("文字");     // 输出文字

常用中文字体

字体名称	大小	说明
`u8g2_font_wqy12_t_chinese3`	12x12	推荐，内存占用适中最常用
`u8g2_font_wqy13_t_chinese3`	13x13	稍大，可读性更好
`u8g2_font_wqy14_t_chinese3`	14x14	清晰美观
`u8g2_font_wqy15_t_chinese3`	15x15	适合大字标题
`u8g2_font_wqy16_t_chinese3`	16x16	最大，内存占用较多

不同分辨率OLED的初始化

128x64分辨率

cpp 复制代码

U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

128x32分辨率

cpp 复制代码

U8G2_SSD1306_128X32_UNIVISION_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

I2C地址为0x3D时

cpp 复制代码

// 需要在begin之前设置地址
u8g2.setI2CAddress(0x3D * 2);  // U8g2内部使用8位地址，需要左移1位
u8g2.begin();

进阶示例：动态显示

cpp 复制代码

int counter = 0;

void loop() {
  u8g2.firstPage();
  do {
    u8g2.setFont(u8g2_font_wqy12_t_chinese3);
    u8g2.setCursor(0, 20);
    u8g2.print("计数: ");
    u8g2.print(counter);
    
    u8g2.setCursor(0, 45);
    u8g2.print("Hello World");
  } while (u8g2.nextPage());
  
  counter++;
  delay(1000);
}

常见问题

Q1: 屏幕不亮或全白？

检查电源连接（VCC接3.3V，GND接GND）
检查I2C接线（SDA/SCL是否接反）
尝试调整屏幕亮度对比度（部分模块需要）

Q2: 中文显示乱码或方框？

原因：未使用中文字体或文件编码不是UTF-8
解决：
1. 使用setFont()设置中文字体
2. 在Arduino IDE中：工具 -> 编码 -> 选择UTF-8
3. 调用enableUTF8Print()

Q3: 编译提示字体不存在？

更新U8g2库到最新版本
文泉驿字体从U8g2 2.27.0版本开始支持

Q4: 内存不足编译失败？

使用F模式改为1或2模式（减少缓冲区）

cpp 复制代码

// 改为分页模式，减少内存占用
U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

Q5: 显示闪烁？

在loop()中不要反复调用begin()和enableUTF8Print()
减少每次刷新时重绘的内容

总结

本文介绍了ESP32驱动SSD1306 OLED显示屏显示中文的方法：

✅ 硬件连接（I2C接口4根线）

✅ U8g2库的安装和配置

✅ 中文字体选择和设置

✅ 完整的"你好世界"代码

✅ 常见问题的解决方案

U8g2库功能非常强大，除了显示文字，还支持绘制图形、位图、多种字体等。后续我会继续分享如何使用OLED显示传感器数据、制作简单的动画效果等实战内容。

项目源码：评论区留言获取完整工程文件

📌 如果觉得有用，欢迎点赞+收藏+关注，你的支持是我分享的最大动力！