跳转到内容
ESPHome - 让智能家居更简单2026.7.0

ePaper SPI 显示

epaper_spi 显示平台提供了一种新的 ePaper 显示组件架构 具有改进的状态管理和非阻塞操作。此组件实现了一个 基于队列的状态机，消除了对忙引脚的阻塞等待，并提供了 与 ESPHome 异步架构更好的集成。

通信方法使用 SPI，因此你需要在配置中有一个 spi: 部分。

驱动支持许多显示器，并且还有针对集成显示屏的 ESP32 板的特定配置。 对于这些板子，预定义配置将设置显示屏的正确引脚和尺寸。

display:
  - platform: epaper_spi
    model: Seeed-reTerminal-E1002
    lambda: |-
      it.filled_circle(it.get_width() / 2, it.get_height() / 2, 50, Color::BLACK);

支持的显示控制器

Section titled “支持的显示控制器”

这些是受支持的控制器芯片。仅使用芯片名称作为模型将需要完整配置并 指定引脚和尺寸。

芯片名称制造商产品描述
JD79660Jadardhttps://www.tdytech.com/en/（B2B，请参阅供应商）
Spectra-E6Einkhttps://www.eink.com/brand/detail/Spectra6
SSD1677Solomonhttps://www.solomon-systech.com/product/ssd1677/
SSD1683Solomonhttps://www.solomon-systech.com/product/ssd1683/
T133A01TianMa13.3” 6 色电子纸控制器 IC，双 CS SPI 架构

支持的显示面板

Section titled “支持的显示面板”

这些模型代表具有已知尺寸的显示面板，但没有微控制器。配置需要 指定与显示接口通信所用的引脚。

显示名称制造商产品描述
GooDisplay-GDEY042T81-4.2Dalian Good Displayhttps://www.good-display.com/product/386.html
Waveshare-1.54in-GWavesharehttps://www.waveshare.com/1.54inch-e-paper-g.htm
Waveshare-2.13in-v3Wavesharehttps://www.waveshare.com/pico-epaper-2.13.htm
Waveshare-2.13in-bv4Waveshare2.13” 3 色电子纸（250x122，SSD1683）https://www.waveshare.com/product/displays/e-paper/epaper-3/2.13inch-e-paper-b.htm
Waveshare-3.97inWavesharehttps://www.waveshare.com/3.97inch-e-paper-hat-plus.htm
Waveshare-4.26inWavesharehttps://www.waveshare.com/4.26inch-e-paper.htm
Waveshare-7.5in-HWavesharehttps://www.waveshare.com/7.5inch-e-paper-hat-h.htm
Waveshare-7.5in-bV2-BWRWavesharehttps://www.waveshare.com/7.5inch-e-paper-hat-b.htm — 7.5” V2 3 色（800x480，UC8179）
WeAct-2.13in-3cWeAct2.13” 3 色电子纸（250x122，SSD1683）
WeAct-2.9in-3cWeAct2.9” 3 色电子纸（128x296，SSD1683）
WeAct-4.2in-3cWeAct4.2” 3 色电子纸（400x300，SSD1683）

支持的集成显示板

Section titled “支持的集成显示板”

这些模型对应于与微控制器集成的显示屏，并且有完整的预定义配置，因此至少 只需配置模型名称即可。如有需要，可以在配置中覆盖其他选项。

模型名称制造商产品描述
inkplate2Soldered ElectronicsSoldered Inkplate 2：2.13” 3 色（黑/白/红）电子纸，104x212。https://soldered.com/products/inkplate-2
Seeed-ee04-mono-4.26Seeed Studio带 Waveshare 4.26” 单色电子纸的 Seeed EE04 板。https://www.seeedstudio.com/XIAO-ePaper-Display-Board-EE04-p-6560.html
Seeed-reTerminal-E1002Seeed Studiohttps://www.seeedstudio.com/reTerminal-E1002-p-6533.html
Seeed-reTerminal-E1004Seeed Studio13.3” 6 色电子纸（1200x1600，T133A01）。需要 PSRAM。https://www.seeedstudio.com/reTerminal-E1004-p-6692.html
Seeed-reTerminal-StickySeeed Studiohttps://www.seeedstudio.com/sticky/

配置变量

Section titled “配置变量”

使用集成显示板模型时，大部分配置（如引脚和尺寸）将默认设置， 如有需要可以覆盖。

  • model (必需): ePaper 显示的模型。请参阅上面的表格了解选项（大小写不敏感）。

  • cs_pin (必需, Pin Schema): CS 引脚。集成板预定义。

  • cs1_pin (可选, Pin Schema): 双 CS 显示（例如 T133A01）的辅助 CS 引脚。需要它的集成板已预定义。

  • dc_pin (必需, Pin Schema): DC 引脚。集成板预定义。

  • busy_pin (可选, Pin Schema): 如果使用的 BUSY 引脚。

    NOTE

    一些显示器使用反转的忙引脚极性（LOW = 忙，HIGH = 空闲）。对于这些模型，请在 busy 引脚上设置 inverted: true。这适用于：Waveshare-1.54in-G、Waveshare-7.5in-H。

  • reset_pin (可选, Pin Schema): 如果使用的 RESET 引脚。 如果未连接到 GPIO 引脚，请确保将该引脚拉高（通过电阻连接到 3.3V）。

  • enable_pin (可选, Pin Schema): 一个可选的使能引脚，如果 需要的话。可以提供引脚列表用于需要多个使能引脚的显示。 可以提供完整的引脚配置来设置引脚模式和反转属性（如果需要）。 显示初始化前，引脚将被驱动为高电平（反转时为低电平）。

  • dimensions (必需, dict): 屏幕尺寸，可以 width x height（例如 320x240 ） 或分别用配置键指定。对于有完整预定义配置的集成板，这是可选的，将由 所选模型预设。尺寸以像素为单位指定，且宽高必须大于 0。

    • height (必需, int): 指定显示的高度。
    • width (必需, int): 指定显示的宽度。

  • rotation (可选, int): 设置显示的旋转角度。你在 lambda: 中绘制的一切都将 根据此选项进行旋转。可选值为 0°（默认）、90°、180°、270°。

  • transform (可选, dict): 如果 rotation 不够用，使用此选项来转换显示。选项有：

    • mirror_x (必需, boolean): 如果为 true，则镜像 x 轴。
    • mirror_y (必需, boolean): 如果为 true，则镜像 y 轴。

  • reset_duration (可选, Time): 显示复位操作的持续时间。默认为 200ms。

  • lambda (可选, lambda): 用于在显示上渲染内容的 lambda。 更多信息请参见 显示渲染引擎。

  • pages (可选, list): 显示页面而非单个 lambda。请参见 显示页面。

  • update_interval (可选, Time): 重新绘制屏幕的间隔。默认为 60s， 使用 never 仅通过 component.update 手动更新屏幕。

  • full_update_every (可选, int): 对于支持局部更新的屏幕，这设置强制完全更新之前的更新次数。默认为 1，每次更新都将完全更新。

  • spi_id (可选, ID): 如果配置 定义了多个 SPI 总线，则必须指定 SPI 组件 的 ID。如果只配置了单个 SPI 总线，这是可选的。

  • id (可选, ID): 手动指定用于代码生成的 ID。

完整配置示例

Section titled “完整配置示例”
display:
  - platform: epaper_spi
    model: SSD1677
    full_update_every: 10
    update_interval: 5s
    dimensions:
      width: 800
      height: 480
    transform:
      mirror_x: true
      mirror_y: false
    rotation: 90 # 旋转到纵向
    cs_pin: GPIOXX
    dc_pin: GPIOXX
    reset_pin: GPIOXX
    busy_pin: { number: GPIOXX, inverted: False, mode: { input: True, pulldown: True } }

4 色显示示例

Section titled “4 色显示示例”

一些显示器支持 4 种颜色（黑、白、红、黄）。颜色会自动从 RGB 映射。 4 色显示的完全刷新时间通常在 20 秒左右。

spi:
  clk_pin: GPIO13
  mosi_pin: GPIO14


display:
  - platform: epaper_spi
    model: Waveshare-7.5in-H
    cs_pin: GPIO15
    dc_pin: GPIO27
    reset_pin: GPIO26
    busy_pin:
      number: GPIO25
      inverted: true
    update_interval: 5min
    lambda: |-
      auto BLACK = Color(0, 0, 0);
      auto WHITE = Color(255, 255, 255);
      auto RED = Color(255, 0, 0);
      auto YELLOW = Color(255, 255, 0);


      it.fill(WHITE);
      it.filled_rectangle(50, 50, 80, 80, BLACK);
      it.filled_rectangle(150, 50, 80, 80, RED);
      it.filled_rectangle(250, 50, 80, 80, YELLOW);

6 色显示示例（reTerminal E1004）

Section titled “6 色显示示例（reTerminal E1004）”

reTerminal E1004 具有 13.3” 6 色电子纸显示（1200x1600，T133A01），支持 黑色、白色、红色、绿色、蓝色和黄色。由于它是集成板，只需 模型名称即可。显示缓冲区需要大约 960KB，因此需要 PSRAM。

完全刷新时间通常在 30 秒左右。

display:
  - platform: epaper_spi
    model: Seeed-reTerminal-E1004
    update_interval: 5min
    lambda: |-
      auto BLACK = Color(0, 0, 0);
      auto WHITE = Color(255, 255, 255);
      auto RED = Color(255, 0, 0);
      auto GREEN = Color(0, 255, 0);
      auto BLUE = Color(0, 0, 255);
      auto YELLOW = Color(255, 255, 0);


      it.fill(WHITE);
      it.filled_circle(200, 300, 80, BLACK);
      it.filled_circle(400, 300, 80, RED);
      it.filled_circle(600, 300, 80, GREEN);
      it.filled_circle(200, 550, 80, BLUE);
      it.filled_circle(400, 550, 80, YELLOW);

参见

Section titled “参见”