`EPaperDisplay` Refresh Hangs on ACeP 7-Color Display

Start by reading shared-module/epaperdisplay/EPaperDisplay.c, especially common_hal_epaperdisplay_epaperdisplay_refresh and the _clean_area path linked in the report; compare the CircuitPython 9 and 10 behavior for the ACeP refresh. Reproduce with the supplied SPD1656 example on the Waveshare 5.65-inch display, then identify why display.refresh() hangs and verify a fix by confirming the refresh completes and “Successful Render” prints.

CircuitPython version and board name

Adafruit CircuitPython 10.2.1 on 2026-05-13; ProS3 with ESP32S3

Code/REPL

# SPDX-FileCopyrightText: Copyright (c) 2023 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
# Source: https://github.com/adafruit/Adafruit_CircuitPython_SPD1656/blob/main/examples/spd1656_color_stripes.py

"""Stripes test script for 5.6" 600x448 7-color ACeP display.
Fill the screen with striped rows, one for each possible color.
"""

import bitmaptools
import board
import displayio
import fourwire
import busio

import adafruit_spd1656

displayio.release_displays()

# SPI on ESP32
sck = board.D36
miso = board.D37
mosi = board.D35
dc = board.D38
cs = board.D34
rst = board.D21
busy = board.D12


displayio.release_displays()

spi = busio.SPI(sck, mosi, miso)
display_bus = fourwire.FourWire(
    spi, command=dc, chip_select=cs, reset=rst, baudrate=1000000
)

# Same behavior without busy pin read
# display = adafruit_spd1656.SPD1656(display_bus, width=600, height=448, busy_pin=busy)
display = adafruit_spd1656.SPD1656(display_bus, width=600, height=448)


g = displayio.Group()

bmp = displayio.Bitmap(display.width, display.height, 7)
p = displayio.Palette(7)
p[0] = 0xFFFFFF
p[1] = 0x000000
p[2] = 0x0000FF
p[3] = 0x00FF00
p[4] = 0xFF0000
p[5] = 0xFFFF00
p[6] = 0xFFA500

bmp.fill(0)

for i in range(7):
    bitmaptools.fill_region(
        bmp,
        0,
        i * (display.height // 7),
        display.width,
        i * (display.height // 7) + (display.height // 7),
        i,
    )

tg = displayio.TileGrid(bitmap=bmp, pixel_shader=p)
g.append(tg)

display.root_group = g

print("Dumping to display")
display.refresh()
print("Successful Render")

while True:
    pass

Behavior

Hang when display.refresh() is called - "Successful Render" never appears and the display never refreshes. If I KeyboardInterrupt the program a multitude of potential outputs occur on the epaper display ranging from static with random horizontal lines on the right hand side of the screen to random color mix to actual proper display.

The key problem is that no matter what, the code hangs here and requires human intervention.

Currently using the WaveShare 5.65" e-Paper module: https://www.waveshare.com/5.65inch-e-paper-module-f.htm

Description

• This code works as is on CircuitPython 9.2.9
  • The SPD driver doesn't seem to have changed for CircuitPython 10 aside from a simple recompilation
• Persists for CircuitPython 10.3.0-alpha4
• If I Ctrl+C during the hang, it's about a 50/50 chance that the error is either KeyboardInterrupt or "Refresh Too Soon"
• I have attempted to change the baud rates down as low as 0.5 MHz and that had no effect (CircuitPython 9 doesn't care about speed)

CircuitPython 9 Output:

code.py output:
Dumping to display
Successful Render

CircuitPython 10 Output:

code.py output:
Dumping to display

Ctrl+C pressed after hanging for 20s

Traceback (most recent call last):
  File "code.py", line 68, in <module>
RuntimeError: Refresh too soon

Note: erase on flash doesn't change the behavior

Additional information

This seems to be stuck in a loop here: EPaperDisplay.common_hal_epaperdisplay_epaperdisplay_refresh

If I skip the call with the following diff and compile, everything goes back to normal with a slightly increased rate of the error console rendering on the epaper:

--- a/shared-bindings/epaperdisplay/EPaperDisplay.c
+++ b/shared-bindings/epaperdisplay/EPaperDisplay.c
@@ -122,7 +122,7 @@
            ARG_write_color_ram_command, ARG_color_bits_inverted, ARG_highlight_color, ARG_highlight_color2,
            ARG_refresh_display_command,  ARG_refresh_time, ARG_busy_pin, ARG_busy_state,
            ARG_seconds_per_frame, ARG_always_toggle_chip_select, ARG_grayscale, ARG_advanced_color_epaper, ARG_spectra6,
-           ARG_two_byte_sequence_length, ARG_start_up_time, ARG_address_little_endian };
+           ARG_clean_area_on_refresh, ARG_two_byte_sequence_length, ARG_start_up_time, ARG_address_little_endian };
     static const mp_arg_t allowed_args[] = {
         { MP_QSTR_display_bus, MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_start_sequence, MP_ARG_REQUIRED | MP_ARG_OBJ },
@@ -155,6 +155,7 @@
         { MP_QSTR_grayscale, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} },
         { MP_QSTR_advanced_color_epaper, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} },
         { MP_QSTR_spectra6, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} },
+        { MP_QSTR_clean_area_on_refresh, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = true} },
         { MP_QSTR_two_byte_sequence_length, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} },
         { MP_QSTR_start_up_time, MP_ARG_OBJ | MP_ARG_KW_ONLY, {.u_obj = MP_OBJ_NEW_SMALL_INT(0)} },
         { MP_QSTR_address_little_endian, MP_ARG_BOOL | MP_ARG_KW_ONLY, {.u_bool = false} },
@@ -245,6 +246,7 @@
     construct_args.grayscale = args[ARG_grayscale].u_bool;
     construct_args.acep = args[ARG_advanced_color_epaper].u_bool;
     construct_args.spectra6 = args[ARG_spectra6].u_bool;
+    construct_args.clean_area_on_refresh = args[ARG_clean_area_on_refresh].u_bool;
     construct_args.two_byte_sequence_length = two_byte_sequence_length;
     construct_args.address_little_endian = args[ARG_address_little_endian].u_bool;
     common_hal_epaperdisplay_epaperdisplay_construct(self, &construct_args);
--- a/shared-bindings/epaperdisplay/EPaperDisplay.h
+++ b/shared-bindings/epaperdisplay/EPaperDisplay.h
@@ -37,6 +37,7 @@
     bool grayscale;
     bool acep;
     bool spectra6;
+    bool clean_area_on_refresh;
     bool two_byte_sequence_length;
     bool address_little_endian;
 } epaperdisplay_construct_args_t;
@@ -70,6 +71,7 @@
         .grayscale = false, \
         .acep = false, \
         .spectra6 = false, \
+        .clean_area_on_refresh = true, \
         .two_byte_sequence_length = false, \
         .address_little_endian = false \
 }
--- a/shared-module/epaperdisplay/EPaperDisplay.c
+++ b/shared-module/epaperdisplay/EPaperDisplay.c
@@ -43,6 +43,7 @@
     self->acep = args->acep || args->spectra6;
     self->core.colorspace.sixcolor = args->spectra6;
     self->core.colorspace.sevencolor = args->acep;
+    self->clean_area_on_refresh = args->clean_area_on_refresh;
     bool grayscale = args->grayscale;
     if (self->acep) {
         color_depth = 4; // bits. 7 colors + clean
@@ -372,7 +373,7 @@
     return true;
 }

-static bool _clean_area(epaperdisplay_epaperdisplay_obj_t *self) {
+static bool __attribute__((unused)) _clean_area(epaperdisplay_epaperdisplay_obj_t *self) {
     uint16_t width = displayio_display_core_get_width(&self->core);
     uint16_t height = displayio_display_core_get_height(&self->core);

@@ -438,7 +439,7 @@
     if (current_area == NULL) {
         return true;
     }
-    if (self->acep) {
+    if (self->acep && self->clean_area_on_refresh) {
         epaperdisplay_epaperdisplay_start_refresh(self);
         _clean_area(self);
         epaperdisplay_epaperdisplay_finish_refresh(self);
--- a/shared-module/epaperdisplay/EPaperDisplay.h
+++ b/shared-module/epaperdisplay/EPaperDisplay.h
@@ -24,6 +24,7 @@
     bool refreshing;
     bool grayscale;
     bool acep;
+    bool clean_area_on_refresh;
     bool two_byte_sequence_length;
     display_chip_select_behavior_t chip_select;
 } epaperdisplay_epaperdisplay_obj_t;

I'm not a C developer by trade but AI (Google Gemini/Jules) is. No PR opened as I can't say this is good (or not) code.