单片机与物联网 / 系统课时
驱动 OLED 屏幕
驱动 OLED 屏幕
本课用 ESP32 通过 I2C 驱动常见的 0.96 英寸 SSD1306 OLED,完成文本、数值和简单图形显示。你会先确认接线与地址,再运行一个完整示例,并知道黑屏、乱码或初始化失败时该从哪里排查。
学习目标
- 能把 SSD1306 OLED 正确连接到 ESP32 的 I2C 引脚,并理解地址与分辨率参数。
- 能初始化显示对象,输出文本、数值、直线和矩形。
- 能根据初始化结果、I2C 地址和供电情况定位常见显示故障。
接好 I2C 与确认参数
下面以常见 ESP32 DevKit 和 128×64、I2C 接口的 SSD1306 模块为例。很多开发板默认使用 GPIO 21 作为 SDA、GPIO 22 作为 SCL,但不同板型可能不同,实际项目应以开发板引脚定义为准。
| OLED 引脚 | ESP32 连接 | 作用 |
|---|---|---|
| VCC | 3.3V | 供电 |
| GND | GND | 共地 |
| SDA | GPIO 21 | I2C 数据线 |
| SCL | GPIO 22 | I2C 时钟线 |
常见 I2C 地址是 0x3C,少数模块使用 0x3D。分辨率也必须与屏幕一致,128×64 屏应使用 128 和 64 初始化。

初始化并显示内容
示例使用 Adafruit_GFX 和 Adafruit_SSD1306 库。先确保这两个库已经安装,然后把下面程序烧录到 ESP32。程序会显示标题、一个数值、一条分隔线和一个矩形,同时在串口输出初始化状态。
#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
constexpr int SCREEN_WIDTH = 128;
constexpr int SCREEN_HEIGHT = 64;
constexpr int OLED_RESET = -1;
constexpr uint8_t OLED_ADDRESS = 0x3C;
constexpr int SDA_PIN = 21;
constexpr int SCL_PIN = 22;
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(115200);
Wire.begin(SDA_PIN, SCL_PIN);
// 初始化失败通常与地址、接线或分辨率配置有关。
if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS)) {
Serial.println("OLED initialization failed");
while (true) {
delay(1000);
}
}
display.clearDisplay();
display.setTextColor(SSD1306_WHITE);
display.setTextSize(1);
display.setCursor(0, 0);
display.println("ESP32 OLED");
int sensorValue = 42;
display.setTextSize(2);
display.setCursor(0, 16);
display.print("Value:");
display.println(sensorValue);
// 简单图形可以用于分隔区域或绘制状态边框。
display.drawLine(0, 42, 127, 42, SSD1306_WHITE);
display.drawRect(0, 48, 50, 14, SSD1306_WHITE);
display.display();
Serial.println("OLED ready");
}
void loop() {
}预期输出
OLED readyOLED 上应出现 ESP32 OLED、Value:42,下方还能看到一条横线和一个空心矩形。实际字体位置会随字号和屏幕型号略有差异。
clearDisplay() 只清空内存缓冲区,真正把新画面发送到屏幕要调用 display()。因此动态刷新时通常按“清缓冲区 → 绘制 → display()”的顺序执行。
排查黑屏与初始化失败
如果串口停在 OLED initialization failed,优先检查 I2C 地址、SDA/SCL 引脚和供电。地址不确定时,可使用 I2C 扫描程序确认设备是否能被总线发现,而不是反复修改显示代码。
如果初始化成功但屏幕仍然没有内容,重点确认是否调用了 display.display(),以及文本颜色是否为 SSD1306_WHITE。出现局部错位或画面裁剪时,应核对模块分辨率是否真的是 128×64。
完成以上步骤后,你已经具备用 ESP32 把传感器数值、连接状态和简单图形输出到 OLED 的完整基础。