Skip to content
Get started

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

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

Chip nameManufacturerDescriptionLink
JD79660JadardB2B, see vendors insteadProduct page
Spectra-E6EinkProduct page
SSD1677SolomonProduct page
SSD1681Solomon200x200 mono, supports partial refresh via full_update_everyProduct page
SSD1683SolomonProduct page
T133A01TianMa13.3” 6-color e-paper controller IC with dual-CS SPI architecture
UC8151UltraChipUC8151D 3-color (black/white/red) e-paper controller
UC8179UltraChipE-paper controller used by 800x480 7.5” panels (mono and 3-color variants)
UC8279UltraChipMono e-paper controller, supports partial refresh via full_update_every

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.

Models listed under Aliases use identical driver settings, so either name can be used for the same panel.

Display nameAliasesManufacturerDescriptionLink
GooDisplay-GDEY0154D67-1.54Waveshare-1.54in-v2Dalian Good Display1.54” mono e-paper (200x200, SSD1681)Product page
GooDisplay-GDEY0213F51-2.13Waveshare-2.13in-G-V1Dalian Good DisplayProduct page
GooDisplay-GDEY029T94-2.9029BN-T94-D2Dalian Good Display2.9” mono e-paper (128x296, SSD1680). Seeed ships it with a 029BN-T94-D2 sticker. Replaces the waveshare_epaper model gdey029t94.Product page
GooDisplay-GDEY029Z95-2.9Dalian Good Display2.9” 3-color e-paper (128x296, SSD1680)Product page
GooDisplay-GDEY042T81-4.2Dalian Good DisplayProduct page
Waveshare-1.54in-GWaveshareProduct page
Waveshare-1.54in-v2GooDisplay-GDEY0154D67-1.54Waveshare1.54” V2 mono e-paper (200x200, SSD1681)Product page
Waveshare-2.13in-bv3Waveshare2.13” B V3 3-color e-paper (212x104, UC8151D), also used on the Pico-ePaper-2.13-B. Later boards use the V4 panel; see Waveshare-2.13in-bv4.Product page
Waveshare-2.13in-bv4Waveshare2.13” 3-color e-paper (250x122, SSD1683)Product page
Waveshare-2.13in-GWaveshare2.13” 4-color e-paper (124x250 padded from 122, JD79660), current hardware/init revision.Product page
Waveshare-2.13in-G-V1GooDisplay-GDEY0213F51-2.13WaveshareOlder hardware/init revision of the same panel (128x250 padded from 122). Untested.Product page
Waveshare-2.13in-v3WaveshareProduct page
Waveshare-2.66in-bWaveshareProduct page
Waveshare-2.9in-v2Waveshare2.9” V2 mono (128x296, SSD1680), partial refresh via full_update_everyProduct page
Waveshare-3.97inWaveshareProduct page
Waveshare-4.26inWaveshareProduct page
Waveshare-7.5in-bV2-BWRWaveshare7.5” V2 3-color (800x480, UC8179)Product page
Waveshare-7.5in-HWaveshareProduct page
Waveshare-7.5in-V2Waveshare7.5” V2 mono (800x480, UC8179), supports fast and partial refresh via full_update_everyProduct page
WeAct-2.13in-3cWeAct2.13” 3-color e-paper (250x122, SSD1683)
WeAct-2.9in-3cWeAct2.9” 3-color e-paper (128x296, SSD1683)
WeAct-4.2in-3cWeAct4.2” 3-color e-paper (400x300, SSD1683)
XSRUPB-7.5in-bwrXSRUPB7.5” 3-color (800x480, UC8179), sold under part numbers FPC-8612 / DEPG0750RWF86BF30 / XSRUPB-2025Product page

Waveshare-2.9in-v2 replaces model: 2.90inv2 of the deprecated waveshare_epaper component.

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 nameManufacturerDescriptionLink
inkplate2Soldered ElectronicsSoldered Inkplate 2: 2.13” 3-color (black/white/red) e-paper, 104x212.Product page
inkplate6colorSoldered ElectronicsSoldered Inkplate 6COLOR: 7-color (black/white/green/blue/red/yellow/orange) e-paper, 600x448.Product page
Seeed-ee04-mono-4.26Seeed StudioSeeed EE04 board with Waveshare 4.26” mono epaper.Product page
Seeed-reTerminal-E1001Seeed Studio7.5” mono e-paper (800x480, UC8179), supports fast and partial refresh via full_update_every.Product page
Seeed-reTerminal-E1002Seeed StudioProduct page
Seeed-reTerminal-E1004Seeed Studio13.3” 6-color e-paper (1200x1600, T133A01). Requires PSRAM.Product page
Seeed-reTerminal-StickySeeed Studio3.97” mono e-paper (800x480, SSD1677), supports partial refresh via full_update_every. Requires PSRAM.Product page
Seeed-reTerminal-Sticky-gray4Seeed StudioThe reTerminal Sticky in four-level grayscale, for antialiased text. Full refresh only unless monochrome_partial_updates is set; see Four-level grayscale. Requires PSRAM.
Xteink-X4Pro-UC8279XteinkXteink X4 Pro e-reader with its UC8279 panel (800x480 mono), supports partial refresh via full_update_every. The X4 Pro also ships with other panel controllers; this model is only for the UC8279 one. The board’s power rails are not managed by this component.

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.

  • cs1_pin (Optional, Pin Schema): The secondary CS pin for dual-CS displays (e.g. T133A01). Predefined for integrated boards that require it.

  • dc_pin (Required, Pin Schema): The DC pin. Predefined for integrated boards.

  • busy_pin (Optional, Pin Schema): The BUSY pin, if used. Required for GooDisplay-GDEY029Z95-2.9.

    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: UC8151, Waveshare-1.54in-G, Waveshare-2.13in-bv3, Waveshare-2.13in-G, Waveshare-2.13in-G-V1, Waveshare-7.5in-H, Waveshare-7.5in-V2, inkplate6color.

  • reset_pin (Optional, Pin Schema): The RESET pin, if used. Required for the SSD1681-based models (SSD1681, Waveshare-1.54in-v2, GooDisplay-GDEY0154D67-1.54), whose panels only wake from deep sleep on a hardware reset, and for GooDisplay-GDEY029Z95-2.9. Make sure you pull this pin high (by connecting it to 3.3V with a resistor) if not connected to a GPIO pin.

  • enable_pin (Optional, Pin Schema): An optional pin to enable the display, if required. A list of pins can be provided for displays that require multiple enable pins. A full pin configuration may be provided to set the pin mode and inverted property if required. The pin or pins will be driven high (low if inverted) prior to display initialisation. If enable_pin is not set, the model’s default enable pins are used, if it has any. A default enable pin that is also used elsewhere in the configuration, for example by a GPIO switch, is left out, so you can control that pin yourself. If every other use of the pin sets allow_other_uses: true, the pin is shared with the display instead. Setting enable_pin replaces all of the model’s default enable pins.

  • 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.

    NOTE

    Waveshare-2.13in-G and Waveshare-2.13in-G-V1 declare a width of 124 and 128 for a 122 pixel panel, because their init sequence fixes the controller’s row length at that value and the buffer has to match it. get_width() returns the padded width; the hidden columns are the last ones of each row in the panel’s native orientation, so content anchored at the left edge is fully visible and lambdas should treat 122 as the visible width. Do not override dimensions on these models: the row length in the init sequence does not follow it and the image shears diagonally.

    • height (Required, int): Specifies height of display.
    • width (Required, int): Specifies width of display.
    • offset_height (Optional, int): Only for UC8279 models. The number of rows the controller scans before the panel’s first row. The panel is bonded to the last rows of the controller’s gates, so a panel that does not start at the first gate needs this set to its offset. Defaults to 0, or the panel’s own offset for a predefined model such as Xteink-X4Pro-UC8279.
  • 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. A full update can also be requested at any time with the epaper_spi.full_update_next action.

  • monochrome_partial_updates (Optional, boolean): Only for four-level grayscale models (Seeed-reTerminal-Sticky-gray4). Allows full_update_every greater than 1, with the partial updates in between in black and white. Defaults to false: every update is a full four-level update. See Four-level grayscale for the trade-off this accepts.

  • border_waveform (Optional, int): Only for SSD1677 models. The border waveform byte (controller command 0x3C), which sets how the border around the active area is driven. Defaults to 0x01, or 0x00 for Seeed-reTerminal-Sticky-gray4. Rarely needs changing.

  • 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.

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 } }

Fast and partial refresh example (reTerminal E1001)

Section titled “Fast and partial refresh example (reTerminal E1001)”

Displays based on the UC8179 controller (Waveshare-7.5in-V2, Seeed-reTerminal-E1001) support fast full and partial refresh. Set full_update_every greater than 1 to enable it: a fast full refresh is performed every full_update_every updates, with partial refreshes in between. With the default of 1, every update is a normal full refresh.

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

Partial refresh example (1.54” SSD1681 panels)

Section titled “Partial refresh example (1.54” SSD1681 panels)”

The 200x200 panels based on the SSD1681 (Waveshare-1.54in-v2, GooDisplay-GDEY0154D67-1.54, or SSD1681 for another panel of that size) support partial refresh. Set full_update_every greater than 1 to enable it: only the pixels that changed since the previous update are driven, so a partial refresh is quick and does not flash the panel. The full refresh every full_update_every updates clears any residue.

The panel is put into deep sleep after every update and only a hardware reset wakes it, so reset_pin is required.

NOTE

Partial refresh relies on a setting the panel maker stores in the controller (RAM ping-pong), which both named panels have. If the generic SSD1681 model gives garbled partial updates on another panel, that panel lacks it; leave full_update_every at 1.

This example assumes a font with id my_font and a time source with id my_time.

display:
- platform: epaper_spi
model: Waveshare-1.54in-v2
cs_pin: GPIOXX
dc_pin: GPIOXX
reset_pin: GPIOXX
busy_pin: GPIOXX
update_interval: 60s
full_update_every: 20
lambda: |-
it.strftime(0, 0, id(my_font), Color::BLACK, "%H:%M", id(my_time).now());

The Seeed-reTerminal-Sticky-gray4 model drives the panel in four gray levels. With monochrome_partial_updates: true, full_update_every can be greater than 1, and the partial updates in between are black and white. The first partial update removes the gray levels from the whole panel until the next full update, a trade-off often worth making for the noticeably sharper text.

In this mode, an update is partial by default; request a full one with epaper_spi.full_update_next to bring the gray levels back:

display:
- platform: epaper_spi
id: epaper
model: Seeed-reTerminal-Sticky-gray4
monochrome_partial_updates: true
full_update_every: 30
# Partial update: fast, black and white
on_...:
- component.update: epaper
# Full four-level update, bringing the gray levels back
on_...:
- epaper_spi.full_update_next: epaper
- component.update: epaper

NOTE

With custom dimensions, the width must be a multiple of 8.

Some displays support 4 colors (black, white, red, yellow). Colors are mapped from RGB automatically; see Color Panels. 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 RED = Color(255, 0, 0);
auto YELLOW = Color(255, 255, 0);
it.filled_rectangle(50, 50, 80, 80, Color::BLACK);
it.filled_rectangle(150, 50, 80, 80, RED);
it.filled_rectangle(250, 50, 80, 80, YELLOW);

6-color display example (reTerminal E1004)

Section titled “6-color display example (reTerminal E1004)”

The reTerminal E1004 features a 13.3” 6-color e-paper display (1200x1600, T133A01) that supports black, white, red, green, blue, and yellow. Since it is an integrated board, only the model name is needed. The display buffer requires approximately 960KB, so PSRAM is required.

Full refresh times are typically around 30 seconds.

display:
- platform: epaper_spi
model: Seeed-reTerminal-E1004
update_interval: 5min
lambda: |-
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.filled_circle(200, 300, 80, Color::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);

The Soldered Inkplate 6COLOR features a 600x448 7-color e-paper display that supports black, white, green, blue, red, yellow, and orange. Since it is an integrated board, only the model name is needed.

Full refresh times are typically around 40 seconds.

display:
- platform: epaper_spi
model: inkplate6color
update_interval: 5min
lambda: |-
auto GREEN = Color(0, 255, 0);
auto BLUE = Color(0, 0, 255);
auto RED = Color(255, 0, 0);
auto YELLOW = Color(255, 255, 0);
auto ORANGE = Color(255, 165, 0);
it.filled_circle(100, 224, 80, Color::BLACK);
it.filled_circle(250, 224, 80, GREEN);
it.filled_circle(400, 224, 80, BLUE);
it.filled_circle(100, 350, 80, RED);
it.filled_circle(250, 350, 80, YELLOW);
it.filled_circle(400, 350, 80, ORANGE);

Most displays clear to black, but epaper_spi clears the display to white, like blank paper. This applies to the automatic clear before each update (see auto_clear_enabled in Display) and to it.clear().

Drawing methods called without a color still draw in Color::WHITE, which on this display is white on white, so nothing appears. The same applies to graph(), legend() and qr_code(). Pass a color explicitly:

display:
- platform: epaper_spi
# ...
lambda: |-
it.line(0, 0, 50, 50, Color::BLACK);
it.print(0, 10, id(my_font), Color::BLACK, "Hello World!");

Antialiased fonts (bpp greater than 1) blend the edges of each character with a background color that defaults to Color::BLACK, so on white paper the edges come out darker than intended. Pass Color::WHITE as the background:

display:
- platform: epaper_spi
# ...
lambda: |-
it.print(0, 10, id(my_font), Color::BLACK, TextAlign::TOP_LEFT, "Hello World!", Color::WHITE);

Black and white panels convert each color to black or white by its brightness (luma), calculated with the Rec.601 weights, which count green far more than red or blue:

Y=0.299R+0.587G+0.114BY = 0.299R + 0.587G + 0.114B

A luma of 128 or more draws white, anything lower draws black. The four-level grayscale model (Seeed-reTerminal-Sticky-gray4) uses the same luma, split into four bands: below 32 draws black, 32 to 95 dark gray, 96 to 159 light gray, and 160 or more white.

Saturated colors therefore do not map the way their RGB values might suggest:

ColorLumaBlack and whiteFour-level gray
Red (255, 0, 0)77BlackDark gray
Green (0, 255, 0)149WhiteLight gray
Blue (0, 0, 255)29BlackBlack
Yellow (255, 255, 0)226WhiteWhite
Cyan (0, 255, 255)178WhiteWhite
Magenta (255, 0, 255)106BlackLight gray
Orange (255, 165, 0)173WhiteWhite
Gray (128, 128, 128)128WhiteLight gray
Gray (127, 127, 127)127BlackLight gray

This has some consequences:

  • Green, yellow, cyan and orange draw white, so they are invisible on the white background.
  • Red, blue and magenta draw black, so they cannot be told apart from black, for example to highlight a warning.
  • A darker green such as Color(0, 200, 0) (luma 117) draws black, while full green draws white.
  • Mid grays flip between black and white at 128, so a small change in a gray value can invert it.
  • Images and LVGL content are converted pixel by pixel in the same way, without dithering, so areas of similar brightness become solid black or white. For photos, use a BINARY image with dither: FLOYDSTEINBERG, which keeps the shading.

Panels with colored inks map each color to one of their inks. All models first check whether the color is close to gray, meaning its largest and smallest RGB components differ by less than 50. A gray is drawn black or white by its luma, as above (Seeed-reTerminal-E1004 uses the plain average of the components instead).

The 3-color (black, white and red) models, inkplate2, WeAct-*-3c, Waveshare-2.13in-bv4, Waveshare-2.66in-b, Waveshare-7.5in-bV2-BWR and XSRUPB-7.5in-bwr, draw any other color in whichever of black, white or red is nearest in RGB space. A color equally near red and white, such as yellow, draws white. Oranges and dark reds such as (128, 0, 0) therefore draw red, while a very dark red such as (100, 0, 0) draws black and a pale pink such as (255, 129, 129) draws white.

The 4-color (JD79660), 6-color (Seeed-reTerminal-E1002, Seeed-reTerminal-E1004) and inkplate6color models instead count each component as on above 128, and the combination of components that are on selects the ink. Colors with no matching ink are folded into another, and a dark color with no component above 128 is black.

Color3-color4-color6-colorinkplate6color
Red (255, 0, 0)RedRedRedRed
Green (0, 255, 0)BlackBlackGreenGreen
Blue (0, 0, 255)BlackBlackBlueBlue
Yellow (255, 255, 0)WhiteYellowYellowYellow
Cyan (0, 255, 255)WhiteWhiteGreenGreen
Magenta (255, 0, 255)WhiteWhiteRedRed
Orange (255, 165, 0)RedYellowYellowOrange

Things to watch for:

  • Magenta draws white on 3-color and 4-color panels, and so is invisible on the white background.
  • Green draws black on 3-color and 4-color panels, but white on black and white panels.
  • Orange draws red, yellow or orange depending on the panel.
  • Yellow and cyan draw white on 3-color panels.

Make the next update of the display a full one. That update refreshes the whole panel, even if nothing new was drawn.

on_...:
- epaper_spi.full_update_next: epaper
- component.update: epaper # not needed if something else, such as LVGL, triggers the update

This condition lets automations check whether a display update or refresh is in progress. It is true from the moment an update starts until the panel has finished refreshing and gone back to deep sleep.

interval:
- interval: 10s
then:
- if:
condition:
not:
epaper_spi.is_updating: my_display
then:
- component.update: my_display

Configuration variables:

  • id (Required, ID): The ID of the epaper_spi display.