ePaper SPI Display

The epaper_spi display platform provides a new ePaper display component architecture with improved state management and non-blocking operation. This component implements a queue-based state machine that eliminates blocking waits for the busy pin and provides better integration with ESPHome’s async architecture.

The communication method uses SPI, so you need to have an spi: section in your configuration.

The driver supports a number of displays and there are also specific configurations for ESP32 boards with integrated displays. For those boards the predefined configuration will set the correct pins and dimensions for the display.

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

Supported display controllers

These are the supported controller chips. Using just the chip name as the model will require full configuration with pins and dimensions specified.

Chip name	Manufacturer	Product Description
JD79660	Jadard	https://www.tdytech.com/en/ (B2B, see vendors instead)
Spectra-E6	Eink	https://www.eink.com/brand/detail/Spectra6
SSD1677	Solomon	https://www.solomon-systech.com/product/ssd1677/

Supported display panels

These models represent display panels with known dimensions, but without a microcontroller. The configuration will require the pins used to interface to the display to be specified.

Display name	Manufacturer	Product Description
Waveshare-1.54in-G	Waveshare	https://www.waveshare.com/1.54inch-e-paper-g.htm
Waveshare-2.13in-v3	Waveshare	https://www.waveshare.com/pico-epaper-2.13.htm
Waveshare-4.26in	Waveshare	https://www.waveshare.com/4.26inch-e-paper.htm
Waveshare-7.5in-H	Waveshare	https://www.waveshare.com/7.5inch-e-paper-hat-h.htm
WeAct-2.13in-3c	WeAct	2.13” 3-color e-paper (250x122, SSD1683)
WeAct-2.9in-3c	WeAct	2.9” 3-color e-paper (128x296, SSD1683)
WeAct-4.2in-3c	WeAct	4.2” 3-color e-paper (400x300, SSD1683)

Supported integrated display boards

These models correspond to displays integrated with a microcontroller, and have a full configuration predefined, so at a minimum only the model name need be configured. Other options can be overridden in the configuration if needed.

Model name	Manufacturer	Product Description
Seeed-reTerminal-E1002	Seeed Studio	https://www.seeedstudio.com/reTerminal-E1002-p-6533.html
Seeed-ee04-mono-4.26	Seeed Studio	Seeed EE04 board with Waveshare 4.26” mono epaper. https://www.seeedstudio.com/XIAO-ePaper-Display-Board-EE04-p-6560.html

Configuration variables

When using a model defining an integrated display board most of the configuration such as the pins and dimensions will be set by default, but can be overridden if needed.

model (Required): The model of the ePaper display. See the table above for options (case is not significant).
cs_pin (Required, Pin Schema): The CS pin. Predefined for integrated boards.
dc_pin (Required, Pin Schema): The DC pin. Predefined for integrated boards.
busy_pin (Optional, Pin Schema): The BUSY pin, if used.

NOTE

Some displays use inverted busy pin polarity (LOW = busy, HIGH = idle). For these models, set inverted: true on the busy pin. This applies to: Waveshare-1.54in-G, Waveshare-7.5in-H.
reset_pin (Optional, Pin Schema): The RESET pin, if used. Make sure you pull this pin high (by connecting it to 3.3V with a resistor) if not connected to a GPIO pin.
dimensions (Required, dict): Dimensions of the screen, specified either as width x height (e.g 320x240 ) or with separate config keys. For integrated boards with full pre-defined configuration this is optional and will be preset by the model selected. The dimensions are specified in pixels, and the width and height must be greater than 0.
- height (Required, int): Specifies height of display.
- width (Required, int): Specifies width of display.
rotation (Optional, int): Set the rotation of the display. Everything you draw in lambda: will be rotated by this option. One of 0° (default), 90°, 180°, 270°.
transform (Optional, dict): If rotation is not sufficient, use this to transform the display. Options are:
- mirror_x (Required, boolean): If true, mirror the x axis.
- mirror_y (Required, boolean): If true, mirror the y axis.
reset_duration (Optional, Time): Duration for the display reset operation. Defaults to 200ms.
lambda (Optional, lambda): The lambda to use for rendering the content on the display. See Display Rendering Engine for more information.
pages (Optional, list): Show pages instead of a single lambda. See Display Pages.
update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 60s, use never to only manually update the screen via component.update.
full_update_every (Optional, int): On screens that support partial updates, this sets the number of updates before a full update is forced. Defaults to 1 which will make every update a full update.
spi_id (Optional, ID): Required to specify the ID of the SPI Component if your configuration defines multiple SPI buses. If only a single SPI bus is configured, this is optional.
id (Optional, ID): Manually specify the ID used for code generation.

Full configuration example

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 # Rotate to portrait
    cs_pin: GPIOXX
    dc_pin: GPIOXX
    reset_pin: GPIOXX
    busy_pin: { number: GPIOXX, inverted: False, mode: { input: True, pulldown: True } }

4-color display example

Some displays support 4 colors (black, white, red, yellow). Colors are mapped from RGB automatically. Full refresh times for 4-color displays are typically around 20 seconds.

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);