1.54英寸三色电子纸驱动全解析：从SPI连接到功耗优化实战

1. 项目概述：为什么选择1.54英寸电子纸？

如果你正在寻找一种超低功耗、阳光下清晰可读、并且能保持静态图像不耗电的显示方案，那么电子纸（e-Paper）几乎是唯一的选择。我最近在几个物联网数据看板和便携式标签项目中，深度使用了这款1.54英寸的三色电子纸模块（通常指黑、白、红三色，即G系列）。和常见的OLED或LCD屏不同，电子纸的刷新原理决定了它的使用方式非常独特——它不是用来播放视频的，而是用来“发布信息”的。

这块1.54英寸的屏幕，分辨率通常是200x200像素，尺寸小巧，非常适合需要间歇性更新显示内容、且对功耗极其敏感的场景。比如，温湿度监测站的户外显示屏、智能家居的中央状态面板、或者是一个离线式的待办事项清单。它的核心优势就在于“双稳态”特性：一旦图像被刷新到屏幕上，即使完全断电，图像也能持续显示数周甚至数月。这意味着你的设备大部分时间都可以处于深度睡眠状态，只在需要更新内容时才唤醒并消耗能量，对于电池供电的设备来说，这是革命性的。

然而，电子纸的驱动也比普通屏幕复杂一些。它需要专门的波形文件（LUT）来控制每个像素点从当前颜色切换到目标颜色的电压序列，这个过程就是“刷新”。刷新过程相对较慢（全刷可能需要2-3秒），并且有全局刷新和局部刷新之分，局部刷新速度快但可能带来残影。网上虽然有现成的库，但如果不理解底层逻辑，一旦遇到显示异常、刷新不全或者图片错位，调试起来会非常头疼。这篇内容，我就结合在Raspberry Pi、Arduino和ESP32这几个主流平台上的实测经验，带你从硬件连接到软件驱动，彻底搞懂这块1.54英寸电子纸，并分享几个实际项目中踩过的坑和优化技巧。

2. 硬件连接与核心驱动原理拆解

拿到模块，第一步肯定是正确接线。1.54英寸e-Paper模块的接口通常是SPI（串行外设接口），这是一切的基础。

2.1 引脚定义与SPI连接指南

虽然不同厂商的引脚顺序可能略有差异，但核心引脚万变不离其宗。我们以一个常见的1.54英寸 e-Paper (G) 模块为例，其引脚通常包括：

注意：务必确认你的模块电压是3.3V逻辑电平。连接像Arduino Uno（5V逻辑）这样的板子时，不能直接连接，必须使用逻辑电平转换器，或者选择像Arduino Nano 33 BLE、ESP32、Raspberry Pi（其GPIO为3.3V）这类原生3.3V逻辑的控制器。

连接示例（以ESP32为例）：

• e-Paper VCC -> ESP32 3.3V
• e-Paper GND -> ESP32 GND
• e-Paper DIN -> ESP32 GPIO 23 (通常作为VSPI的MOSI)
• e-Paper CLK -> ESP32 GPIO 18 (VSPI的SCK)
• e-Paper CS -> ESP32 GPIO 5 (可自定义，但需在代码中指定)
• e-Paper DC -> ESP32 GPIO 17 (可自定义)
• e-Paper RST -> ESP32 GPIO 16 (可自定义)
• e-Paper BUSY -> ESP32 GPIO 4 (可自定义)

2.2 驱动IC与波形文件（LUT）的核心作用

屏幕背后有一颗驱动芯片，常见的是IL3829、SSD1681或UC8151D等。这颗芯片并不直接“理解”你要显示什么图像，它只负责按照预设的“规则”去操纵屏幕上的每一个微胶囊（里面是黑白红带电粒子）。

这个“规则”就是波形查找表（Look-Up Table, LUT）。你可以把LUT想象成驱动芯片的“指令集”或“配方”。它定义了从当前像素状态（黑/白/红）切换到目标状态，需要施加怎样的电压序列（包括电压大小、极性、持续时间）。例如，从“白色”切换到“黑色”，和从“黑色”切换到“红色”，所需的电压波形是不同的。

为什么需要LUT？因为电子纸的刷新不是瞬时的，施加错误的电压或时序可能导致对比度下降、残影（鬼影）甚至屏幕损坏。厂商会根据屏幕的具体特性（如温度、批次）预烧录一个全局LUT。我们在代码中，通常通过发送一系列命令（如0x32）来将这个LUT数据写入驱动芯片。全刷和局部刷本质上就是使用了不同的LUT。全刷LUT的电压变化更彻底，能确保最干净的显示效果但速度慢；局部刷LUT则优化了速度，但长时间使用可能积累残影，需要定期进行一次全刷来清除。

理解这一点至关重要：当你发现局部刷新几次后屏幕变脏、有重影，这不是代码bug，而是物理特性。解决方案就是在你的应用逻辑中，计数局部刷新次数（比如每5次局部刷后，强制进行一次全刷）。

3. 在Raspberry Pi上驱动：从系统配置到图片显示

树莓派拥有完整的Linux操作系统，资源丰富，适合做复杂的图形处理或作为显示服务器。这里我们使用Python和waveshare_epd这个优秀的库来驱动。

3.1 系统准备与SPI接口启用

首先，确保你的Raspberry Pi OS是最新的，并通过raspi-config工具启用SPI接口。

sudo raspi-config

进入Interface Options->SPI->Yes启用它。重启后，可以通过命令检查SPI设备是否出现：

ls /dev/spi*

你应该能看到类似/dev/spidev0.0和/dev/spidev0.1的设备。

接下来安装必要的库。使用pip3进行安装：

sudo apt update sudo apt install python3-pip python3-pil python3-numpy sudo pip3 install waveshare-epd

PIL（Pillow）库用于处理图像，numpy用于数组操作，waveshare-epd是官方提供的驱动库。

3.2 基础显示与图像处理实战

安装好后，就可以开始写Python脚本了。首先是一个最简单的清屏和显示文本的例子：

import epaper from PIL import Image, ImageDraw, ImageFont import time # 初始化1.54英寸e-Paper对象，这里以waveshare的V2版本为例 epd = epaper.epaper('epd1in54b_V2').EPD() # 初始化屏幕 epd.init() epd.Clear() # 创建一个在内存中的图像缓冲区，模式为'1'（1位黑白），大小匹配屏幕 # 注意：对于三色屏，我们通常用‘1’模式创建黑白层，红色层另做处理。 # 但waveshare库的`getbuffer`方法会处理转换。更通用的方法是创建‘RGB’图像再转换。 height = epd.height # 200 width = epd.width # 200 image = Image.new('1', (width, height), 255) # 255为白色 draw = ImageDraw.Draw(image) # 加载字体（确保字体文件存在） font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 20) # 绘制文本 draw.text((10, 10), 'Hello e-Paper!', font=font, fill=0) # fill=0 代表黑色 draw.text((10, 40), 'Raspberry Pi', font=font, fill=0) # 显示图像 # 对于三色屏，需要黑白图像和红色图像两个缓冲区 # 我们先假设所有内容都是黑色（无红色部分） red_image = Image.new('1', (width, height), 255) # 红色层全白（即不显示红色） # 将PIL图像转换为库所需的缓冲区 black_buffer = epd.getbuffer(image) red_buffer = epd.getbuffer(red_image) # 显示 epd.display(black_buffer, red_buffer) # 休眠并关闭电源以省电 time.sleep(2) epd.sleep()

这段代码完成了从初始化、清屏、绘制到显示的全过程。关键点在于理解双缓冲：black_buffer控制黑白粒子，red_buffer控制红色粒子。在red_buffer里，0（黑色）表示要显示红色，1（白色）表示不显示红色。这是一个容易混淆的地方。

3.3 显示自定义图片与残影处理技巧

显示图片更实用。你需要将图片处理成200x200像素，并转换为黑白和红色两个图层。

from PIL import Image # 1. 打开并调整图片大小 original_image = Image.open('your_picture.jpg') resized_image = original_image.resize((epd.width, epd.height), Image.Resampling.LANCZOS) # 2. 转换为RGB模式确保颜色操作正常 rgb_image = resized_image.convert('RGB') pixels = rgb_image.load() # 3. 创建黑白和红色两个图层 black_layer = Image.new('1', (epd.width, epd.height), 255) red_layer = Image.new('1', (epd.width, epd.height), 255) black_draw = ImageDraw.Draw(black_layer) red_draw = ImageDraw.Draw(red_layer) # 4. 遍历每个像素，根据颜色分配到不同图层 # 这是一个简单的阈值法：偏红的像素归到红色层，否则按亮度归到黑/白层。 for y in range(epd.height): for x in range(epd.width): r, g, b = pixels[x, y] # 简单判断：如果红色分量突出且非纯黑/白，则视为红色 if r > 160 and g < 100 and b < 100: # 在红色层，将该点设为黑色（0），表示要显示红色 red_draw.point((x, y), fill=0) # 在黑白层，对应位置保持白色（255），避免重叠 black_draw.point((x, y), fill=255) else: # 非红色区域，转换为灰度，然后根据阈值决定黑白 luminance = 0.299 * r + 0.587 * g + 0.114 * b if luminance < 128: # 较暗，显示黑色 black_draw.point((x, y), fill=0) else: # 较亮，显示白色 black_draw.point((x, y), fill=255) # 红色层对应位置保持白色（不显示红） red_draw.point((x, y), fill=255) # 5. 显示 black_buffer = epd.getbuffer(black_layer) red_buffer = epd.getbuffer(red_layer) epd.display(black_buffer, red_buffer)

残影处理实战：当你快速更新部分内容（如只更新数字）时，使用局部刷新(epd.displayPartBaseImage等函数)。但正如前文所述，局部刷新有累积效应。我的经验是：

1. 定义刷新策略：在内存中维护一个“局部刷新计数器”。每次局部刷新后计数器+1。
2. 设置阈值：当计数器达到一个阈值（例如5次）时，下一次更新强制使用全局刷新(epd.display)，并将计数器清零。
3. 关键信息更新：对于需要绝对清晰度的关键信息更新（如整页内容更换），直接使用全局刷新，不要使用局部刷新。

这样可以很好地平衡刷新速度和显示质量。此外，确保在设备进入深度睡眠(epd.sleep)或断电前，屏幕已完成最后一次刷新（通过检查BUSY引脚或等待足够时间）。

4. 在Arduino平台上的驱动与优化

Arduino环境更贴近硬件，资源有限，适合对功耗和实时性要求更高的嵌入式场景。我们将使用GxEPD2库，这是一个功能强大且维护活跃的库。

4.1 库安装与硬件抽象层选择

在Arduino IDE中，通过库管理器搜索并安装“GxEPD2”。这个库支持多种屏幕和控制器。安装后，你需要根据你的具体模块型号和连接方式，包含正确的头文件。

你的模块很可能使用的是SSD1681或兼容的驱动IC。接线参考前面的ESP32示例（因为两者都是3.3V逻辑）。在代码中，你需要告诉库你使用的具体屏幕类、SPI引脚以及驱动IC类型。

// 对于1.54英寸三色屏，通常使用 GxEPD2_154_D67 或 GxEPD2_154_M09 等类 // 具体型号需查阅模块资料或GxEPD2库的示例 #include <GxEPD2_BW.h> // 我们使用BW库，但通过特殊方式支持三色 #include <GxEPD2_3C.h> // 实际上三色屏更常用3C这个头文件 #include <GxEPD2_7C.h> // 七色屏用这个 #include <Fonts/FreeMonoBold9pt7b.h> // 内置字体 // 定义连接引脚（以ESP32为例，如果用的是Arduino Nano 33 BLE，需调整引脚号） #define EPD_CS 5 #define EPD_DC 17 #define EPD_RST 16 #define EPD_BUSY 4 // 使用GxEPD2_3C类定义显示对象 // 参数：驱动IC型号、屏幕尺寸、CS, DC, RST, BUSY引脚 GxEPD2_3C<GxEPD2_154_M09, GxEPD2_154_M09::HEIGHT> display( GxEPD2_154_M09(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY) );

注意：GxEPD2_154_M09只是一个示例，你必须根据你的模块确切型号来选择。最准确的方法是查看卖家提供的资料，或者打开GxEPD2库的“GxEPD2_display_selection.h”头文件，里面列出了所有支持的屏幕型号及对应的驱动IC。选错会导致颜色反转、刷新异常甚至无显示。

4.2 基础图形绘制与文本显示

初始化后，绘制和显示就相对直观了。库提供了类似Arduino GFX标准的API。

void setup() { Serial.begin(115200); display.init(115200); // 初始化显示屏，可传入串口调试波特率 display.setRotation(1); // 设置旋转方向（0-3） display.setFullWindow(); // 设置全窗口刷新模式 display.firstPage(); // 开始多页渲染（对于复杂图形） do { display.fillScreen(GxEPD_WHITE); // 填充白色背景 display.setTextColor(GxEPD_BLACK); // 设置文本颜色为黑 display.setFont(&FreeMonoBold9pt7b); // 设置字体 display.setCursor(10, 30); // 设置光标位置 display.print("Hello, e-Paper!"); // 绘制一个矩形框 display.drawRect(50, 50, 100, 60, GxEPD_BLACK); // 填充一个红色矩形（注意：对于三色屏，红色是第三种颜色） display.fillRect(60, 60, 80, 40, GxEPD_RED); } while (display.nextPage()); // 结束渲染并刷新屏幕 display.hibernate(); // 进入休眠模式，省电 } void loop() { // 主循环为空，显示内容后进入低功耗状态 delay(60000); // 每分钟更新一次，模拟实际应用 updateDisplay(); }

这里的关键是display.nextPage()。对于内存有限的MCU，GxEPD2库使用了一种“分页渲染”的技术。在do...while循环中，你描述的是整个屏幕的内容，但库在后台可能分多次将数据发送到屏幕。这是一种内存优化的手段。

4.3 深度睡眠与功耗管理实战

对于电池供电的Arduino项目，功耗是生命线。电子纸本身不耗电，但你的微控制器（如ESP32）耗电。目标是让MCU在两次刷新之间尽可能深地睡眠。

ESP32深度睡眠结合电子纸刷新的典型流程：

1. 上电/唤醒：ESP32从深度睡眠中唤醒（可以是定时器唤醒、外部引脚触发等）。
2. 初始化与连接：初始化显示模块，从传感器读取数据，或从网络获取信息。
3. 准备与刷新显示：在内存中准备好要显示的图像，调用display.display()或分页渲染进行刷新。务必等待刷新完成（可以通过display.waitWhileBusy()函数，或者读取BUSY引脚状态）。
4. 让屏幕休眠：调用display.hibernate()。这个命令会发送指令让电子纸驱动芯片进入最低功耗状态，此时可以安全断开电源。
5. MCU进入深度睡眠：配置ESP32的唤醒源（如定时器），然后调用esp_deep_sleep_start()。此时整个系统电流可以降到10微安级别。

一个常见的坑是：在屏幕刷新完成前就进入睡眠。这会导致刷新过程中断，屏幕显示乱码或半幅图像。务必加入等待机制：

void updateDisplayAndSleep() { // ... 准备显示内容 ... display.display(false); // false表示不使用局部刷新（即全刷） display.waitWhileBusy(); // **关键：等待刷新完成** display.hibernate(); // 屏幕进入休眠 // 现在可以安全地让MCU睡觉了 Serial.println("准备进入深度睡眠"); esp_sleep_enable_timer_wakeup(60 * 1000000); // 60秒后唤醒 esp_deep_sleep_start(); }

此外，如果使用局部刷新，在进入长时间睡眠或关机前，最好执行一次全局刷新，以确保图像稳定，避免残影在长期显示中变得明显。

5. 在STM32环境下的移植与底层驱动剖析

在STM32这类没有Arduino抽象层的纯嵌入式环境中驱动电子纸，能让你更深入地理解其通信协议。我们通常使用HAL库或标准外设库，直接操作SPI和GPIO。

5.1 SPI与GPIO的底层配置

首先，使用STM32CubeMX工具配置硬件：

1. 启用一个SPI外设（如SPI1），模式为Full-Duplex Master，数据大小8 Bits，时钟极性（CPOL）和相位（CPHA）通常设置为Low和1 Edge（即Mode 0）。具体需参考电子纸数据手册，但Mode 0或Mode 3是常见的。
2. 将SPI的MOSI、SCK引脚以及自定义的CS、DC、RST、BUSY引脚配置为GPIO Output（除了BUSY是Input）。
3. 生成代码。

在代码中，我们需要手动实现片选(CS)、数据/命令(DC)的控制，以及通过SPI发送数据的函数。

// 引脚定义 #define EPD_CS_PIN GPIO_PIN_4 #define EPD_CS_PORT GPIOA #define EPD_DC_PIN GPIO_PIN_5 #define EPD_DC_PORT GPIOA #define EPD_RST_PIN GPIO_PIN_6 #define EPD_RST_PORT GPIOA #define EPD_BUSY_PIN GPIO_PIN_7 #define EPD_BUSY_PORT GPIOA // 控制函数 void EPD_CS_Low(void) { HAL_GPIO_WritePin(EPD_CS_PORT, EPD_CS_PIN, GPIO_PIN_RESET); } void EPD_CS_High(void) { HAL_GPIO_WritePin(EPD_CS_PORT, EPD_CS_PIN, GPIO_PIN_SET); } void EPD_DC_Data(void) { HAL_GPIO_WritePin(EPD_DC_PORT, EPD_DC_PIN, GPIO_PIN_SET); } void EPD_DC_Cmd(void) { HAL_GPIO_WritePin(EPD_DC_PORT, EPD_DC_PIN, GPIO_PIN_RESET); } void EPD_RST_Low(void) { HAL_GPIO_WritePin(EPD_RST_PORT, EPD_RST_PIN, GPIO_PIN_RESET); } void EPD_RST_High(void) { HAL_GPIO_WritePin(EPD_RST_PORT, EPD_RST_PIN, GPIO_PIN_SET); } uint8_t EPD_Busy_Read(void) { return HAL_GPIO_ReadPin(EPD_BUSY_PORT, EPD_BUSY_PIN); } // SPI发送单字节函数 void EPD_SendByte(uint8_t data) { HAL_SPI_Transmit(&hspi1, &data, 1, HAL_MAX_DELAY); } // 发送命令函数 void EPD_SendCommand(uint8_t command) { EPD_DC_Cmd(); // DC置低，表示发送的是命令 EPD_CS_Low(); EPD_SendByte(command); EPD_CS_High(); } // 发送数据函数 void EPD_SendData(uint8_t data) { EPD_DC_Data(); // DC置高，表示发送的是数据 EPD_CS_Low(); EPD_SendByte(data); EPD_CS_High(); }

5.2 驱动序列与显存管理

电子纸的初始化、刷新都需要遵循严格的命令序列。这些序列通常在厂商的数据手册或参考代码中提供。一个简化的初始化序列可能如下：

void EPD_Init(void) { // 1. 硬件复位 EPD_RST_Low(); HAL_Delay(10); // 延时至少10ms EPD_RST_High(); HAL_Delay(10); // 2. 等待BUSY变低（如果模块支持） while(EPD_Busy_Read() == 1) { HAL_Delay(1); } // 3. 发送一系列初始化命令 EPD_SendCommand(0x12); // 软复位 EPD_WaitBusy(); EPD_SendCommand(0x01); // 驱动器输出控制 EPD_SendData(0xC7); EPD_SendData(0x00); EPD_SendData(0x00); // ... 更多设置命令，如设置LUT、边框控制等 ... EPD_SendCommand(0x32); // 写LUT寄存器 for(int i=0; i<153; i++) { EPD_SendData(lut_full_update[i]); // 发送全刷LUT数据 } EPD_SendCommand(0x11); // 数据输入模式 EPD_SendData(0x03); // 使用RAM EPD_SendCommand(0x44); // 设置RAM X地址起止 EPD_SendData(0x00); EPD_SendData(0x18); // (200+7)/8 = 25.875 -> 0x18 EPD_SendCommand(0x45); // 设置RAM Y地址起止 EPD_SendData(0xC7); // 199 = 0xC7 EPD_SendData(0x00); EPD_SendData(0x00); EPD_SendData(0x00); EPD_SendCommand(0x4E); // 设置RAM X地址计数器 EPD_SendData(0x00); EPD_SendCommand(0x4F); // 设置RAM Y地址计数器 EPD_SendData(0xC7); EPD_SendData(0x00); }

显存管理是另一个重点。屏幕的200x200像素，对于单色（1位深度）来说，需要200 * 200 / 8 = 5000字节的显存。对于三色屏，通常需要两个这样的缓冲区：一个给黑白色（Black/White），一个给红色（Red）。在STM32上，这1KB的缓冲区可能占据不少RAM（尤其是对于RAM较小的型号如STM32F103）。你需要将其定义在全局数组或通过malloc分配。

#define EPD_WIDTH 200 #define EPD_HEIGHT 200 #define EPD_BUFFER_SIZE (EPD_WIDTH * EPD_HEIGHT / 8) uint8_t epd_black_buffer[EPD_BUFFER_SIZE]; uint8_t epd_red_buffer[EPD_BUFFER_SIZE]; // 清空缓冲区（全白） void EPD_ClearBuffer(void) { memset(epd_black_buffer, 0xFF, EPD_BUFFER_SIZE); // 0xFF = 所有位为1，白色 memset(epd_red_buffer, 0xFF, EPD_BUFFER_SIZE); // 红色层全白表示不显示红色 }

将图像数据写入缓冲区后，需要通过EPD_SendCommand(0x24)和EPD_SendCommand(0x26)等命令，分别将黑白和红色缓冲区的数据发送到驱动芯片的指定RAM区域，最后发送刷新命令（如0x22和0x20）来启动屏幕刷新。

5.3 性能优化与DMA传输应用

在STM32上，通过SPI发送5000字节的数据（对于单色）可能需要几十毫秒，这期间CPU被完全占用。为了解放CPU，可以使用DMA（直接存储器访问）来传输数据。

使用HAL库的DMA传输优化：

1. 配置SPI的DMA请求：在CubeMX中，为SPI的TX流启用DMA。
2. 修改发送函数：将EPD_SendData函数用于发送命令和少量数据，对于大批量显存数据，使用DMA传输。

void EPD_WriteBuffer_DMA(uint8_t *buffer, uint32_t size) { EPD_DC_Data(); // 设置为数据模式 EPD_CS_Low(); // 使用HAL_SPI_Transmit_DMA，此函数立即返回，传输在后台进行 HAL_SPI_Transmit_DMA(&hspi1, buffer, size); // 注意：此时不能立即拉高CS，需要等待DMA传输完成 } // 在DMA传输完成中断回调函数中拉高CS void HAL_SPI_TxCpltCallback(SPI_HandleTypeDef *hspi) { if(hspi->Instance == SPI1) { EPD_CS_High(); // 传输完成，释放片选 } }

使用DMA后，CPU在数据传输期间可以去处理其他任务（如准备下一帧数据、处理传感器读数），显著提高了系统效率。但需要注意同步：必须在DMA传输完成后，才能进行下一步操作（如发送刷新命令），否则数据可能不完整。这就需要利用DMA传输完成中断或查询标志位。

6. 在ESP32上使用Arduino框架与IDF的混合实践

ESP32因其强大的无线功能和双核处理能力，成为物联网显示终端的绝佳选择。我们既可以使用熟悉的Arduino框架快速原型开发，也可以深入ESP-IDF以获得更精细的控制。

6.1 基于Arduino框架的快速实现

在Arduino框架下，驱动电子纸与在普通Arduino上类似，但ESP32的引脚定义更灵活。我们同样使用GxEPD2库。

#include <GxEPD2_BW.h> #include <GxEPD2_3C.h> #include <WiFi.h> #include <HTTPClient.h> #include <ArduinoJson.h> // 定义引脚（可根据你的板子调整） #define EPD_CS 15 #define EPD_DC 27 #define EPD_RST 26 #define EPD_BUSY 25 GxEPD2_3C<GxEPD2_154_M09, GxEPD2_154_M09::HEIGHT> display( GxEPD2_154_M09(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY) ); void setup() { Serial.begin(115200); display.init(115200); connectToWiFi(); displayWeather(); display.hibernate(); // 可以在这里让ESP32进入深度睡眠 // esp_sleep_enable_timer_wakeup(300 * 1000000); // 5分钟后唤醒 // esp_deep_sleep_start(); } void loop() { /* 空，或定时唤醒 */ } void displayWeather() { if (WiFi.status() == WL_CONNECTED) { HTTPClient http; http.begin("http://api.weather.com/..."); // 替换为你的天气API int httpCode = http.GET(); if (httpCode == HTTP_CODE_OK) { String payload = http.getString(); // 解析JSON，获取温度、湿度等信息 DynamicJsonDocument doc(1024); deserializeJson(doc, payload); float temp = doc["main"]["temp"]; int humidity = doc["main"]["humidity"]; // 在屏幕上绘制 display.setFullWindow(); display.firstPage(); do { display.fillScreen(GxEPD_WHITE); display.setTextColor(GxEPD_BLACK); display.setFont(&FreeMonoBold18pt7b); display.setCursor(20, 60); display.print(temp, 1); display.print(" C"); display.setFont(&FreeMonoBold12pt7b); display.setCursor(20, 100); display.print("Hum: "); display.print(humidity); display.print("%"); } while (display.nextPage()); } http.end(); } }

这个例子展示了ESP32从网络获取数据并刷新的典型物联网应用。关键在于处理好网络请求、数据解析和屏幕刷新之间的时序，并考虑网络失败时的重试或显示默认信息机制。

6.2 深入ESP-IDF：任务、电源管理与OTA考量

对于更复杂的项目，直接使用ESP-IDF可以提供更好的任务管理、电源控制和OTA（空中升级）支持。

多任务处理：你可以创建一个独立的“显示任务”，它从一个队列中接收需要显示的消息或图像数据。网络任务或传感器任务将数据推送到队列，显示任务负责刷新屏幕。这样避免了在HTTP回调函数中直接操作显示（可能导致阻塞）。

// 显示任务示例 void display_task(void *pvParameters) { epd_init(); // 你自己的初始化函数 display_message_t msg; while(1) { if(xQueueReceive(display_queue, &msg, portMAX_DELAY)) { epd_prepare_frame(msg.data); // 准备图像数据 epd_display_frame(); // 刷新屏幕 epd_sleep(); // 屏幕休眠 vTaskDelay(pdMS_TO_TICKS(100)); // 短暂延迟，防止队列拥塞 } } }

精细电源管理：ESP-IDF允许你配置不同的电源模式。在显示刷新后，除了让电子纸休眠，你还可以将ESP32置于Light-sleep或Deep-sleep模式。在Deep-sleep下，仅RTC模块和ULP协处理器保持供电，电流可低至10μA。通过RTC定时器或GPIO（如按键）唤醒。

OTA升级的注意事项：如果你的设备支持OTA，必须考虑升级过程中或升级失败后的显示状态。一个良好的实践是：

1. 在开始OTA前，在屏幕上显示“Updating...”的静态提示。
2. 使用一个独立的“工厂分区”或“安全启动”分区，确保即使OTA失败，设备也能回退到一个已知可工作的固件，并能在屏幕上显示错误代码。
3. 避免在显示刷新的过程中进行OTA文件写入，这可能导致SPI总线冲突。最好在显示任务处于空闲状态时进行OTA。

6.3 常见问题排查与调试心得

在ESP32上集成电子纸，我遇到过几个典型问题：

1. SPI引脚冲突：ESP32的某些引脚在启动时有特殊功能（如GPIO12影响启动电压，GPIO0影响启动模式）。确保你使用的SPI引脚（特别是CS、DC）不与这些特殊引脚冲突。最好查阅你所使用的具体开发板的引脚定义图。

2. 电源噪声导致显示异常：ESP32在Wi-Fi射频工作时，电源上会有较大的噪声。如果电子纸的电源与ESP32的射频部分共用同一路LDO且滤波不足，可能导致刷新过程中出现乱码或局部刷新失败。解决方案：为电子纸模块使用独立的稳压电源，或者在靠近模块的VCC和GND之间并联一个100μF的电解电容和一个0.1μF的陶瓷电容，进行退耦滤波。

3. GxEPD2库编译错误“没有匹配的函数”：这通常是因为屏幕型号选择错误，或者引脚定义与库中某个构造函数不匹配。仔细核对GxEPD2_display_selection.h文件，找到与你屏幕驱动IC和尺寸完全匹配的类。如果找不到，你可能需要根据已有的类，在库中自行添加一个新的显示类定义，这需要一定的移植工作。

4. 局部刷新累积残影：这是物理特性，无法完全避免。除了之前提到的定期全刷策略，还可以尝试在软件上做“反色闪烁”。即在局部刷新前，先将整个显示区域用反色快速刷新一次（白变黑，黑变白），然后再刷新目标内容。这能帮助清除上一帧的残留电荷，但会稍微增加刷新时间和功耗。这个方法效果因屏幕型号而异，需要实验测试。