如何快速上手GxEPD2：Arduino SPI电子纸显示库的完整指南

【免费下载链接】GxEPD2 Arduino Display Library for SPI E-Paper Displays 项目地址: https://gitcode.com/gh_mirrors/gx/GxEPD2

GxEPD2是一款强大的Arduino SPI电子纸显示库，支持来自大连佳显（Good Display）和 Waveshare 的SPI电子纸显示屏，提供完整的图形和文本支持，完美兼容Adafruit_GFX库。无论是单色、三色还是七色彩屏，GxEPD2都能轻松驱动，帮助开发者快速实现低功耗、高对比度的显示应用。

📌 核心功能与优势

GxEPD2库凭借其丰富的特性，成为电子纸显示开发的理想选择：

• 全面的硬件支持：兼容40余款不同尺寸（1.02英寸至13.3英寸）和类型（单色/三色/七色）的电子纸面板，包括热门型号如1.54英寸GDEY0154D67、2.9英寸GDEY029T94和7.5英寸GDEY075T7。

• 高效图形渲染：基于Adafruit_GFX库实现文本和图形绘制，支持多种字体、几何图形及位图显示，轻松实现复杂界面设计。

• 灵活的刷新模式：提供分页绘制（Paged Drawing）和全屏缓冲两种模式，平衡内存占用与刷新速度，部分面板还支持快速局部刷新（Differential Refresh）。

• 跨平台兼容性：支持Arduino Uno、ESP8266、ESP32、Raspberry Pi Pico等主流开发板，满足不同项目的硬件需求。

GxEPD2驱动的彩色电子纸显示效果示例，图片来源：项目内置位图资源

📂 项目结构解析

GxEPD2库的目录结构清晰，便于开发者快速定位所需资源：

GxEPD2/
├── src/                 # 核心源代码
│   ├── epd/             # 单色屏驱动（如GxEPD2_290.cpp）
│   ├── epd3c/           # 三色屏驱动（如GxEPD2_290c.cpp）
│   ├── epd4c/           # 四色屏驱动（如GxEPD2_290c_GDEY029F51H.cpp）
│   ├── epd7c/           # 七色屏驱动（如GxEPD2_565c.cpp）
│   └── bitmaps/         # 内置位图资源（如Bitmaps200x200.h）
├── examples/            # 示例程序
│   ├── GxEPD2_HelloWorld/      # 基础显示示例
│   ├── GxEPD2_SD_Example/      # SD卡位图显示
│   └── GxEPD2_WiFi_Example/    # 网络图片下载显示
└── extras/              # 额外资源
    └── bitmaps/         # 示例位图文件（如tiger.bmp、woof.bmp）

🔑 关键文件说明

• src/GxEPD2.h：库的主头文件，整合核心类和方法定义。
• src/epd/GxEPD2_EPD.cpp：电子纸显示基类，实现初始化、刷新等底层操作。
• examples/GxEPD2_GFX_Example/：展示图形绘制功能，包括文本、几何图形和自定义位图。
• extras/bitmaps/：包含多种分辨率的示例位图，如tiger_240x317x4.bmp（240x317像素四色老虎图像），可直接用于测试显示效果。

🚀 快速开始：Hello World示例

以下是使用GxEPD2库驱动1.54英寸电子纸屏的极简示例，只需三步即可实现文字显示：

1️⃣ 硬件准备

• 电子纸模块：1.54英寸单色屏（如GDEY0154D67，200x200分辨率）
• 开发板：ESP32（推荐，内存充足）或Arduino Uno
• 连接线：按照examples/GxEPD2_HelloWorld/GxEPD2_wiring_examples.h中的引脚定义连接SPI线路（SCK、MOSI、CS、DC、RST、BUSY）

2️⃣ 库安装

1. 访问项目仓库：git clone https://gitcode.com/gh_mirrors/gx/GxEPD2
2. 将GxEPD2文件夹复制到Arduino libraries目录
3. 重启Arduino IDE，库将自动加载

3️⃣ 代码实现

#include <GxEPD2_BW.h>
// 初始化1.54英寸单色屏（根据实际型号修改）
GxEPD2_BW<GxEPD2_154_D67, GxEPD2_154_D67::HEIGHT> display(GxEPD2_154_D67(/*CS=5*/ SS, /*DC=2*/ 2, /*RST=4*/ 4, /*BUSY=15*/ 15));

void setup() {
  display.init(115200);  // 初始化显示屏，波特率115200
  display.setRotation(1); // 设置旋转角度（0-3）
  display.setTextColor(GxEPD_BLACK); // 设置文本颜色
  display.setTextSize(2); // 设置文本大小
  display.firstPage();
  do {
    display.fillScreen(GxEPD_WHITE); // 清屏为白色
    display.setCursor(10, 50); // 设置光标位置
    display.print("Hello, E-Paper!"); // 显示文本
  } while (display.nextPage()); // 分页绘制
  display.powerOff(); // 关闭电源，降低功耗
}

void loop() {
  // 电子纸无需持续刷新，此处为空
}

上传代码后，电子纸屏将显示"Hello, E-Paper!"，刷新完成后自动断电，功耗低至微安级。

GxEPD2驱动电子纸显示文本示例（图片为库内置位图，实际显示效果类似）

📊 高级应用示例

GxEPD2库提供丰富的示例程序，覆盖各类实用场景：

🖼️ 位图显示（SD卡/Flash）

通过GxEPD2_SD_Example可从SD卡加载位图文件，支持BMP格式。以下代码片段演示如何显示extras/bitmaps/woof.bmp（200x200像素）：

#include <SD.h>
#include <GxEPD2_BW.h>
GxEPD2_BW<GxEPD2_154_D67, GxEPD2_154_D67::HEIGHT> display(...);

void setup() {
  display.init();
  SD.begin(SS); // 初始化SD卡
  File bmpFile = SD.open("woof.bmp");
  display.drawBitmap(0, 0, bmpFile, 200, 200, GxEPD_BLACK); // 绘制位图
  display.display(); // 刷新屏幕
}

🌐 WiFi图片下载

GxEPD2_WiFi_Example展示了如何通过WiFi从网络下载图片并显示，支持HTTPS协议和证书验证，适用于实时数据显示（如天气、新闻）。

🌈 彩色显示

对于三色（黑/白/红）或七色屏，只需包含对应的头文件（如GxEPD2_3C.h或GxEPD2_7C.h），并使用drawPixel(color)指定颜色即可。例如驱动5.65英寸七色屏（GDEP0565D90）：

#include <GxEPD2_7C.h>
GxEPD2_7C<GxEPD2_565c, GxEPD2_565c::HEIGHT> display(...);
display.drawCircle(100, 100, 50, GxEPD_RED); // 绘制红色圆形

⚠️ 注意事项

1. 电压兼容性：电子纸模块均为3.3V供电，5V开发板需使用电平转换器（如TXB0108），避免直接连接导致烧毁。

2. 刷新次数：大多数电子纸的寿命约10万次刷新，设计时应避免不必要的频繁刷新。

3. 波形表优化：部分面板（如GDEY075T7）支持快速全屏刷新，可通过修改驱动类中的hasFastPartialUpdate属性调整。

4. 技术支持：若遇到硬件问题，可参考佳显官方文档或项目README中的"Supported SPI e-paper panels"章节。

📚 资源与学习

• 官方示例：examples/目录下包含15+个细分场景示例，从基础绘图到WiFi应用全覆盖。
• 位图资源：extras/bitmaps/提供多种测试图片，如tiger_320x200x24.bmp（彩色老虎）和liberato640x384.bmp（风景图），可直接用于SD卡或Flash示例。
• 社区讨论：访问Arduino Forum的电子纸专题获取最新技术分享。

GxEPD2驱动彩色电子纸显示8位灰度图像（示例位图：marilyn_240x240x8.bmp）

📝 总结

GxEPD2库以其强大的兼容性、丰富的功能和易用性，成为Arduino平台电子纸显示开发的首选工具。无论你是制作低功耗物联网设备、便携式仪表还是创意电子项目，GxEPD2都能帮助你快速实现高品质的显示效果。立即克隆项目，开启你的电子纸应用开发之旅吧！

👉 项目地址：git clone https://gitcode.com/gh_mirrors/gx/GxEPD2

提示：使用examples/GxEPD2_DisplaySelection工具可自动生成适配特定面板的初始化代码，大幅简化开发流程。

【免费下载链接】GxEPD2 Arduino Display Library for SPI E-Paper Displays 项目地址: https://gitcode.com/gh_mirrors/gx/GxEPD2