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
Section titled “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 | Description | Link |
|---|---|---|---|
JD79660 | Jadard | B2B, see vendors instead | Product page |
Spectra-E6 | Eink | Product page | |
SSD1677 | Solomon | Product page | |
SSD1681 | Solomon | 200x200 mono, supports partial refresh via full_update_every | Product page |
SSD1683 | Solomon | Product page | |
T133A01 | TianMa | 13.3” 6-color e-paper controller IC with dual-CS SPI architecture | |
UC8151 | UltraChip | UC8151D 3-color (black/white/red) e-paper controller | |
UC8179 | UltraChip | E-paper controller used by 800x480 7.5” panels (mono and 3-color variants) | |
UC8279 | UltraChip | Mono e-paper controller, supports partial refresh via full_update_every |
Supported display panels
Section titled “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.
Models listed under Aliases use identical driver settings, so either name can be used for the same panel.
| Display name | Aliases | Manufacturer | Description | Link |
|---|---|---|---|---|
GooDisplay-GDEY0154D67-1.54 | Waveshare-1.54in-v2 | Dalian Good Display | 1.54” mono e-paper (200x200, SSD1681) | Product page |
GooDisplay-GDEY0213F51-2.13 | Waveshare-2.13in-G-V1 | Dalian Good Display | Product page | |
GooDisplay-GDEY029T94-2.9 | 029BN-T94-D2 | Dalian Good Display | 2.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.9 | Dalian Good Display | 2.9” 3-color e-paper (128x296, SSD1680) | Product page | |
GooDisplay-GDEY042T81-4.2 | Dalian Good Display | Product page | ||
Waveshare-1.54in-G | Waveshare | Product page | ||
Waveshare-1.54in-v2 | GooDisplay-GDEY0154D67-1.54 | Waveshare | 1.54” V2 mono e-paper (200x200, SSD1681) | Product page |
Waveshare-2.13in-bv3 | Waveshare | 2.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-bv4 | Waveshare | 2.13” 3-color e-paper (250x122, SSD1683) | Product page | |
Waveshare-2.13in-G | Waveshare | 2.13” 4-color e-paper (124x250 padded from 122, JD79660), current hardware/init revision. | Product page | |
Waveshare-2.13in-G-V1 | GooDisplay-GDEY0213F51-2.13 | Waveshare | Older hardware/init revision of the same panel (128x250 padded from 122). Untested. | Product page |
Waveshare-2.13in-v3 | Waveshare | Product page | ||
Waveshare-2.66in-b | Waveshare | Product page | ||
Waveshare-2.9in-v2 | Waveshare | 2.9” V2 mono (128x296, SSD1680), partial refresh via full_update_every | Product page | |
Waveshare-3.97in | Waveshare | Product page | ||
Waveshare-4.26in | Waveshare | Product page | ||
Waveshare-7.5in-bV2-BWR | Waveshare | 7.5” V2 3-color (800x480, UC8179) | Product page | |
Waveshare-7.5in-H | Waveshare | Product page | ||
Waveshare-7.5in-V2 | Waveshare | 7.5” V2 mono (800x480, UC8179), supports fast and partial refresh via full_update_every | Product page | |
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) | ||
XSRUPB-7.5in-bwr | XSRUPB | 7.5” 3-color (800x480, UC8179), sold under part numbers FPC-8612 / DEPG0750RWF86BF30 / XSRUPB-2025 | Product page |
Waveshare-2.9in-v2 replaces model: 2.90inv2 of the deprecated waveshare_epaper component.
Supported integrated display boards
Section titled “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 | Description | Link |
|---|---|---|---|
inkplate2 | Soldered Electronics | Soldered Inkplate 2: 2.13” 3-color (black/white/red) e-paper, 104x212. | Product page |
inkplate6color | Soldered Electronics | Soldered Inkplate 6COLOR: 7-color (black/white/green/blue/red/yellow/orange) e-paper, 600x448. | Product page |
Seeed-ee04-mono-4.26 | Seeed Studio | Seeed EE04 board with Waveshare 4.26” mono epaper. | Product page |
Seeed-reTerminal-E1001 | Seeed Studio | 7.5” mono e-paper (800x480, UC8179), supports fast and partial refresh via full_update_every. | Product page |
Seeed-reTerminal-E1002 | Seeed Studio | Product page | |
Seeed-reTerminal-E1004 | Seeed Studio | 13.3” 6-color e-paper (1200x1600, T133A01). Requires PSRAM. | Product page |
Seeed-reTerminal-Sticky | Seeed Studio | 3.97” mono e-paper (800x480, SSD1677), supports partial refresh via full_update_every. Requires PSRAM. | Product page |
Seeed-reTerminal-Sticky-gray4 | Seeed Studio | The 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-UC8279 | Xteink | Xteink 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. |
Configuration variables
Section titled “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.
-
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: trueon 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 forGooDisplay-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_pinis 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 setsallow_other_uses: true, the pin is shared with the display instead. Settingenable_pinreplaces 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-GandWaveshare-2.13in-G-V1declare 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 overridedimensionson 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 asXteink-X4Pro-UC8279.
-
rotation (Optional, int): Set the rotation of the display. Everything you draw in
lambda:will be rotated by this option. One of0°(default),90°,180°,270°. -
transform (Optional, dict): If
rotationis 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, useneverto only manually update the screen viacomponent.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
1which will make every update a full update. A full update can also be requested at any time with theepaper_spi.full_update_nextaction. -
monochrome_partial_updates (Optional, boolean): Only for four-level grayscale models (
Seeed-reTerminal-Sticky-gray4). Allowsfull_update_everygreater than1, with the partial updates in between in black and white. Defaults tofalse: 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 to0x01, or0x00forSeeed-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.
Full configuration example
Section titled “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 } }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());Four-Level Grayscale (reTerminal Sticky)
Section titled “Four-Level Grayscale (reTerminal Sticky)”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 whiteon_...: - component.update: epaper
# Full four-level update, bringing the gray levels backon_...: - epaper_spi.full_update_next: epaper - component.update: epaperNOTE
With custom dimensions, the width must be a multiple of 8.
4-color display example
Section titled “4-color display example”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);7-color display example (Inkplate 6COLOR)
Section titled “7-color display example (Inkplate 6COLOR)”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);Colors
Section titled “Colors”Background and Default Color
Section titled “Background and Default Color”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 and Grayscale Panels
Section titled “Black and White and Grayscale Panels”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:
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:
| Color | Luma | Black and white | Four-level gray |
|---|---|---|---|
Red (255, 0, 0) | 77 | Black | Dark gray |
Green (0, 255, 0) | 149 | White | Light gray |
Blue (0, 0, 255) | 29 | Black | Black |
Yellow (255, 255, 0) | 226 | White | White |
Cyan (0, 255, 255) | 178 | White | White |
Magenta (255, 0, 255) | 106 | Black | Light gray |
Orange (255, 165, 0) | 173 | White | White |
Gray (128, 128, 128) | 128 | White | Light gray |
Gray (127, 127, 127) | 127 | Black | Light 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
BINARYimage withdither: FLOYDSTEINBERG, which keeps the shading.
Color Panels
Section titled “Color Panels”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.
| Color | 3-color | 4-color | 6-color | inkplate6color |
|---|---|---|---|---|
Red (255, 0, 0) | Red | Red | Red | Red |
Green (0, 255, 0) | Black | Black | Green | Green |
Blue (0, 0, 255) | Black | Black | Blue | Blue |
Yellow (255, 255, 0) | White | Yellow | Yellow | Yellow |
Cyan (0, 255, 255) | White | White | Green | Green |
Magenta (255, 0, 255) | White | White | Red | Red |
Orange (255, 165, 0) | Red | Yellow | Yellow | Orange |
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.
Actions
Section titled “Actions”epaper_spi.full_update_next Action
Section titled “epaper_spi.full_update_next Action”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 updateConditions
Section titled “Conditions”epaper_spi.is_updating Condition
Section titled “epaper_spi.is_updating Condition”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_displayConfiguration variables:
- id (Required, ID): The ID of the
epaper_spidisplay.