单片机与物联网 / 系统课时

驱动 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 初始化。

ESP32 与 SSD1306 OLED 的 I2C 接线

初始化并显示内容

示例使用 Adafruit_GFX 和 Adafruit_SSD1306 库。先确保这两个库已经安装,然后把下面程序烧录到 ESP32。程序会显示标题、一个数值、一条分隔线和一个矩形,同时在串口输出初始化状态。

cpp
#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() {
}

预期输出

text
OLED ready

OLED 上应出现 ESP32 OLED、Value:42,下方还能看到一条横线和一个空心矩形。实际字体位置会随字号和屏幕型号略有差异。

clearDisplay() 只清空内存缓冲区,真正把新画面发送到屏幕要调用 display()。因此动态刷新时通常按“清缓冲区 → 绘制 → display()”的顺序执行。

排查黑屏与初始化失败

如果串口停在 OLED initialization failed,优先检查 I2C 地址、SDA/SCL 引脚和供电。地址不确定时,可使用 I2C 扫描程序确认设备是否能被总线发现,而不是反复修改显示代码。

如果初始化成功但屏幕仍然没有内容,重点确认是否调用了 display.display(),以及文本颜色是否为 SSD1306_WHITE。出现局部错位或画面裁剪时,应核对模块分辨率是否真的是 128×64。

完成以上步骤后,你已经具备用 ESP32 把传感器数值、连接状态和简单图形输出到 OLED 的完整基础。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

驱动 OLED 屏幕

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通