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 displays

Model name	Manufacturer	Product Description
Spectra-E6	Eink	https://www.eink.com/brand/detail/Spectra6
Seeed-reTerminal-E1002	Seeed Studio	https://www.seeedstudio.com/reTerminal-E1002-p-6533.html
SSD1677	Solomon	https://www.solomon-systech.com/product/ssd1677/
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 ESP32 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.
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 models 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.