GxEPD2库设置

GxEPD2库设置

概述

本节介绍 GxEPD2 库的安装和配置，这是 ESP32 上最流行的电子纸显示驱动库。完成本节后，你将能够：

• 在 PlatformIO 和 Arduino IDE 中安装 GxEPD2 库
• 为你的电子纸型号选择正确的显示构造函数
• 在草图中初始化显示屏
• 验证库是否正常工作

前置条件

开始本节前，请确保：

• 电子纸显示屏已正确接线（参见 02-02）
• 已安装 PlatformIO IDE 或 Arduino IDE
• 已配置 ESP32 开发板支持
• 已完成第 1 章（基础草图结构）

关键概念

GxEPD2 库概览

GxEPD2 是适用于 ESP32 和其他兼容 Arduino 的开发板的电子纸显示库，构建在 AdaFruit GFX 图形库之上。它支持来自 Waveshare、GoodDisplay 和其他制造商的多种电子纸显示屏。

主要功能：

• 支持 40+ 种电子纸显示屏型号
• 基于 AdaFruit GFX，提供一致的绘图 API
• 支持黑白和三色显示屏
• 局部刷新能力（选定型号）
• 可配置的 SPI 引脚

库架构

GxEPD2 库
├── GxEPD2 核心类（显示初始化与控制）
├── 特定显示构造函数（40+ 型号）
├── AdaFruit GFX 依赖（文本、形状、位图）
├── SPI 总线管理
└── 局部刷新支持

显示类和构造函数

每种电子纸显示屏型号都有一个特定的构造函数类。命名约定遵循显示驱动 IC：

GxEPD2_<驱动IC>(CS, DC, RST, BUSY)

常见示例：

显示屏	驱动 IC	构造函数
Waveshare 1.54” 黑白	SSD1608	GxEPD2_154_D67(CS, DC, RST, BUSY)
Waveshare 2.13” 黑白	SSD1680	GxEPD2_213_B72(CS, DC, RST, BUSY)
Waveshare 2.13” 黑白红	SSD1680	GxEPD2_213_Z19c(CS, DC, RST, BUSY)
Waveshare 2.9” 黑白	SSD1680	GxEPD2_290_T5(CS, DC, RST, BUSY)
Waveshare 4.2” 黑白	SSD1683	GxEPD2_420(CS, DC, RST, BUSY)
Waveshare 7.5” 黑白	SSD1680	GxEPD2_750_T7(CS, DC, RST, BUSY)

实现步骤

步骤 1：安装依赖项

PlatformIO 环境：

将以下内容添加到 platformio.ini：

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

lib_deps =
    zingjjm/GxEPD2@^1.5.4
    adafruit/Adafruit GFX Library@^1.11.5

然后运行：

pio pkg install

Arduino IDE 环境：

1. 打开 项目 → 加载库 → 管理库
2. 搜索 GxEPD2 by Jean-Marc Zingg
3. 点击 安装
4. 搜索 Adafruit GFX Library
5. 点击 安装

步骤 2：识别显示屏构造函数

找到显示屏的正确构造函数：

// 包含库
#include <GxEPD2_BW.h>      // 黑白显示屏
// 或
#include <GxEPD2_3C.h>      // 三色显示屏（黑白/红 或 黑白/黄）

// 定义 SPI 引脚
#define EPD_CS    5
#define EPD_DC    17
#define EPD_RST   16
#define EPD_BUSY  4

// 选择显示构造函数
// 示例：Waveshare 2.13" 黑白（SSD1680 驱动）
GxEPD2_BW<GxEPD2_213_B72, GxEPD2_213_B72::HEIGHT> display(
    GxEPD2_213_B72(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY)
);

如何找到你的构造函数：

1. 查看显示屏产品页面上的驱动 IC 信息
2. 查看 GxEPD2_Example（文件 → 示例 → GxEPD2）
3. 使用与显示屏尺寸和颜色匹配的构造函数

步骤 3：初始化显示屏

#include <GxEPD2_BW.h>
#include <GxEPD2_3C.h>

// 引脚定义
#define EPD_CS    5
#define EPD_DC    17
#define EPD_RST   16
#define EPD_BUSY  4

// 2.13" 黑白显示屏构造函数
GxEPD2_BW<GxEPD2_213_B72, GxEPD2_213_B72::HEIGHT> display(
    GxEPD2_213_B72(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY)
);

void setup() {
    Serial.begin(115200);
    Serial.println("GxEPD2 初始化测试");

    // 初始化显示屏
    display.init(115200); // SPI 速度用于调试输出

    // 设置旋转（0-3）
    display.setRotation(1);

    // 清除显示屏为白色
    display.fillScreen(GxEPD_WHITE);
    display.display();

    Serial.println("显示屏初始化成功！");

    // 显示一些文本
    display.setCursor(10, 10);
    display.setTextColor(GxEPD_BLACK);
    display.print("你好，电子墨水屏！");
    display.display();
}

void loop() {
    // 此处无需操作
}

步骤 4：理解 init() 参数

display.init(baud_rate, initial, reset, pwr_enable);

参数	类型	默认值	描述
baud_rate	uint32_t	必需	SPI 速度（通常 115200 或 4000000）
initial	bool	true	完整初始化序列
reset	bool	true	初始化前硬件复位
pwr_enable	bool	false	为某些显示屏启用电源

建议：初始测试始终使用 display.init(115200)。

步骤 5：完整测试草图

#include <GxEPD2_BW.h>

// 引脚定义
#define EPD_CS    5
#define EPD_DC    17
#define EPD_RST   16
#define EPD_BUSY  4

// 2.13" 黑白显示屏构造函数
GxEPD2_BW<GxEPD2_213_B72, GxEPD2_213_B72::HEIGHT> display(
    GxEPD2_213_B72(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY)
);

void setup() {
    Serial.begin(115200);
    delay(1000);

    Serial.println("测试 GxEPD2 库...");

    // 初始化
    display.init(115200);
    display.setRotation(0);

    // 绘制形状
    display.fillScreen(GxEPD_WHITE);

    display.fillRect(10, 10, 50, 30, GxEPD_BLACK);

    display.drawCircle(100, 60, 20, GxEPD_BLACK);

    display.setCursor(10, 100);
    display.setTextColor(GxEPD_BLACK);
    display.print("GxEPD2 就绪！");

    // 更新显示屏
    display.display();

    Serial.println("测试完成！");
}

void loop() {}

验证

上传测试草图上后，你应该看到：

• 显示屏清除为白色
• 左上角出现黑色矩形
• 中心区域出现圆形
• 底部显示文本 “GxEPD2 就绪！”

如果缺少任何元素，请查看下面的故障排查部分。

串行监视器输出：

测试 GxEPD2 库...
显示屏初始化成功！
测试完成！

故障排查

问题 1：编译错误——“Display class not found”

症状：

error: 'GxEPD2_213_B72' does not name a type

解决方案：

• 检查库文档中的显示构造函数名称
• 验证是否包含正确的头文件（GxEPD2_BW.h 或 GxEPD2_3C.h）
• 尝试将库更新到最新版本

问题 2：显示屏显示随机像素

症状：

• 屏幕显示随机点或线条
• 文本显示乱码

可能原因：

• 选择了错误的构造函数
• SPI 速度太高
• 电源不稳定

解决方案：

// 尝试降低 init() 中的 SPI 速度
display.init(400000);  // 降低速度以提高稳定性

• 仔细检查构造函数是否与你的确切显示屏型号匹配
• 在 VCC 和 GND 之间添加 10µF 电容

问题 3：上传后显示屏保持白色

症状：

• 屏幕保持白色
• 无可见输出

解决方案：

1. 验证所有接线连接
2. 检查是否在绘图后调用了 display.display()
3. 确保 BUSY 引脚已连接并正确配置
4. 使用不同的构造函数测试（检查显示屏变体）

最佳实践

• ✅ 绘图后始终调用 display.display()——没有这个，屏幕上不会显示任何内容
• ✅ 开发期间使用带串行调试的 display.init()（115200 波特率）
• ✅ 在绘图前设置旋转——中途更改旋转会导致布局混乱
• ❌ 每分钟不要更新显示屏超过一次——过多更新会损耗显示屏
• ❌ 避免在三色显示屏上使用局部刷新——可能导致图像残影

总结

1. GxEPD2 是 ESP32 的标准电子纸驱动库，基于 AdaFruit GFX 构建
2. 每种显示屏型号需要一个特定的构造函数——在库示例中检查正确的构造函数
3. 初始化顺序：安装库 → 选择构造函数 → 初始化 → 绘图 → display()
4. 始终调用 display.display() 将缓冲区内容推到屏幕上
5. 保持低刷新频率以延长显示屏寿命并降低功耗

参考

• GxEPD2 GitHub 仓库
• Adafruit GFX 图形库
• Waveshare 电子纸库比较