diff --git a/AGENTS.md b/AGENTS.md index e7d2fdbbe8c..acefd1df574 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -- Capture CircuitPython output by finding the matching device in `/dev/serial/by-id` +- Capture CircuitPython output by finding the matching device in `/dev/serial/by-id` or `/dev/sandbox` - You can mount the CIRCUITPY drive by doing `udisksctl mount -b /dev/disk/by-label/CIRCUITPY` and access it via `/run/media//CIRCUITPY`. - `circup` is a command line tool to install libraries and examples to CIRCUITPY. -- When connecting to serial devices on Linux use /dev/serial/by-id. These will be more stable than /dev/ttyACM*. +- When connecting to serial devices on Linux use /dev/serial/by-id or /dev/sandbox. These will be more stable than /dev/ttyACM*. diff --git a/ports/atmel-samd/boards/huntercat_nfc/mpconfigboard.mk b/ports/atmel-samd/boards/huntercat_nfc/mpconfigboard.mk index af825c6cf39..4da89f10cb8 100644 --- a/ports/atmel-samd/boards/huntercat_nfc/mpconfigboard.mk +++ b/ports/atmel-samd/boards/huntercat_nfc/mpconfigboard.mk @@ -11,3 +11,22 @@ EXTERNAL_FLASH_DEVICES = "W25Q16JVxQ" LONGINT_IMPL = MPZ CIRCUITPY_CODEOP = 0 + +# No display or display connector. +CIRCUITPY_DISPLAYIO = 0 +CIRCUITPY_PARALLELDISPLAYBUS = 0 + +# No audio input, output, amplifier, microphone, or codec. +CIRCUITPY_AUDIOBUSIO = 0 +CIRCUITPY_AUDIOIO = 0 + +# Discrete LEDs only, not NeoPixels. +CIRCUITPY_RAINBOWIO = 0 +CIRCUITPY_NEOPIXEL_WRITE = 0 +CIRCUITPY_PIXELBUF = 0 + +# No corresponding built-in peripherals. +CIRCUITPY_ONEWIREIO = 0 +CIRCUITPY_PULSEIO = 0 +CIRCUITPY_ROTARYIO = 0 +CIRCUITPY_TOUCHIO = 0 diff --git a/ports/espressif/mpconfigport.mk b/ports/espressif/mpconfigport.mk index a1dc5179a00..038533d3008 100644 --- a/ports/espressif/mpconfigport.mk +++ b/ports/espressif/mpconfigport.mk @@ -551,12 +551,6 @@ CIRCUITPY_AUDIOMIXER_USE_PORT_MIX ?= 1 endif #### end chip-specific choices ######################################## -# The LVGL compositing core replaces the legacy scanline core. EPaperDisplay still -# depends on the legacy display core, so it isn't available with LVGL yet. -ifeq ($(CIRCUITPY_DISPLAYIO_LVGL),1) -CIRCUITPY_EPAPERDISPLAY = 0 -endif - # By default, load native .mpy files. Boards without the flash space turn it off. CIRCUITPY_LOAD_NATIVE ?= 1 diff --git a/ports/zephyr-cp/cptools/build_circuitpython.py b/ports/zephyr-cp/cptools/build_circuitpython.py index 48971d77f4c..988df3a9673 100644 --- a/ports/zephyr-cp/cptools/build_circuitpython.py +++ b/ports/zephyr-cp/cptools/build_circuitpython.py @@ -765,7 +765,7 @@ async def build_circuitpython(): # noqa: C901 or s.parent.name == backend_dir or (s.parent.name == "legacy" and s.name == "__init__.c") ] - if module.name in ("busdisplay", "framebufferio"): + if module.name in ("busdisplay", "epaperdisplay", "framebufferio"): # These have legacy scanline implementations and LVGL ones. backend_dir = "lvgl" if lvgl_enabled else "legacy" backend_root = top / "shared-module" / module.name diff --git a/py/circuitpy_defns.mk b/py/circuitpy_defns.mk index 9fd8abce783..1c6be24f5ab 100755 --- a/py/circuitpy_defns.mk +++ b/py/circuitpy_defns.mk @@ -698,6 +698,7 @@ $(filter $(SRC_PATTERNS), \ __future__/__init__.c \ busdisplay/BusDisplay.c \ camera/ImageFormat.c \ + epaperdisplay/EPaperDisplay.c \ canio/Match.c \ codeop/__init__.c \ countio/Edge.c \ @@ -953,6 +954,7 @@ $(filter $(SRC_PATTERNS), \ busdisplay/lvgl/BusDisplay.c \ displayio/lvgl/TileGrid.c \ displayio/legacy/__init__.c \ + epaperdisplay/lvgl/EPaperDisplay.c \ framebufferio/lvgl/FramebufferDisplay.c \ vectorio/lvgl/VectorShape.c \ videocore/lvgl/VideoBuffer.c \ @@ -969,6 +971,7 @@ $(filter $(SRC_PATTERNS), \ displayio/legacy/OnDiskBitmap.c \ displayio/legacy/Palette.c \ displayio/legacy/TileGrid.c \ + epaperdisplay/legacy/EPaperDisplay.c \ framebufferio/legacy/FramebufferDisplay.c \ vectorio/legacy/VectorShape.c \ videocore/legacy/VideoBuffer.c \ @@ -1219,6 +1222,7 @@ $(filter $(SRC_PATTERNS), \ displayio/bus_core.c \ displayio/display_core.c \ displayio/area.c \ + epaperdisplay/epaper_core.c \ epaperdisplay/lag_drive.c \ usb/utf16le.c \ ) diff --git a/shared-bindings/epaperdisplay/EPaperDisplay.c b/shared-bindings/epaperdisplay/EPaperDisplay.c index 7cfd59adbab..31908307317 100644 --- a/shared-bindings/epaperdisplay/EPaperDisplay.c +++ b/shared-bindings/epaperdisplay/EPaperDisplay.c @@ -450,7 +450,7 @@ static mp_obj_t epaperdisplay_epaperdisplay_obj_refresh(mp_obj_t self_in) { bool ok = common_hal_epaperdisplay_epaperdisplay_refresh(self); if (!ok) { #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->lag.frames > 0) { + if (common_hal_epaperdisplay_epaperdisplay_has_lag_frames(self)) { // Interrupted is not too soon: raise what interrupted it. mp_handle_pending(true); } @@ -484,7 +484,7 @@ static mp_obj_t epaperdisplay_epaperdisplay_clean(size_t n_args, const mp_obj_t epaperdisplay_epaperdisplay_obj_t *self = native_display(pos_args[0]); mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - if (self->lag.frames == 0) { + if (!common_hal_epaperdisplay_epaperdisplay_has_lag_frames(self)) { mp_raise_RuntimeError(MP_ERROR_TEXT("Invalid state")); } mp_int_t frames = mp_arg_validate_int_range(args[ARG_frames].u_int, 0, 255, MP_QSTR_frames); diff --git a/shared-bindings/epaperdisplay/EPaperDisplay.h b/shared-bindings/epaperdisplay/EPaperDisplay.h index a85e3139640..21359ee4bc8 100644 --- a/shared-bindings/epaperdisplay/EPaperDisplay.h +++ b/shared-bindings/epaperdisplay/EPaperDisplay.h @@ -15,7 +15,7 @@ extern const mp_obj_type_t epaperdisplay_epaperdisplay_type; #define NO_COMMAND 0x100 -typedef struct { +typedef struct epaperdisplay_construct_args_t { mp_obj_t bus; const uint8_t *start_sequence; uint16_t start_sequence_len; @@ -113,6 +113,8 @@ bool common_hal_epaperdisplay_epaperdisplay_refresh(epaperdisplay_epaperdisplay_ // Doesn't allocate. Holds any interrupt until it ends. Returns false, with any owed drive still // owed, if the bus can't be had. bool common_hal_epaperdisplay_epaperdisplay_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, bool full); +// True when lag driving is configured for the display. +bool common_hal_epaperdisplay_epaperdisplay_has_lag_frames(epaperdisplay_epaperdisplay_obj_t *self); #endif mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_root_group(epaperdisplay_epaperdisplay_obj_t *self); diff --git a/shared-module/busdisplay/legacy/BusDisplay.c b/shared-module/busdisplay/legacy/BusDisplay.c index 330db3b6cf6..03e2741b93b 100644 --- a/shared-module/busdisplay/legacy/BusDisplay.c +++ b/shared-module/busdisplay/legacy/BusDisplay.c @@ -313,21 +313,7 @@ static void _refresh_display(busdisplay_busdisplay_obj_t *self) { } void common_hal_busdisplay_busdisplay_set_rotation(busdisplay_busdisplay_obj_t *self, int rotation) { - bool transposed = (self->core.rotation == 90 || self->core.rotation == 270); - bool will_transposed = (rotation == 90 || rotation == 270); - if (transposed != will_transposed) { - int tmp = self->core.width; - self->core.width = self->core.height; - self->core.height = tmp; - } - displayio_display_core_set_rotation(&self->core, rotation); - if (self == &displays[0].display) { - supervisor_stop_terminal(); - supervisor_start_terminal(self->core.width, self->core.height); - } - if (self->core.current_group != NULL) { - displayio_group_update_transform(self->core.current_group, &self->core.transform); - } + displayio_display_core_set_rotation_and_update(&self->core, rotation, &self->base); } uint16_t common_hal_busdisplay_busdisplay_get_rotation(busdisplay_busdisplay_obj_t *self) { diff --git a/shared-module/displayio/display_core.c b/shared-module/displayio/display_core.c index 8cfecc2822a..a3a1a16a7f0 100644 --- a/shared-module/displayio/display_core.c +++ b/shared-module/displayio/display_core.c @@ -106,6 +106,28 @@ void displayio_display_core_set_rotation(displayio_display_core_t *self, #endif } +#if !CIRCUITPY_DISPLAYIO_LVGL +// Keep this out of line so each display implementation and its binding don't get separate copies. +MP_NOINLINE void displayio_display_core_set_rotation_and_update(displayio_display_core_t *self, + int rotation, mp_obj_base_t *display) { + bool transposed = (self->rotation == 90 || self->rotation == 270); + bool will_transposed = (rotation == 90 || rotation == 270); + if (transposed != will_transposed) { + int tmp = self->width; + self->width = self->height; + self->height = tmp; + } + displayio_display_core_set_rotation(self, rotation); + if (display == &displays[0].display_base) { + supervisor_stop_terminal(); + supervisor_start_terminal(self->width, self->height); + } + if (self->current_group != NULL) { + displayio_group_update_transform(self->current_group, &self->transform); + } +} +#endif + bool displayio_display_core_set_root_group(displayio_display_core_t *self, displayio_group_t *root_group) { if (root_group == NULL) { diff --git a/shared-module/displayio/display_core.h b/shared-module/displayio/display_core.h index 53c0fc609e0..c4bcbad8a4c 100644 --- a/shared-module/displayio/display_core.h +++ b/shared-module/displayio/display_core.h @@ -49,6 +49,9 @@ void displayio_display_core_set_rotation(displayio_display_core_t *self, int rot void release_display_core(displayio_display_core_t *self); #if !CIRCUITPY_DISPLAYIO_LVGL +void displayio_display_core_set_rotation_and_update(displayio_display_core_t *self, int rotation, + mp_obj_base_t *display); + bool displayio_display_core_start_refresh(displayio_display_core_t *self); void displayio_display_core_finish_refresh(displayio_display_core_t *self); diff --git a/shared-module/displayio/legacy/__init__.c b/shared-module/displayio/legacy/__init__.c index 567f8cf8f83..6edb2902372 100644 --- a/shared-module/displayio/legacy/__init__.c +++ b/shared-module/displayio/legacy/__init__.c @@ -133,7 +133,7 @@ static mp_obj_t get_display_bus(int display_number) { #endif #if CIRCUITPY_EPAPERDISPLAY } else if (display->display_base.type == &epaperdisplay_epaperdisplay_type) { - return display->epaper_display.bus.bus; + return display->epaper_display.epaper.bus.bus; #endif #if CIRCUITPY_FRAMEBUFFERIO } else if (display->display_base.type == &framebufferio_framebufferdisplay_type) { diff --git a/shared-module/epaperdisplay/EPaperDisplay.c b/shared-module/epaperdisplay/EPaperDisplay.c index a7d4f1262ad..3334763ad18 100644 --- a/shared-module/epaperdisplay/EPaperDisplay.c +++ b/shared-module/epaperdisplay/EPaperDisplay.c @@ -6,925 +6,19 @@ #include "shared-bindings/epaperdisplay/EPaperDisplay.h" -#include "py/gc.h" -#include "py/runtime.h" -#include "shared/runtime/interrupt_char.h" -#if CIRCUITPY_EPAPERDISPLAY_FAST && CIRCUITPY_WATCHDOG -#include "shared-bindings/watchdog/WatchDogTimer.h" -#endif -#include "shared-bindings/displayio/ColorConverter.h" -#include "shared-bindings/microcontroller/__init__.h" -#include "shared-bindings/microcontroller/Pin.h" -#include "shared-bindings/time/__init__.h" #include "shared-module/displayio/__init__.h" -#include "shared-module/epaperdisplay/lag_drive.h" #include "supervisor/shared/display.h" -#include "supervisor/shared/tick.h" - -#if CIRCUITPY_TINYUSB -#include "supervisor/usb.h" -#endif - -#include -#include - -#define DELAY 0x80 - -// lag_drive.c calls these only when it is built. Otherwise they stay static, as before it. -#if CIRCUITPY_EPAPERDISPLAY_FAST -#define LAG_SHARED -#else -#define LAG_SHARED static -#endif - -void common_hal_epaperdisplay_epaperdisplay_construct(epaperdisplay_epaperdisplay_obj_t *self, - const epaperdisplay_construct_args_t *args) { - uint16_t color_depth = 1; - bool core_grayscale = true; - if (args->highlight_color != 0x000000) { - self->core.colorspace.tricolor = true; - self->core.colorspace.tricolor_hue = displayio_colorconverter_compute_hue(args->highlight_color); - } else { - self->core.colorspace.tricolor = false; - } - if (args->highlight_color != 0x000000 && args->highlight_color2 != 0x000000) { - self->core.colorspace.tricolor = false; - self->core.colorspace.fourcolor = true; - self->core.colorspace.fourcolor_hue = displayio_colorconverter_compute_hue(args->highlight_color2); - } else { - self->core.colorspace.fourcolor = false; - } - self->acep = args->acep || args->spectra6; - self->core.colorspace.sixcolor = args->spectra6; - self->core.colorspace.sevencolor = args->acep; - bool grayscale = args->grayscale; - if (self->acep) { - color_depth = 4; // bits. 7 colors + clean - grayscale = false; - core_grayscale = false; - } - if ((args->highlight_color != 0x000000 || args->highlight_color2 != 0x000000) && args->write_color_ram_command == NO_COMMAND) { - color_depth = 2; - core_grayscale = false; - grayscale = false; - } - - displayio_display_core_construct(&self->core, args->width, args->height, args->rotation, color_depth, core_grayscale, true, 1, true, true); - displayio_display_bus_construct(&self->bus, args->bus, args->ram_width, args->ram_height, - args->colstart, args->rowstart, - args->set_column_window_command, args->set_row_window_command, args->set_current_column_command, args->set_current_row_command, - false /* data_as_commands */, args->always_toggle_chip_select, - false /* SH1107_addressing */, args->address_little_endian); - - #if CIRCUITPY_EPAPERDISPLAY_FAST - self->lag.slots = NULL; - self->lag.frames = 0; - self->lag.busy_deadline = 0; - self->lag.bus_held = false; - self->lag.state_lost = false; - self->lag.slot_overwriting = false; - self->lag.commit = LAG_COMMIT_NONE; - self->lag.holding_interrupts = false; - self->lag.held_exception = MP_OBJ_NULL; - self->clean_sequence = args->clean_sequence; - self->clean_sequence_len = args->clean_sequence_len; - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - - self->write_black_ram_command = args->write_black_ram_command; - self->black_bits_inverted = args->black_bits_inverted; - self->write_color_ram_command = args->write_color_ram_command; - self->color_bits_inverted = args->color_bits_inverted; - #if CIRCUITPY_EPAPERDISPLAY_FAST - self->write_previous_ram_command = args->write_previous_ram_command; - #endif - self->refresh_time = args->refresh_time * 1000; - self->busy_state = args->busy_state; - self->refreshing = false; - self->milliseconds_per_frame = args->seconds_per_frame * 1000; - self->chip_select = args->always_toggle_chip_select ? CHIP_SELECT_TOGGLE_EVERY_BYTE : CHIP_SELECT_UNTOUCHED; - self->grayscale = grayscale; - - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (args->lag_frames > 0) { - epaperdisplay_lag_construct(self, args->lag_frames); - } - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - - self->start_sequence = args->start_sequence; - self->start_sequence_len = args->start_sequence_len; - self->start_up_time_ms = args->start_up_time * 1000; - self->stop_sequence = args->stop_sequence; - self->stop_sequence_len = args->stop_sequence_len; - self->refresh_sequence = args->refresh_sequence; - self->refresh_sequence_len = args->refresh_sequence_len; - #if CIRCUITPY_EPAPERDISPLAY_FAST - self->fast = args->fast; - self->awake = false; - self->needs_start = false; - #endif - - self->busy.base.type = &mp_type_NoneType; - self->two_byte_sequence_length = args->two_byte_sequence_length; - if (args->busy_pin != NULL) { - self->busy.base.type = &digitalio_digitalinout_type; - common_hal_digitalio_digitalinout_construct(&self->busy, args->busy_pin); - } - - // Clear the color memory if it isn't in use. - if (args->highlight_color == 0x00 && args->highlight_color2 == 0x00 && args->write_color_ram_command != NO_COMMAND) { - // TODO: Clear - } - - // Set the group after initialization otherwise we may send pixels while we delay in - // initialization. - common_hal_epaperdisplay_epaperdisplay_set_root_group(self, &circuitpython_splash); -} - -bool common_hal_epaperdisplay_epaperdisplay_set_root_group(epaperdisplay_epaperdisplay_obj_t *self, displayio_group_t *root_group) { - return displayio_display_core_set_root_group(&self->core, root_group); -} - -static const displayio_area_t *epaperdisplay_epaperdisplay_get_refresh_areas(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->core.full_refresh) { - self->core.area.next = NULL; - return &self->core.area; - } - const displayio_area_t *first_area = NULL; - if (self->core.current_group != NULL) { - first_area = displayio_group_get_refresh_areas(self->core.current_group, NULL); - } - if (first_area != NULL && self->bus.row_command == NO_COMMAND) { - // Do a full refresh if the display doesn't support partial updates. - self->core.area.next = NULL; - return &self->core.area; - } - return first_area; -} - -uint16_t common_hal_epaperdisplay_epaperdisplay_get_width(epaperdisplay_epaperdisplay_obj_t *self) { - return displayio_display_core_get_width(&self->core); -} - -uint16_t common_hal_epaperdisplay_epaperdisplay_get_height(epaperdisplay_epaperdisplay_obj_t *self) { - return displayio_display_core_get_height(&self->core); -} - -#if CIRCUITPY_EPAPERDISPLAY_FAST -// BUSY can take a moment to rise after an update command, and reading it low before then would -// look like a finished update. If it never rises, nothing has started or it was too quick to see, -// so this returns false after 2 ms. Short enough that an interrupt doesn't have to end it. -bool epaperdisplay_epaperdisplay_wait_for_update_start(epaperdisplay_epaperdisplay_obj_t *self) { - for (uint8_t wait = 0; wait < 200; wait++) { - if (common_hal_digitalio_digitalinout_get_value(&self->busy) == self->busy_state) { - return true; - } - common_hal_mcu_delay_us(10); - } - return false; -} -#endif // CIRCUITPY_EPAPERDISPLAY_FAST - -#if CIRCUITPY_EPAPERDISPLAY_FAST -// When a wait for BUSY or the bus gives up, or 0 for never. Lag drive always has an end, so a -// stuck panel can't hold up a caller that holds interrupts or has no way to be interrupted. -static uint64_t display_wait_deadline(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->lag.busy_deadline != 0 || self->lag.frames == 0) { - return self->lag.busy_deadline; - } - return supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; -} - -// Between hold and release a waveform or a panel reset is under way, and cutting it short leaves -// the panel dark. Whatever interrupts (Ctrl-C, a reload, a watchdog) waits for the release. -bool epaperdisplay_epaperdisplay_interrupted(epaperdisplay_epaperdisplay_obj_t *self) { - if (!self->lag.holding_interrupts) { - return mp_hal_is_interrupted(); - } - if (mp_hal_is_interrupted()) { - if (self->lag.held_exception == MP_OBJ_NULL) { - self->lag.held_exception = MP_STATE_THREAD(mp_pending_exception); - } - MP_STATE_THREAD(mp_pending_exception) = MP_OBJ_NULL; - } - #if CIRCUITPY_WATCHDOG - // A stored waveform takes seconds, and a reset mid-waveform leaves the panel dark. These waits - // are bounded, so a hang still ends. - if (common_hal_watchdog_get_mode(&common_hal_mcu_watchdogtimer_obj) != WATCHDOGMODE_NONE) { - common_hal_watchdog_feed(&common_hal_mcu_watchdogtimer_obj); - } - #endif - return false; -} - -static bool display_send_command(epaperdisplay_epaperdisplay_obj_t *self, const uint8_t *command, - const uint8_t *data, uint32_t length) { - for (uint8_t attempt = 0; attempt < 3; attempt++) { - if (epaperdisplay_lag_send(self, DISPLAY_COMMAND, command, 1) && epaperdisplay_lag_send(self, DISPLAY_DATA, data, length)) { - return true; - } - // The send stopped, and it may have arrived. If it was an update, sending it again would - // drive every pixel a second time. BUSY high says it landed. A command with no data could - // be an update that BUSY hasn't shown yet, so don't risk it: the drive is now unknown. - if (epaperdisplay_epaperdisplay_wait_for_update_start(self)) { - return true; - } - if (length == 0) { - self->lag.state_lost = true; - return false; - } - } - return false; -} - -// A delay ends early when interrupted, which a held interrupt must not do. -void epaperdisplay_epaperdisplay_delay_ms(epaperdisplay_epaperdisplay_obj_t *self, uint32_t delay_ms) { - uint64_t start = supervisor_ticks_ms64(); - uint32_t elapsed = 0; - while (true) { - common_hal_time_delay_ms(delay_ms - elapsed); - elapsed = supervisor_ticks_ms64() - start; - if (!self->lag.holding_interrupts || elapsed >= delay_ms) { - return; - } - epaperdisplay_epaperdisplay_interrupted(self); - } -} -#else // CIRCUITPY_EPAPERDISPLAY_FAST -#define display_wait_deadline(self) ((uint64_t)0) -#define epaperdisplay_epaperdisplay_interrupted(self) mp_hal_is_interrupted() -#define display_send_command(self, command, data, length) ( \ - (self)->bus.send((self)->bus.bus, DISPLAY_COMMAND, (self)->chip_select, command, 1), \ - (self)->bus.send((self)->bus.bus, DISPLAY_DATA, (self)->chip_select, data, length), \ - true) -#define epaperdisplay_epaperdisplay_delay_ms(self, delay_ms) common_hal_time_delay_ms(delay_ms) -#endif // CIRCUITPY_EPAPERDISPLAY_FAST - -LAG_SHARED void epaperdisplay_epaperdisplay_wait_for_busy(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->busy.base.type == &mp_type_NoneType) { - return; - } - const uint64_t deadline = display_wait_deadline(self); - while (common_hal_digitalio_digitalinout_get_value(&self->busy) == self->busy_state && - !epaperdisplay_epaperdisplay_interrupted(self)) { - if (deadline != 0 && supervisor_ticks_ms64() > deadline) { - return; - } - RUN_BACKGROUND_TASKS; - } -} - -// True if every command went out. Lag drive counts an update only if its last command did. -LAG_SHARED bool epaperdisplay_epaperdisplay_send_command_sequence(epaperdisplay_epaperdisplay_obj_t *self, - bool should_wait_for_busy, const uint8_t *sequence, uint32_t sequence_len) { - uint32_t i = 0; - while (i < sequence_len) { - const uint8_t *cmd = sequence + i; - uint8_t data_size = *(cmd + 1); - bool delay = (data_size & DELAY) != 0; - const uint8_t *data = cmd + 2; - data_size &= ~DELAY; - if (self->two_byte_sequence_length) { - data_size = ((data_size & ~DELAY) << 8) + *(cmd + 2); - data = cmd + 3; - } - bool have_bus; - const uint64_t deadline = display_wait_deadline(self); - while (!(have_bus = displayio_display_bus_begin_transaction(&self->bus)) && - !epaperdisplay_epaperdisplay_interrupted(self) && (deadline == 0 || supervisor_ticks_ms64() <= deadline)) { - RUN_BACKGROUND_TASKS; - } - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (!have_bus && self->lag.frames > 0) { - return false; - } - self->lag.bus_held = have_bus; - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - const bool sent = display_send_command(self, cmd, data, data_size); - displayio_display_bus_end_transaction(&self->bus); - #if CIRCUITPY_EPAPERDISPLAY_FAST - self->lag.bus_held = false; - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - if (!sent) { - return false; - } - uint16_t delay_length_ms = 0; - if (delay) { - data_size++; - delay_length_ms = *(cmd + 1 + data_size + self->two_byte_sequence_length); - if (delay_length_ms == 255) { - delay_length_ms = 500; - } - } - epaperdisplay_epaperdisplay_delay_ms(self, delay_length_ms); - if (should_wait_for_busy) { - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->lag.frames > 0) { - epaperdisplay_epaperdisplay_wait_for_update_start(self); - } - #endif - epaperdisplay_epaperdisplay_wait_for_busy(self); - } - #if !CIRCUITPY_EPAPERDISPLAY_FAST - if (mp_hal_is_interrupted()) { - return true; - } - #endif - i += 2 + data_size; - if (self->two_byte_sequence_length) { - i++; - } - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (epaperdisplay_epaperdisplay_interrupted(self)) { - return i >= sequence_len; - } - #endif - } - return true; -} - -void epaperdisplay_epaperdisplay_change_refresh_mode_parameters(epaperdisplay_epaperdisplay_obj_t *self, - mp_buffer_info_t *start_sequence, mp_buffer_info_t *refresh_sequence, float seconds_per_frame) { - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->lag.frames > 0) { - // Finish the drive with the waveform that started it, and rewrite both planes after. - nlr_buf_t nlr; - if (nlr_push(&nlr) == 0) { - epaperdisplay_lag_flush(self); - epaperdisplay_epaperdisplay_wait_for_busy(self); - nlr_pop(); - } else { - epaperdisplay_lag_raise(self, nlr.ret_val); - } - if (self->lag.settle > 0 || self->lag.commit != LAG_COMMIT_NONE) { - // Still owed: keep the mode that started it. - if (!mp_hal_is_interrupted()) { - mp_raise_RuntimeError_varg(MP_ERROR_TEXT("%q in use"), MP_QSTR_display_bus); - } - return; - } - self->lag.force_full = true; - } - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - self->start_sequence = (uint8_t *)start_sequence->buf; - self->start_sequence_len = start_sequence->len; - #if CIRCUITPY_EPAPERDISPLAY_FAST - // NULL keeps the current refresh sequence. - if (refresh_sequence != NULL) { - self->refresh_sequence = (uint8_t *)refresh_sequence->buf; - self->refresh_sequence_len = refresh_sequence->len; - } - #endif - self->milliseconds_per_frame = seconds_per_frame * 1000; - #if CIRCUITPY_EPAPERDISPLAY_FAST - self->needs_start = true; - #endif -} - -#if CIRCUITPY_EPAPERDISPLAY_FAST -// For a panel kept awake. Ctrl-C raises from a send in progress, and that transaction is still -// open. The caller still has things to do first, so the interrupt raises later. -static void send_stop_sequence_guarded(epaperdisplay_epaperdisplay_obj_t *self) { - nlr_buf_t nlr; - if (nlr_push(&nlr) == 0) { - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - nlr_pop(); - } else { - if (!displayio_display_bus_is_free(&self->bus)) { - displayio_display_bus_end_transaction(&self->bus); - } - mp_sched_exception(nlr.ret_val); - } -} -#endif // CIRCUITPY_EPAPERDISPLAY_FAST - -LAG_SHARED void epaperdisplay_epaperdisplay_start_refresh(epaperdisplay_epaperdisplay_obj_t *self) { - if (!displayio_display_bus_is_free(&self->bus)) { - // Can't acquire display bus; skip updating this display. Try next display. - return; - } - if (!displayio_display_core_start_refresh(&self->core)) { - // Refresh on this display already in progress. - return; - } - - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->fast && self->awake) { - if (!self->needs_start) { - // The panel is still configured from the previous refresh. - return; - } - epaperdisplay_epaperdisplay_wait_for_busy(self); - // SSD168x controllers commit the last RAM byte when the next command arrives, so a reset - // can't come straight after a RAM write. - send_stop_sequence_guarded(self); - self->awake = false; - } - #endif - - // run start sequence - self->bus.bus_reset(self->bus.bus); - - epaperdisplay_epaperdisplay_delay_ms(self, self->start_up_time_ms); - - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (!epaperdisplay_epaperdisplay_send_command_sequence(self, true, self->start_sequence, self->start_sequence_len) || - epaperdisplay_epaperdisplay_interrupted(self)) { - return; - } - self->awake = true; - self->needs_start = false; - #else - epaperdisplay_epaperdisplay_send_command_sequence(self, true, self->start_sequence, self->start_sequence_len); - #endif -} - -uint32_t common_hal_epaperdisplay_epaperdisplay_get_time_to_refresh(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->core.last_refresh == 0) { - return 0; - } - // Refresh at seconds per frame rate. - uint32_t elapsed_time = supervisor_ticks_ms64() - self->core.last_refresh; - if (elapsed_time > self->milliseconds_per_frame) { - return 0; - } - return self->milliseconds_per_frame - elapsed_time; -} - -#if CIRCUITPY_EPAPERDISPLAY_FAST -static bool epaperdisplay_epaperdisplay_refresh_area(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area, bool write_previous); - -// False if the panel is still updating when the wait is over. -static bool wait_for_update_end(epaperdisplay_epaperdisplay_obj_t *self) { - epaperdisplay_epaperdisplay_wait_for_update_start(self); - const uint64_t deadline = supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; - bool busy; - while ((busy = common_hal_digitalio_digitalinout_get_value(&self->busy) == self->busy_state) && - !mp_hal_is_interrupted() && supervisor_ticks_ms64() <= deadline) { - RUN_BACKGROUND_TASKS; - } - return !busy; -} - -static void epaperdisplay_epaperdisplay_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas) { - // Actually refresh the display now that all pixel RAM has been updated. - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->refresh_sequence, self->refresh_sequence_len); - const uint64_t refresh_start = supervisor_ticks_ms64(); - bool previous_written = true; - mp_obj_t raised = MP_OBJ_NULL; - - if (self->write_previous_ram_command != NO_COMMAND && areas != NULL) { - // Copy the new image into the previous image RAM so the next partial update compares - // against what is on screen. The controller ignores RAM writes while it is updating. - if (self->busy.base.type == &mp_type_NoneType) { - common_hal_time_delay_ms(self->refresh_time); - } else { - previous_written = wait_for_update_end(self); - } - nlr_buf_t nlr; - if (nlr_push(&nlr) == 0) { - while (areas != NULL && previous_written) { - previous_written = !mp_hal_is_interrupted() && - epaperdisplay_epaperdisplay_refresh_area(self, areas, true); - areas = areas->next; - } - nlr_pop(); - } else { - // Ctrl-C raises from a transfer in progress, and that transaction is still open. - raised = nlr.ret_val; - previous_written = false; - if (!displayio_display_bus_is_free(&self->bus)) { - displayio_display_bus_end_transaction(&self->bus); - } - } - } - - supervisor_enable_tick(); - self->refreshing = true; - - displayio_display_core_finish_refresh(&self->core); - // The update began before the wait above, and refresh_time and seconds_per_frame count from it. - self->core.last_refresh = refresh_start; - if (!previous_written) { - // The previous RAM is stale, so the next update has to write everything. - self->core.full_refresh = true; - } - if (raised != MP_OBJ_NULL) { - nlr_jump(raised); - } -} -#else -static void epaperdisplay_epaperdisplay_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas) { - // Actually refresh the display now that all pixel RAM has been updated. - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->refresh_sequence, self->refresh_sequence_len); - - supervisor_enable_tick(); - self->refreshing = true; - - displayio_display_core_finish_refresh(&self->core); -} -#endif // CIRCUITPY_EPAPERDISPLAY_FAST - -mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_bus(epaperdisplay_epaperdisplay_obj_t *self) { - return self->bus.bus; -} - -void common_hal_epaperdisplay_epaperdisplay_set_rotation(epaperdisplay_epaperdisplay_obj_t *self, int rotation) { - bool transposed = (self->core.rotation == 90 || self->core.rotation == 270); - bool will_transposed = (rotation == 90 || rotation == 270); - if (transposed != will_transposed) { - int tmp = self->core.width; - self->core.width = self->core.height; - self->core.height = tmp; - } - displayio_display_core_set_rotation(&self->core, rotation); - if (self == &displays[0].epaper_display) { - supervisor_stop_terminal(); - supervisor_start_terminal(self->core.width, self->core.height); - } - if (self->core.current_group != NULL) { - displayio_group_update_transform(self->core.current_group, &self->core.transform); - } -} - -uint16_t common_hal_epaperdisplay_epaperdisplay_get_rotation(epaperdisplay_epaperdisplay_obj_t *self) { - return self->core.rotation; -} - -mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_root_group(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->core.current_group == NULL) { - return mp_const_none; - } - return self->core.current_group; -} - -static bool epaperdisplay_epaperdisplay_refresh_area(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area, bool write_previous) { - uint16_t buffer_size = 128; // In uint32_ts - - displayio_area_t clipped; - // Clip the area to the display by overlapping the areas. If there is no overlap then we're done. - if (!displayio_display_core_clip_area(&self->core, area, &clipped)) { - return true; - } - uint16_t subrectangles = 1; - uint16_t rows_per_buffer = displayio_area_height(&clipped); - uint8_t pixels_per_word = (sizeof(uint32_t) * 8) / self->core.colorspace.depth; - uint16_t pixels_per_buffer = displayio_area_size(&clipped); - if (displayio_area_size(&clipped) > buffer_size * pixels_per_word) { - rows_per_buffer = buffer_size * pixels_per_word / displayio_area_width(&clipped); - if (rows_per_buffer == 0) { - rows_per_buffer = 1; - } - subrectangles = displayio_area_height(&clipped) / rows_per_buffer; - if (displayio_area_height(&clipped) % rows_per_buffer != 0) { - subrectangles++; - } - pixels_per_buffer = rows_per_buffer * displayio_area_width(&clipped); - buffer_size = pixels_per_buffer / pixels_per_word; - if (pixels_per_buffer % pixels_per_word) { - buffer_size += 1; - } - } - - // Allocated and shared as a uint32_t array so the compiler knows the - // alignment everywhere. - uint32_t buffer[buffer_size]; - volatile uint32_t mask_length = (pixels_per_buffer / 32) + 1; - uint32_t mask[mask_length]; - - uint8_t passes = 1; - if (self->write_color_ram_command != NO_COMMAND && !write_previous) { - passes = 2; - } - for (uint8_t pass = 0; pass < passes; pass++) { - uint16_t remaining_rows = displayio_area_height(&clipped); - - if (self->bus.row_command != NO_COMMAND) { - displayio_display_bus_set_region_to_update(&self->bus, &self->core.colorspace, &clipped); - } - - uint8_t write_command = self->write_black_ram_command; - if (pass == 1) { - write_command = self->write_color_ram_command; - } - #if CIRCUITPY_EPAPERDISPLAY_FAST - else if (write_previous) { - write_command = self->write_previous_ram_command; - } - #endif - if (!displayio_display_bus_begin_transaction(&self->bus)) { - // Display bus not available now. - return false; - } - self->bus.send(self->bus.bus, DISPLAY_COMMAND, self->chip_select, &write_command, 1); - displayio_display_bus_end_transaction(&self->bus); - - for (uint16_t j = 0; j < subrectangles; j++) { - displayio_area_t subrectangle = { - .x1 = clipped.x1, - .y1 = clipped.y1 + rows_per_buffer * j, - .x2 = clipped.x2, - .y2 = clipped.y1 + rows_per_buffer * (j + 1) - }; - if (remaining_rows < rows_per_buffer) { - subrectangle.y2 = subrectangle.y1 + remaining_rows; - } - remaining_rows -= rows_per_buffer; - - - uint16_t subrectangle_size_bytes = displayio_area_size(&subrectangle) / (8 / self->core.colorspace.depth); - - memset(mask, 0, mask_length * sizeof(mask[0])); - memset(buffer, 0, buffer_size * sizeof(buffer[0])); - - if (!self->acep) { - self->core.colorspace.grayscale = true; - self->core.colorspace.grayscale_bit = 7; - } - if (pass == 1) { - if (self->grayscale) { // 4-color grayscale - self->core.colorspace.grayscale_bit = 6; - displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer); - } else if (self->core.colorspace.tricolor) { - self->core.colorspace.grayscale = false; - displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer); - } else if (self->core.colorspace.sixcolor || self->core.colorspace.sevencolor) { - displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer); - } - } else { - displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer); - } - - // Invert it all. - if ((pass == 1 && self->color_bits_inverted) || - (pass == 0 && self->black_bits_inverted)) { - for (uint16_t k = 0; k < buffer_size; k++) { - buffer[k] = ~buffer[k]; - } - } - - if (!displayio_display_bus_begin_transaction(&self->bus)) { - // Can't acquire display bus; skip the rest of the data. Try next display. - return false; - } - self->bus.send(self->bus.bus, DISPLAY_DATA, self->chip_select, (uint8_t *)buffer, subrectangle_size_bytes); - displayio_display_bus_end_transaction(&self->bus); - - // Run background tasks so they can run during an explicit refresh. - // Auto-refresh won't run background tasks here because it is a background task itself. - RUN_BACKGROUND_TASKS; - - // Run USB background tasks so they can run during an implicit refresh. - #if CIRCUITPY_TINYUSB - usb_background(); - #endif - } - } - - return true; -} - -static bool _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); - - uint8_t buffer[width / 2]; - memset(buffer, 0x77, width / 2); - - uint8_t write_command = self->write_black_ram_command; - if (!displayio_display_bus_begin_transaction(&self->bus)) { - return false; - } - self->bus.send(self->bus.bus, DISPLAY_COMMAND, self->chip_select, &write_command, 1); - displayio_display_bus_end_transaction(&self->bus); - - for (uint16_t j = 0; j < height; j++) { - if (!displayio_display_bus_begin_transaction(&self->bus)) { - // Can't acquire display bus; skip the rest of the data. Try next display. - return false; - } - self->bus.send(self->bus.bus, DISPLAY_DATA, self->chip_select, buffer, width / 2); - displayio_display_bus_end_transaction(&self->bus); - - // TODO(tannewt): Make refresh displays faster so we don't starve other - // background tasks. - #if CIRCUITPY_TINYUSB - usb_background(); - #endif - } - - return true; -} - -bool common_hal_epaperdisplay_epaperdisplay_refresh(epaperdisplay_epaperdisplay_obj_t *self) { - - if (self->refreshing && self->busy.base.type == &digitalio_digitalinout_type) { - if (common_hal_digitalio_digitalinout_get_value(&self->busy) != self->busy_state) { - supervisor_disable_tick(); - self->refreshing = false; - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (!self->fast) { - // Run stop sequence but don't wait for busy because busy is set when sleeping. - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - } - #else - // Run stop sequence but don't wait for busy because busy is set when sleeping. - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - #endif - } else { - #if CIRCUITPY_EPAPERDISPLAY_FAST - epaperdisplay_lag_give_up_if_stuck(self); - #endif - return false; - } - } - if (self->core.current_group == NULL) { - #if CIRCUITPY_EPAPERDISPLAY_FAST - // Nothing to draw, but the drive already started is still owed. - if (self->lag.frames > 0 && self->awake) { - return epaperdisplay_lag_refresh(self, NULL); - } - #endif - return true; - } - // Refresh at seconds per frame rate. - if (common_hal_epaperdisplay_epaperdisplay_get_time_to_refresh(self) > 0) { - return false; - } - if (!displayio_display_bus_is_free(&self->bus)) { - // Can't acquire display bus; skip updating this display. Try next display. - return false; - } - const displayio_area_t *current_area = epaperdisplay_epaperdisplay_get_refresh_areas(self); - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->lag.frames > 0) { - return epaperdisplay_lag_refresh(self, current_area); - } - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - if (current_area == NULL) { - return true; - } - if (self->acep) { - epaperdisplay_epaperdisplay_start_refresh(self); - _clean_area(self); - epaperdisplay_epaperdisplay_finish_refresh(self, NULL); - while (self->refreshing && !mp_hal_is_interrupted()) { - RUN_BACKGROUND_TASKS; - } - } - if (mp_hal_is_interrupted()) { - return false; - } - - epaperdisplay_epaperdisplay_start_refresh(self); - const displayio_area_t *first_area = current_area; - while (current_area != NULL) { - epaperdisplay_epaperdisplay_refresh_area(self, current_area, false); - current_area = current_area->next; - } - epaperdisplay_epaperdisplay_finish_refresh(self, first_area); - return true; -} - -void epaperdisplay_epaperdisplay_background(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->refreshing) { - bool refresh_done = false; - if (self->busy.base.type == &digitalio_digitalinout_type) { - bool busy = common_hal_digitalio_digitalinout_get_value(&self->busy); - refresh_done = busy != self->busy_state; - } else { - refresh_done = supervisor_ticks_ms64() - self->core.last_refresh > self->refresh_time; - } - if (refresh_done) { - supervisor_disable_tick(); - self->refreshing = false; - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (!self->fast) { - // Run stop sequence but don't wait for busy because busy is set when sleeping. - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - } - #else - // Run stop sequence but don't wait for busy because busy is set when sleeping. - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - #endif - } - #if CIRCUITPY_EPAPERDISPLAY_FAST - else { - epaperdisplay_lag_give_up_if_stuck(self); - } - #endif - } -} - -bool common_hal_epaperdisplay_epaperdisplay_get_busy(epaperdisplay_epaperdisplay_obj_t *self) { - epaperdisplay_epaperdisplay_background(self); - return self->refreshing; -} - -void release_epaperdisplay(epaperdisplay_epaperdisplay_obj_t *self) { - #if CIRCUITPY_EPAPERDISPLAY_FAST - epaperdisplay_lag_shutdown(self); - epaperdisplay_lag_free(self); - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - if (self->refreshing) { - epaperdisplay_epaperdisplay_wait_for_busy(self); - supervisor_disable_tick(); - self->refreshing = false; - // Run stop sequence but don't wait for busy because busy is set when sleeping. - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->fast) { - send_stop_sequence_guarded(self); - } else { - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - } - #else - epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); - #endif - } - #if CIRCUITPY_EPAPERDISPLAY_FAST - else if (self->fast && self->awake) { - send_stop_sequence_guarded(self); - } - self->awake = false; - #endif - #if CIRCUITPY_EPAPERDISPLAY_FAST - epaperdisplay_lag_release_interrupts(self); - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - - release_display_core(&self->core); - if (self->busy.base.type == &digitalio_digitalinout_type) { - common_hal_digitalio_digitalinout_deinit(&self->busy); - } -} #if CIRCUITPY_EPAPERDISPLAY_FAST -void epaperdisplay_epaperdisplay_prepare_release(epaperdisplay_epaperdisplay_obj_t *self) { - if (self->lag.frames == 0 || (!self->awake && !self->lag.state_lost)) { - return; - } - const uint64_t deadline = supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; - while (!displayio_display_bus_is_free(&self->bus)) { - mp_handle_pending(true); - if (supervisor_ticks_ms64() > deadline) { - mp_raise_RuntimeError_varg(MP_ERROR_TEXT("%q in use"), MP_QSTR_display_bus); - } - RUN_BACKGROUND_TASKS; - } -} -#endif // CIRCUITPY_EPAPERDISPLAY_FAST - -#if CIRCUITPY_EPAPERDISPLAY_FAST -void epaperdisplay_epaperdisplay_end_held_bus(epaperdisplay_epaperdisplay_obj_t *self) { - // The VM is over, so whatever holds the bus can never let it go: end it here. - if (self->fast && !displayio_display_bus_is_free(&self->bus)) { - displayio_display_bus_end_transaction(&self->bus); - self->lag.bus_held = false; - } -} -#endif // CIRCUITPY_EPAPERDISPLAY_FAST - -void epaperdisplay_epaperdisplay_reset(epaperdisplay_epaperdisplay_obj_t *self) { - #if CIRCUITPY_EPAPERDISPLAY_FAST - if (self->lag.frames > 0) { - // Only a primary display gets here; reset_displays() has released the others. The heap is - // still here but the sequences won't be, and the display would otherwise persist to draw - // the splash with them. Finish now and stay asleep. Its bus still holds the pins until - // the next VM ends or release_displays(). - epaperdisplay_epaperdisplay_end_held_bus(self); - release_epaperdisplay(self); - self->base.type = &mp_type_NoneType; - return; - } - #endif // CIRCUITPY_EPAPERDISPLAY_FAST - displayio_display_core_set_root_group(&self->core, &circuitpython_splash); - self->core.full_refresh = true; - #if CIRCUITPY_EPAPERDISPLAY_FAST - // Let the panel sleep after the next refresh when code isn't running. - if (self->fast && self->awake && !self->refreshing) { - // Nothing can catch a raise from a send. A reload may be pending. - epaperdisplay_epaperdisplay_end_held_bus(self); - send_stop_sequence_guarded(self); - self->awake = false; - } - self->fast = false; - #endif -} - -void epaperdisplay_epaperdisplay_collect_ptrs(epaperdisplay_epaperdisplay_obj_t *self) { - displayio_display_core_collect_ptrs(&self->core); - displayio_display_bus_collect_ptrs(&self->bus); - gc_collect_ptr((void *)self->start_sequence); - gc_collect_ptr((void *)self->stop_sequence); - gc_collect_ptr((void *)self->refresh_sequence); - #if CIRCUITPY_EPAPERDISPLAY_FAST - gc_collect_ptr((void *)self->clean_sequence); - gc_collect_ptr(self->lag.held_exception); - #endif // CIRCUITPY_EPAPERDISPLAY_FAST +bool common_hal_epaperdisplay_epaperdisplay_has_lag_frames(epaperdisplay_epaperdisplay_obj_t *self) { + return self->epaper.lag.frames > 0; } +#endif size_t maybe_refresh_epaperdisplay(void) { for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) { if (displays[i].epaper_display.base.type != &epaperdisplay_epaperdisplay_type || - displays[i].epaper_display.core.current_group != &circuitpython_splash) { + displays[i].epaper_display.epaper.core.current_group != &circuitpython_splash) { // Skip regular displays and those not showing the splash. continue; } diff --git a/shared-module/epaperdisplay/EPaperDisplay.h b/shared-module/epaperdisplay/EPaperDisplay.h index 4b0d97bdf0a..e053872403f 100644 --- a/shared-module/epaperdisplay/EPaperDisplay.h +++ b/shared-module/epaperdisplay/EPaperDisplay.h @@ -1,91 +1,26 @@ // This file is part of the CircuitPython project: https://circuitpython.org // // SPDX-FileCopyrightText: Copyright (c) 2019 Scott Shawcroft for Adafruit Industries +// SPDX-FileCopyrightText: Copyright (c) 2026 Scott Shawcroft for Adafruit Industries // // SPDX-License-Identifier: MIT #pragma once -#include "shared-bindings/displayio/Group.h" - -#include "shared-module/displayio/area.h" -#include "shared-module/displayio/bus_core.h" -#include "shared-module/displayio/display_core.h" -#include "common-hal/digitalio/DigitalInOut.h" - -#if CIRCUITPY_EPAPERDISPLAY_FAST -// Lag drive, built on FAST's write_previous_ram_command. FAST writes the last frame to the -// previous RAM, so each changed pixel is driven once. Lag writes the frame from frames -// refreshes ago, so a changed pixel is driven frames times, the same number each way. -// The ring holds those frames. Only used when frames > 0. -typedef struct { - uint8_t **slots; - uint64_t busy_deadline; // When not 0, stop waiting for BUSY or the bus after this tick. - // What interrupted while interrupts are held. A send can raise one from the heap, so it is - // marked in epaperdisplay_epaperdisplay_collect_ptrs(). - mp_obj_t held_exception; - bool holding_interrupts; - bool bus_held; // Inside a transaction, so an exception must end it. - bool last_try; // Shutdown's reset after a stuck wait: the deadline is not renewed. - bool state_lost; // What the panel received is unknown, so it needs a stored-waveform refresh. - bool slot_overwriting; // The oldest frame in the ring is being replaced. - bool commit_drive; // The owed step has pixels to drive. - uint8_t commit; // What the newest step in the ring still has to send. - displayio_area_t commit_box; - uint64_t update_start; // When the running update was sent. - // What each of the last frames + 1 steps rendered, in pixels. - displayio_area_t *boxes; - uint32_t slot_size; - uint16_t stride; - uint16_t rows; - uint8_t frames; - uint8_t head; // Slot of the newest frame. - uint8_t box_index; // Entry in boxes for this step. - uint8_t settle; // Steps owed until every plane pair matches the newest frame. - bool force_full; // Write everything on the next step. -} epaperdisplay_lag_t; +// The EPaperDisplay implementation has two backends selected at build time with +// CIRCUITPY_DISPLAYIO_LVGL: +// +// legacy/ - renders with the scanline compositor through display_core. +// lvgl/ - renders with LVGL, then converts the composed RGB pixels into the +// packed pixel planes the panel understands. The converted planes are +// kept in a framebuffer of their own so partial updates and the fast +// lag drive do not have to read pixels back from the panel. +#if CIRCUITPY_DISPLAYIO_LVGL +#include "shared-module/epaperdisplay/lvgl/EPaperDisplay.h" +#else +#include "shared-module/epaperdisplay/legacy/EPaperDisplay.h" #endif -typedef struct { - mp_obj_base_t base; - displayio_display_core_t core; - displayio_display_bus_t bus; - digitalio_digitalinout_obj_t busy; - uint32_t milliseconds_per_frame; - const uint8_t *start_sequence; - const uint8_t *stop_sequence; - const uint8_t *refresh_sequence; - uint16_t start_sequence_len; - uint16_t stop_sequence_len; - uint16_t refresh_sequence_len; - uint16_t start_up_time_ms; - uint16_t refresh_time; - uint16_t write_black_ram_command; - uint16_t write_color_ram_command; - #if CIRCUITPY_EPAPERDISPLAY_FAST - uint16_t write_previous_ram_command; - #endif - uint8_t hue; - bool busy_state; - bool black_bits_inverted; - bool color_bits_inverted; - bool refreshing; - bool grayscale; - bool acep; - bool two_byte_sequence_length; - #if CIRCUITPY_EPAPERDISPLAY_FAST - bool fast; - bool awake; - bool needs_start; // update_refresh_mode() changed the start sequence. - #endif - display_chip_select_behavior_t chip_select; - #if CIRCUITPY_EPAPERDISPLAY_FAST - const uint8_t *clean_sequence; - uint32_t clean_sequence_len; - epaperdisplay_lag_t lag; - #endif -} epaperdisplay_epaperdisplay_obj_t; - void epaperdisplay_epaperdisplay_change_refresh_mode_parameters(epaperdisplay_epaperdisplay_obj_t *self, mp_buffer_info_t *start_sequence, mp_buffer_info_t *refresh_sequence, float seconds_per_frame); void epaperdisplay_epaperdisplay_background(epaperdisplay_epaperdisplay_obj_t *self); diff --git a/shared-module/epaperdisplay/epaper_core.c b/shared-module/epaperdisplay/epaper_core.c new file mode 100644 index 00000000000..a053b73b5b4 --- /dev/null +++ b/shared-module/epaperdisplay/epaper_core.c @@ -0,0 +1,476 @@ +// This file is part of the CircuitPython project: https://circuitpython.org +// +// SPDX-FileCopyrightText: Copyright (c) 2019 Scott Shawcroft for Adafruit Industries +// +// SPDX-License-Identifier: MIT + +// Operations on the state shared by the legacy and LVGL EPaperDisplay implementations. + +#include "shared-bindings/epaperdisplay/EPaperDisplay.h" + +#include "py/gc.h" +#include "py/runtime.h" +#include "shared/runtime/interrupt_char.h" +#include "shared-bindings/digitalio/DigitalInOut.h" +#include "shared-bindings/displayio/ColorConverter.h" +#if CIRCUITPY_EPAPERDISPLAY_FAST && CIRCUITPY_WATCHDOG +#include "shared-bindings/watchdog/WatchDogTimer.h" +#endif +#include "shared-bindings/microcontroller/__init__.h" +#include "shared-bindings/time/__init__.h" +#include "shared-module/epaperdisplay/lag_drive.h" +#include "supervisor/port.h" +#include "supervisor/shared/tick.h" + +#include + +#define DELAY 0x80 + +void epaperdisplay_epaper_core_construct(epaperdisplay_epaper_core_t *self, + const epaperdisplay_construct_args_t *args) { + uint16_t color_depth = 1; + bool core_grayscale = true; + if (args->highlight_color != 0x000000) { + self->core.colorspace.tricolor = true; + self->core.colorspace.tricolor_hue = displayio_colorconverter_compute_hue(args->highlight_color); + } else { + self->core.colorspace.tricolor = false; + } + if (args->highlight_color != 0x000000 && args->highlight_color2 != 0x000000) { + self->core.colorspace.tricolor = false; + self->core.colorspace.fourcolor = true; + self->core.colorspace.fourcolor_hue = displayio_colorconverter_compute_hue(args->highlight_color2); + } else { + self->core.colorspace.fourcolor = false; + } + self->acep = args->acep || args->spectra6; + self->core.colorspace.sixcolor = args->spectra6; + self->core.colorspace.sevencolor = args->acep; + bool grayscale = args->grayscale; + if (self->acep) { + color_depth = 4; // bits. 7 colors + clean + grayscale = false; + core_grayscale = false; + } + if ((args->highlight_color != 0x000000 || args->highlight_color2 != 0x000000) && args->write_color_ram_command == NO_COMMAND) { + color_depth = 2; + core_grayscale = false; + grayscale = false; + } + + displayio_display_core_construct(&self->core, args->width, args->height, args->rotation % 360, + color_depth, core_grayscale, true, 1, true, true); + displayio_display_bus_construct(&self->bus, args->bus, args->ram_width, args->ram_height, + args->colstart, args->rowstart, + args->set_column_window_command, args->set_row_window_command, args->set_current_column_command, args->set_current_row_command, + false /* data_as_commands */, args->always_toggle_chip_select, + false /* SH1107_addressing */, args->address_little_endian); + + #if CIRCUITPY_EPAPERDISPLAY_FAST + self->lag.slots = NULL; + self->lag.frames = 0; + self->lag.busy_deadline = 0; + self->lag.bus_held = false; + self->lag.state_lost = false; + self->lag.slot_overwriting = false; + self->lag.commit = LAG_COMMIT_NONE; + self->lag.holding_interrupts = false; + self->lag.held_exception = MP_OBJ_NULL; + self->clean_sequence = args->clean_sequence; + self->clean_sequence_len = args->clean_sequence_len; + self->write_previous_ram_command = args->write_previous_ram_command; + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + + self->write_black_ram_command = args->write_black_ram_command; + self->black_bits_inverted = args->black_bits_inverted; + self->write_color_ram_command = args->write_color_ram_command; + self->color_bits_inverted = args->color_bits_inverted; + self->refresh_time = args->refresh_time * 1000; + self->busy_state = args->busy_state; + self->refreshing = false; + self->milliseconds_per_frame = args->seconds_per_frame * 1000; + self->chip_select = args->always_toggle_chip_select ? CHIP_SELECT_TOGGLE_EVERY_BYTE : CHIP_SELECT_UNTOUCHED; + self->grayscale = grayscale; + self->start_sequence = args->start_sequence; + self->start_sequence_len = args->start_sequence_len; + self->start_up_time_ms = args->start_up_time * 1000; + self->stop_sequence = args->stop_sequence; + self->stop_sequence_len = args->stop_sequence_len; + self->refresh_sequence = args->refresh_sequence; + self->refresh_sequence_len = args->refresh_sequence_len; + #if CIRCUITPY_EPAPERDISPLAY_FAST + self->fast = args->fast; + self->awake = false; + self->needs_start = false; + #endif + + self->busy.base.type = &mp_type_NoneType; + self->two_byte_sequence_length = args->two_byte_sequence_length; + if (args->busy_pin != NULL) { + self->busy.base.type = &digitalio_digitalinout_type; + common_hal_digitalio_digitalinout_construct(&self->busy, args->busy_pin); + } + + // Clear the color memory if it isn't in use. + if (args->highlight_color == 0x00 && args->highlight_color2 == 0x00 && args->write_color_ram_command != NO_COMMAND) { + // TODO: Clear + } +} + +uint16_t epaperdisplay_epaper_core_get_width(epaperdisplay_epaper_core_t *self) { + return displayio_display_core_get_width(&self->core); +} + +uint16_t epaperdisplay_epaper_core_get_height(epaperdisplay_epaper_core_t *self) { + return displayio_display_core_get_height(&self->core); +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +// BUSY can take a moment to rise after an update command, and reading it low before then would +// look like a finished update. If it never rises, nothing has started or it was too quick to see, +// so this returns false after 2 ms. Short enough that an interrupt doesn't have to end it. +bool epaperdisplay_epaper_core_wait_for_update_start(epaperdisplay_epaper_core_t *self) { + for (uint8_t wait = 0; wait < 200; wait++) { + if (common_hal_digitalio_digitalinout_get_value(&self->busy) == self->busy_state) { + return true; + } + common_hal_mcu_delay_us(10); + RUN_BACKGROUND_TASKS; + port_task_yield(); + } + return false; +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +#if CIRCUITPY_EPAPERDISPLAY_FAST +// When a wait for BUSY or the bus gives up, or 0 for never. Lag drive always has an end, so a +// stuck panel can't hold up a caller that holds interrupts or has no way to be interrupted. +static uint64_t display_wait_deadline(epaperdisplay_epaper_core_t *self) { + if (self->lag.busy_deadline != 0 || self->lag.frames == 0) { + return self->lag.busy_deadline; + } + return supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; +} + +// Between hold and release a waveform or a panel reset is under way, and cutting it short leaves +// the panel dark. Whatever interrupts (Ctrl-C, a reload, a watchdog) waits for the release. +bool epaperdisplay_epaper_core_interrupted(epaperdisplay_epaper_core_t *self) { + if (!self->lag.holding_interrupts) { + return mp_hal_is_interrupted(); + } + if (mp_hal_is_interrupted()) { + if (self->lag.held_exception == MP_OBJ_NULL) { + self->lag.held_exception = MP_STATE_THREAD(mp_pending_exception); + } + MP_STATE_THREAD(mp_pending_exception) = MP_OBJ_NULL; + } + #if CIRCUITPY_WATCHDOG + // A stored waveform takes seconds, and a reset mid-waveform leaves the panel dark. These waits + // are bounded, so a hang still ends. + if (common_hal_watchdog_get_mode(&common_hal_mcu_watchdogtimer_obj) != WATCHDOGMODE_NONE) { + common_hal_watchdog_feed(&common_hal_mcu_watchdogtimer_obj); + } + #endif + return false; +} + +static bool display_send_command(epaperdisplay_epaper_core_t *self, const uint8_t *command, + const uint8_t *data, uint32_t length) { + for (uint8_t attempt = 0; attempt < 3; attempt++) { + if (epaperdisplay_lag_send(self, DISPLAY_COMMAND, command, 1) && epaperdisplay_lag_send(self, DISPLAY_DATA, data, length)) { + return true; + } + // The send stopped, and it may have arrived. If it was an update, sending it again would + // drive every pixel a second time. BUSY high says it landed. A command with no data could + // be an update that BUSY hasn't shown yet, so don't risk it: the drive is now unknown. + if (epaperdisplay_epaper_core_wait_for_update_start(self)) { + return true; + } + if (length == 0) { + self->lag.state_lost = true; + return false; + } + } + return false; +} +#else // CIRCUITPY_EPAPERDISPLAY_FAST +#define display_wait_deadline(self) ((uint64_t)0) +#define epaperdisplay_epaper_core_interrupted(self) mp_hal_is_interrupted() +#define display_send_command(self, command, data, length) ( \ + (self)->bus.send((self)->bus.bus, DISPLAY_COMMAND, (self)->chip_select, command, 1), \ + (self)->bus.send((self)->bus.bus, DISPLAY_DATA, (self)->chip_select, data, length), \ + true) +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +// A delay ends early when interrupted, which a held interrupt must not do. +void epaperdisplay_epaper_core_delay_ms(epaperdisplay_epaper_core_t *self, uint32_t delay_ms) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + uint64_t start = supervisor_ticks_ms64(); + uint32_t elapsed = 0; + while (true) { + common_hal_time_delay_ms(delay_ms - elapsed); + elapsed = supervisor_ticks_ms64() - start; + if (!self->lag.holding_interrupts || elapsed >= delay_ms) { + return; + } + epaperdisplay_epaper_core_interrupted(self); + } + #else + (void)self; + common_hal_time_delay_ms(delay_ms); + #endif +} + +void epaperdisplay_epaper_core_wait_for_busy(epaperdisplay_epaper_core_t *self) { + if (self->busy.base.type == &mp_type_NoneType) { + return; + } + const uint64_t deadline = display_wait_deadline(self); + while (common_hal_digitalio_digitalinout_get_value(&self->busy) == self->busy_state && + !epaperdisplay_epaper_core_interrupted(self)) { + if (deadline != 0 && supervisor_ticks_ms64() > deadline) { + return; + } + RUN_BACKGROUND_TASKS; + port_task_yield(); + } +} + +// True if every command went out. Lag drive counts an update only if its last command did. +bool epaperdisplay_epaper_core_send_command_sequence(epaperdisplay_epaper_core_t *self, + bool should_wait_for_busy, const uint8_t *sequence, uint32_t sequence_len) { + uint32_t i = 0; + while (i < sequence_len) { + const uint8_t *cmd = sequence + i; + uint8_t data_size = *(cmd + 1); + bool delay = (data_size & DELAY) != 0; + const uint8_t *data = cmd + 2; + data_size &= ~DELAY; + if (self->two_byte_sequence_length) { + data_size = ((data_size & ~DELAY) << 8) + *(cmd + 2); + data = cmd + 3; + } + bool have_bus; + const uint64_t deadline = display_wait_deadline(self); + while (!(have_bus = displayio_display_bus_begin_transaction(&self->bus)) && + !epaperdisplay_epaper_core_interrupted(self) && (deadline == 0 || supervisor_ticks_ms64() <= deadline)) { + RUN_BACKGROUND_TASKS; + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (!have_bus && self->lag.frames > 0) { + return false; + } + self->lag.bus_held = have_bus; + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + const bool sent = display_send_command(self, cmd, data, data_size); + displayio_display_bus_end_transaction(&self->bus); + #if CIRCUITPY_EPAPERDISPLAY_FAST + self->lag.bus_held = false; + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + if (!sent) { + return false; + } + uint16_t delay_length_ms = 0; + if (delay) { + data_size++; + delay_length_ms = *(cmd + 1 + data_size + self->two_byte_sequence_length); + if (delay_length_ms == 255) { + delay_length_ms = 500; + } + } + epaperdisplay_epaper_core_delay_ms(self, delay_length_ms); + if (should_wait_for_busy) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->lag.frames > 0) { + epaperdisplay_epaper_core_wait_for_update_start(self); + } + #endif + epaperdisplay_epaper_core_wait_for_busy(self); + } + #if !CIRCUITPY_EPAPERDISPLAY_FAST + if (mp_hal_is_interrupted()) { + return true; + } + #endif + i += 2 + data_size; + if (self->two_byte_sequence_length) { + i++; + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (epaperdisplay_epaper_core_interrupted(self)) { + return i >= sequence_len; + } + #endif + } + return true; +} + +void epaperdisplay_epaper_core_change_refresh_mode_parameters(epaperdisplay_epaper_core_t *self, + mp_buffer_info_t *start_sequence, mp_buffer_info_t *refresh_sequence, float seconds_per_frame) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->lag.frames > 0) { + // Finish the drive with the waveform that started it, and rewrite both planes after. + nlr_buf_t nlr; + if (nlr_push(&nlr) == 0) { + epaperdisplay_lag_flush(self); + epaperdisplay_epaper_core_wait_for_busy(self); + nlr_pop(); + } else { + epaperdisplay_lag_raise(self, nlr.ret_val); + } + if (self->lag.settle > 0 || self->lag.commit != LAG_COMMIT_NONE) { + // Still owed: keep the mode that started it. + if (!mp_hal_is_interrupted()) { + mp_raise_RuntimeError_varg(MP_ERROR_TEXT("%q in use"), MP_QSTR_display_bus); + } + return; + } + self->lag.force_full = true; + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + self->start_sequence = (uint8_t *)start_sequence->buf; + self->start_sequence_len = start_sequence->len; + #if CIRCUITPY_EPAPERDISPLAY_FAST + // NULL keeps the current refresh sequence. + if (refresh_sequence != NULL) { + self->refresh_sequence = (uint8_t *)refresh_sequence->buf; + self->refresh_sequence_len = refresh_sequence->len; + } + #endif + self->milliseconds_per_frame = seconds_per_frame * 1000; + #if CIRCUITPY_EPAPERDISPLAY_FAST + self->needs_start = true; + #endif +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +// For a panel kept awake. Ctrl-C raises from a send in progress, and that transaction is still +// open. The caller still has things to do first, so the interrupt raises later. +void epaperdisplay_epaper_core_send_stop_sequence_guarded(epaperdisplay_epaper_core_t *self) { + nlr_buf_t nlr; + if (nlr_push(&nlr) == 0) { + epaperdisplay_epaper_core_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); + nlr_pop(); + } else { + if (!displayio_display_bus_is_free(&self->bus)) { + displayio_display_bus_end_transaction(&self->bus); + } + mp_sched_exception(nlr.ret_val); + } +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +uint32_t epaperdisplay_epaper_core_get_time_to_refresh(epaperdisplay_epaper_core_t *self) { + if (self->core.last_refresh == 0) { + return 0; + } + // Refresh at seconds per frame rate. + uint32_t elapsed_time = supervisor_ticks_ms64() - self->core.last_refresh; + if (elapsed_time > self->milliseconds_per_frame) { + return 0; + } + return self->milliseconds_per_frame - elapsed_time; +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +// False if the panel is still updating when the wait is over. +bool epaperdisplay_epaper_core_wait_for_update_end(epaperdisplay_epaper_core_t *self) { + epaperdisplay_epaper_core_wait_for_update_start(self); + const uint64_t deadline = supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; + bool busy; + while ((busy = common_hal_digitalio_digitalinout_get_value(&self->busy) == self->busy_state) && + !mp_hal_is_interrupted() && supervisor_ticks_ms64() <= deadline) { + RUN_BACKGROUND_TASKS; + port_task_yield(); + } + return !busy; +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +mp_obj_t epaperdisplay_epaper_core_get_bus(epaperdisplay_epaper_core_t *self) { + return self->bus.bus; +} + +uint16_t epaperdisplay_epaper_core_get_rotation(epaperdisplay_epaper_core_t *self) { + return self->core.rotation; +} + +mp_obj_t epaperdisplay_epaper_core_get_root_group(epaperdisplay_epaper_core_t *self) { + if (self->core.current_group == NULL) { + return mp_const_none; + } + return self->core.current_group; +} + +void epaperdisplay_epaper_core_background(epaperdisplay_epaper_core_t *self) { + if (self->refreshing) { + bool refresh_done = false; + if (self->busy.base.type == &digitalio_digitalinout_type) { + bool busy = common_hal_digitalio_digitalinout_get_value(&self->busy); + refresh_done = busy != self->busy_state; + } else { + refresh_done = supervisor_ticks_ms64() - self->core.last_refresh > self->refresh_time; + } + if (refresh_done) { + supervisor_disable_tick(); + self->refreshing = false; + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (!self->fast) { + // Run stop sequence but don't wait for busy because busy is set when sleeping. + epaperdisplay_epaper_core_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); + } + #else + // Run stop sequence but don't wait for busy because busy is set when sleeping. + epaperdisplay_epaper_core_send_command_sequence(self, false, self->stop_sequence, self->stop_sequence_len); + #endif + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + else { + epaperdisplay_lag_give_up_if_stuck(self); + } + #endif + } +} + +bool epaperdisplay_epaper_core_get_busy(epaperdisplay_epaper_core_t *self) { + epaperdisplay_epaper_core_background(self); + return self->refreshing; +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_epaper_core_prepare_release(epaperdisplay_epaper_core_t *self) { + if (self->lag.frames == 0 || (!self->awake && !self->lag.state_lost)) { + return; + } + const uint64_t deadline = supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; + while (!displayio_display_bus_is_free(&self->bus)) { + mp_handle_pending(true); + if (supervisor_ticks_ms64() > deadline) { + mp_raise_RuntimeError_varg(MP_ERROR_TEXT("%q in use"), MP_QSTR_display_bus); + } + RUN_BACKGROUND_TASKS; + } +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_epaper_core_end_held_bus(epaperdisplay_epaper_core_t *self) { + // The VM is over, so whatever holds the bus can never let it go: end it here. + if (self->fast && !displayio_display_bus_is_free(&self->bus)) { + displayio_display_bus_end_transaction(&self->bus); + self->lag.bus_held = false; + } +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +void epaperdisplay_epaper_core_collect_ptrs(epaperdisplay_epaper_core_t *self) { + displayio_display_core_collect_ptrs(&self->core); + displayio_display_bus_collect_ptrs(&self->bus); + gc_collect_ptr((void *)self->start_sequence); + gc_collect_ptr((void *)self->stop_sequence); + gc_collect_ptr((void *)self->refresh_sequence); + #if CIRCUITPY_EPAPERDISPLAY_FAST + gc_collect_ptr((void *)self->clean_sequence); + gc_collect_ptr(self->lag.held_exception); + #endif // CIRCUITPY_EPAPERDISPLAY_FAST +} diff --git a/shared-module/epaperdisplay/epaper_core.h b/shared-module/epaperdisplay/epaper_core.h new file mode 100644 index 00000000000..6a1fa317ef2 --- /dev/null +++ b/shared-module/epaperdisplay/epaper_core.h @@ -0,0 +1,136 @@ +// This file is part of the CircuitPython project: https://circuitpython.org +// +// SPDX-FileCopyrightText: Copyright (c) 2026 Adafruit Industries LLC +// +// SPDX-License-Identifier: MIT + +#pragma once + +#include "common-hal/digitalio/DigitalInOut.h" +#include "shared-module/displayio/area.h" +#include "shared-module/displayio/bus_core.h" +#include "shared-module/displayio/display_core.h" + +// Defined by the selected implementation; only the pointer is needed by the common core. +typedef struct epaperdisplay_epaperdisplay_obj_t epaperdisplay_epaperdisplay_obj_t; +typedef struct epaperdisplay_construct_args_t epaperdisplay_construct_args_t; + +#if CIRCUITPY_EPAPERDISPLAY_FAST +// Lag drive state shared by both backends. FAST writes the last frame to the previous RAM, so each +// changed pixel is driven once. Lag writes the frame from frames refreshes ago, so a changed pixel +// is driven frames times, the same number each way. The ring is only used when frames > 0. +typedef struct { + uint8_t **slots; + uint64_t busy_deadline; // When not 0, stop waiting for BUSY or the bus after this tick. + // What interrupted while interrupts are held. A send can raise one from the heap, so it is + // marked in epaperdisplay_epaper_core_collect_ptrs(). + mp_obj_t held_exception; + bool holding_interrupts; + bool bus_held; // Inside a transaction, so an exception must end it. + bool last_try; // Shutdown's reset after a stuck wait: the deadline is not renewed. + bool state_lost; // What the panel received is unknown, so it needs a stored-waveform refresh. + bool slot_overwriting; // The oldest frame in the ring is being replaced. + bool commit_drive; // The owed step has pixels to drive. + uint8_t commit; // What the newest step in the ring still has to send. + displayio_area_t commit_box; + uint64_t update_start; // When the running update was sent. + // What each of the last frames + 1 steps rendered, in pixels. + displayio_area_t *boxes; + uint32_t slot_size; + uint16_t stride; + uint16_t rows; + uint8_t frames; + uint8_t head; // Slot of the newest frame. + uint8_t box_index; // Entry in boxes for this step. + uint8_t settle; // Steps owed until every plane pair matches the newest frame. + bool force_full; // Write everything on the next step. +} epaperdisplay_lag_t; +#endif + +// State and operations shared by the legacy and LVGL EPaperDisplay implementations. Keeping this +// separate from epaperdisplay_epaperdisplay_obj_t lets the common code and lag drive operate +// without knowing either implementation's object layout. +typedef struct { + displayio_display_core_t core; + displayio_display_bus_t bus; + digitalio_digitalinout_obj_t busy; + uint32_t milliseconds_per_frame; + const uint8_t *start_sequence; + const uint8_t *stop_sequence; + const uint8_t *refresh_sequence; + uint16_t start_sequence_len; + uint16_t stop_sequence_len; + uint16_t refresh_sequence_len; + uint16_t start_up_time_ms; + uint16_t refresh_time; + uint16_t write_black_ram_command; + uint16_t write_color_ram_command; + #if CIRCUITPY_EPAPERDISPLAY_FAST + uint16_t write_previous_ram_command; + #endif + uint8_t hue; + bool busy_state; + bool black_bits_inverted; + bool color_bits_inverted; + bool refreshing; + bool grayscale; + bool acep; + bool two_byte_sequence_length; + #if CIRCUITPY_EPAPERDISPLAY_FAST + bool fast; + bool awake; + bool needs_start; // update_refresh_mode() changed the start sequence. + #endif + display_chip_select_behavior_t chip_select; + + #if CIRCUITPY_EPAPERDISPLAY_FAST + const uint8_t *clean_sequence; + uint32_t clean_sequence_len; + epaperdisplay_lag_t lag; + epaperdisplay_epaperdisplay_obj_t *display; + #endif +} epaperdisplay_epaper_core_t; + +void epaperdisplay_epaper_core_construct(epaperdisplay_epaper_core_t *self, + const epaperdisplay_construct_args_t *args); + +uint16_t epaperdisplay_epaper_core_get_width(epaperdisplay_epaper_core_t *self); +uint16_t epaperdisplay_epaper_core_get_height(epaperdisplay_epaper_core_t *self); +uint16_t epaperdisplay_epaper_core_get_rotation(epaperdisplay_epaper_core_t *self); +mp_obj_t epaperdisplay_epaper_core_get_root_group(epaperdisplay_epaper_core_t *self); +mp_obj_t epaperdisplay_epaper_core_get_bus(epaperdisplay_epaper_core_t *self); +uint32_t epaperdisplay_epaper_core_get_time_to_refresh(epaperdisplay_epaper_core_t *self); +bool epaperdisplay_epaper_core_get_busy(epaperdisplay_epaper_core_t *self); +void epaperdisplay_epaper_core_background(epaperdisplay_epaper_core_t *self); +void epaperdisplay_epaper_core_change_refresh_mode_parameters(epaperdisplay_epaper_core_t *self, + mp_buffer_info_t *start_sequence, mp_buffer_info_t *refresh_sequence, float seconds_per_frame); +void epaperdisplay_epaper_core_collect_ptrs(epaperdisplay_epaper_core_t *self); + +// Waits for BUSY to clear or an interrupt. On a lag display the wait is bounded. +void epaperdisplay_epaper_core_wait_for_busy(epaperdisplay_epaper_core_t *self); +// Sends a start, stop or refresh sequence. True if every command went out. +bool epaperdisplay_epaper_core_send_command_sequence(epaperdisplay_epaper_core_t *self, + bool should_wait_for_busy, const uint8_t *sequence, uint32_t sequence_len); +// Delays, but while interrupts are held an interrupt doesn't cut it short. +void epaperdisplay_epaper_core_delay_ms(epaperdisplay_epaper_core_t *self, uint32_t delay_ms); + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_epaper_core_prepare_release(epaperdisplay_epaper_core_t *self); +void epaperdisplay_epaper_core_end_held_bus(epaperdisplay_epaper_core_t *self); +void epaperdisplay_epaper_core_send_stop_sequence_guarded(epaperdisplay_epaper_core_t *self); +bool epaperdisplay_epaper_core_wait_for_update_end(epaperdisplay_epaper_core_t *self); +bool epaperdisplay_epaper_core_interrupted(epaperdisplay_epaper_core_t *self); +bool epaperdisplay_epaper_core_wait_for_update_start(epaperdisplay_epaper_core_t *self); +// Backend operations needed by lag drive. Implementations can use display to reach their own state. +void epaperdisplay_backend_full_area(epaperdisplay_epaper_core_t *self, displayio_area_t *area); +bool epaperdisplay_backend_clip_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + displayio_area_t *clipped); +void epaperdisplay_backend_render_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + uint8_t *frame, uint16_t frame_stride, bool white); +void epaperdisplay_backend_finish_refresh(epaperdisplay_epaper_core_t *self); +void epaperdisplay_backend_set_full_refresh(epaperdisplay_epaper_core_t *self, bool full_refresh); +void epaperdisplay_backend_set_refresh_in_progress(epaperdisplay_epaper_core_t *self, bool in_progress); +// Implemented by the selected backend. A fast display that is already awake skips the start +// sequence unless it changed. +void epaperdisplay_epaper_core_start_refresh(epaperdisplay_epaper_core_t *self); +#endif diff --git a/shared-module/epaperdisplay/lag_drive.c b/shared-module/epaperdisplay/lag_drive.c index 1e0eb7e9f98..4ecbe50f242 100644 --- a/shared-module/epaperdisplay/lag_drive.c +++ b/shared-module/epaperdisplay/lag_drive.c @@ -4,7 +4,7 @@ // // SPDX-License-Identifier: MIT -#include "shared-bindings/epaperdisplay/EPaperDisplay.h" +#include "shared-module/epaperdisplay/lag_drive.h" #if CIRCUITPY_EPAPERDISPLAY_FAST @@ -12,7 +12,6 @@ #include "py/runtime.h" #include "shared/runtime/interrupt_char.h" #include "shared-bindings/digitalio/DigitalInOut.h" -#include "shared-module/epaperdisplay/lag_drive.h" #include "supervisor/port_heap.h" #include "supervisor/shared/tick.h" @@ -23,22 +22,46 @@ // a reset, so a RAM write ends with this. Lag drive is only for displays where it is harmless. #define LAG_RAM_COMMIT_COMMAND 0x7f -static void lag_after_raise(epaperdisplay_epaperdisplay_obj_t *self); -static bool lag_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, bool full); +static void lag_after_raise(epaperdisplay_epaper_core_t *self); +static bool lag_clean(epaperdisplay_epaper_core_t *self, uint8_t frames, bool full); + +static bool lag_clip_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + displayio_area_t *clipped) { + return epaperdisplay_backend_clip_area(self, area, clipped); +} + +// Clip the whole panel to whole bytes of pixels. Filling a plane or forcing a full step uses it. +static bool lag_full_area(epaperdisplay_epaper_core_t *self, displayio_area_t *area) { + displayio_area_t whole; + epaperdisplay_backend_full_area(self, &whole); + return epaperdisplay_backend_clip_area(self, &whole, area); +} + +static void lag_finish_refresh(epaperdisplay_epaper_core_t *self) { + epaperdisplay_backend_finish_refresh(self); +} + +static void lag_set_full_refresh(epaperdisplay_epaper_core_t *self, bool full_refresh) { + epaperdisplay_backend_set_full_refresh(self, full_refresh); +} + +static void lag_set_refresh_in_progress(epaperdisplay_epaper_core_t *self, bool in_progress) { + epaperdisplay_backend_set_refresh_in_progress(self, in_progress); +} -static bool lag_deadline_passed(epaperdisplay_epaperdisplay_obj_t *self) { +static bool lag_deadline_passed(epaperdisplay_epaper_core_t *self) { return self->lag.busy_deadline != 0 && supervisor_ticks_ms64() > self->lag.busy_deadline; } -static void lag_hold_interrupts(epaperdisplay_epaperdisplay_obj_t *self) { +static void lag_hold_interrupts(epaperdisplay_epaper_core_t *self) { self->lag.holding_interrupts = true; if (self->lag.busy_deadline == 0) { self->lag.busy_deadline = supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; } - epaperdisplay_epaperdisplay_interrupted(self); + epaperdisplay_epaper_core_interrupted(self); } -void epaperdisplay_lag_release_interrupts(epaperdisplay_epaperdisplay_obj_t *self) { +void epaperdisplay_lag_release_interrupts(epaperdisplay_epaper_core_t *self) { if (!self->lag.holding_interrupts) { return; } @@ -53,7 +76,7 @@ void epaperdisplay_lag_release_interrupts(epaperdisplay_epaperdisplay_obj_t *sel // A transfer in progress raises when something interrupts. On a port with async SPI that can be // any transfer, however short. While holding, that returns false: the transfer stopped partway, // so the caller goes back to where the RAM or command can start again. -bool epaperdisplay_lag_send(epaperdisplay_epaperdisplay_obj_t *self, display_byte_type_t type, +bool epaperdisplay_lag_send(epaperdisplay_epaper_core_t *self, display_byte_type_t type, const uint8_t *data, uint32_t length) { if (!self->lag.holding_interrupts) { self->bus.send(self->bus.bus, type, self->chip_select, data, length); @@ -66,12 +89,12 @@ bool epaperdisplay_lag_send(epaperdisplay_epaperdisplay_obj_t *self, display_byt return true; } MP_STATE_THREAD(mp_pending_exception) = nlr.ret_val; - epaperdisplay_epaperdisplay_interrupted(self); + epaperdisplay_epaper_core_interrupted(self); return false; } // set_region_to_update() has its own transaction, so a raise from it leaves the bus locked. -static bool lag_set_region(epaperdisplay_epaperdisplay_obj_t *self, displayio_area_t *box) { +static bool lag_set_region(epaperdisplay_epaper_core_t *self, displayio_area_t *box) { for (volatile uint8_t attempt = 0; attempt < 3; attempt++) { // It skips its commands if it can't get the bus, which would leave the old window. if (!displayio_display_bus_is_free(&self->bus)) { @@ -95,7 +118,7 @@ static bool lag_set_region(epaperdisplay_epaperdisplay_obj_t *self, displayio_ar nlr_jump(nlr.ret_val); } MP_STATE_THREAD(mp_pending_exception) = nlr.ret_val; - epaperdisplay_epaperdisplay_interrupted(self); + epaperdisplay_epaper_core_interrupted(self); } return false; } @@ -125,9 +148,11 @@ static bool lag_set_region(epaperdisplay_epaperdisplay_obj_t *self, displayio_ar // equal outside the box: a byte there is either outside the last box too, so equal by induction, // or was last written with frames that have not changed there since. -void epaperdisplay_lag_construct(epaperdisplay_epaperdisplay_obj_t *self, uint8_t lag_frames) { - self->lag.stride = (self->core.area.x2 + 7) / 8; - self->lag.rows = self->core.area.y2; +void epaperdisplay_lag_construct(epaperdisplay_epaper_core_t *self, mp_obj_base_t *base, uint8_t lag_frames) { + displayio_area_t whole; + epaperdisplay_backend_full_area(self, &whole); + self->lag.stride = (whole.x2 + 7) / 8; + self->lag.rows = whole.y2; self->lag.slot_size = self->lag.stride * self->lag.rows; self->lag.frames = lag_frames; self->lag.head = 0; @@ -148,7 +173,7 @@ void epaperdisplay_lag_construct(epaperdisplay_epaperdisplay_obj_t *self, uint8_ } if (!ok) { epaperdisplay_lag_free(self); - self->base.type = &mp_type_NoneType; + base->type = &mp_type_NoneType; m_malloc_fail(self->lag.slot_size); } // History starts white, the state a cleared panel is in. @@ -157,7 +182,7 @@ void epaperdisplay_lag_construct(epaperdisplay_epaperdisplay_obj_t *self, uint8_ } } -void epaperdisplay_lag_free(epaperdisplay_epaperdisplay_obj_t *self) { +void epaperdisplay_lag_free(epaperdisplay_epaper_core_t *self) { if (self->lag.slots != NULL) { for (uint8_t i = 0; i < self->lag.frames; i++) { if (self->lag.slots[i] != NULL) { @@ -170,59 +195,21 @@ void epaperdisplay_lag_free(epaperdisplay_epaperdisplay_obj_t *self) { self->lag.frames = 0; } -static void lag_render_area(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area, uint8_t *frame, bool white) { +static void lag_render_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, uint8_t *frame, bool white) { displayio_area_t clipped; - if (!displayio_display_core_clip_area(&self->core, area, &clipped)) { + if (!lag_clip_area(self, area, &clipped)) { return; } - if (white) { - for (int16_t row = clipped.y1; row < clipped.y2; row++) { - memset(frame + row * self->lag.stride + clipped.x1 / 8, self->black_bits_inverted ? 0x00 : 0xff, - displayio_area_width(&clipped) / 8); - } - return; - } - uint16_t width = displayio_area_width(&clipped); - uint16_t bytes_per_row = width / 8; - uint16_t rows_per_buffer = MAX(1, 128 * 32 / width); - size_t words = (rows_per_buffer * width + 31) / 32; - uint32_t buffer[words]; - uint32_t mask[words]; - - self->core.colorspace.grayscale = true; - self->core.colorspace.grayscale_bit = 7; - for (int16_t y = clipped.y1; y < clipped.y2; y += rows_per_buffer) { - displayio_area_t subrectangle = { - .x1 = clipped.x1, - .y1 = y, - .x2 = clipped.x2, - .y2 = MIN(y + rows_per_buffer, clipped.y2), - }; - memset(mask, 0, sizeof(mask)); - memset(buffer, 0, sizeof(buffer)); - displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer); - if (self->black_bits_inverted) { - for (size_t k = 0; k < words; k++) { - buffer[k] = ~buffer[k]; - } - } - const uint8_t *in = (const uint8_t *)buffer; - for (int16_t row = subrectangle.y1; row < subrectangle.y2; row++) { - memcpy(frame + row * self->lag.stride + clipped.x1 / 8, in, bytes_per_row); - in += bytes_per_row; - } - // Run background tasks like a regular refresh does. - RUN_BACKGROUND_TASKS; - } + epaperdisplay_backend_render_area(self, &clipped, frame, self->lag.stride, white); } -static bool lag_send_ram_commit(epaperdisplay_epaperdisplay_obj_t *self) { +static bool lag_send_ram_commit(epaperdisplay_epaper_core_t *self) { const uint8_t command = LAG_RAM_COMMIT_COMMAND; return epaperdisplay_lag_send(self, DISPLAY_COMMAND, &command, 1); } // Rows are gathered so a narrow box doesn't cost one SPI transfer per row. -static bool lag_send_plane(epaperdisplay_epaperdisplay_obj_t *self, uint8_t command, const uint8_t *frame, const displayio_area_t *box) { +static bool lag_send_plane(epaperdisplay_epaper_core_t *self, uint8_t command, const uint8_t *frame, const displayio_area_t *box) { if (!epaperdisplay_lag_send(self, DISPLAY_COMMAND, &command, 1)) { return false; } @@ -234,6 +221,13 @@ static bool lag_send_plane(epaperdisplay_epaperdisplay_obj_t *self, uint8_t comm uint8_t chunk[512]; size_t used = 0; for (int16_t y = box->y1; y < box->y2; y++) { + if (bytes_per_row > sizeof(chunk)) { + if (!epaperdisplay_lag_send(self, DISPLAY_DATA, in, bytes_per_row)) { + return false; + } + in += self->lag.stride; + continue; + } if (used + bytes_per_row > sizeof(chunk)) { if (!epaperdisplay_lag_send(self, DISPLAY_DATA, chunk, used)) { return false; @@ -248,7 +242,7 @@ static bool lag_send_plane(epaperdisplay_epaperdisplay_obj_t *self, uint8_t comm } // A send stopped by a held interrupt leaves the RAM pointer partway, so start over from the region. -static bool lag_write_plane(epaperdisplay_epaperdisplay_obj_t *self, uint8_t command, const uint8_t *frame, displayio_area_t *box) { +static bool lag_write_plane(epaperdisplay_epaper_core_t *self, uint8_t command, const uint8_t *frame, displayio_area_t *box) { for (uint8_t attempt = 0; attempt < 3; attempt++) { if (!lag_set_region(self, box) || !displayio_display_bus_begin_transaction(&self->bus)) { return false; @@ -267,7 +261,7 @@ static bool lag_write_plane(epaperdisplay_epaperdisplay_obj_t *self, uint8_t com // Finish a step whose frame is already in the ring: frame N to its plane, then the update. Each // part stays owed until it has gone out, so a pixel is only counted as driven if it was. Interrupts // wait, since a send they stop can't be told from one that arrived. False if the bus can't be had. -static bool lag_commit_step(epaperdisplay_epaperdisplay_obj_t *self) { +static bool lag_commit_step(epaperdisplay_epaper_core_t *self) { const bool was_holding = self->lag.holding_interrupts; lag_hold_interrupts(self); bool ok = true; @@ -280,9 +274,9 @@ static bool lag_commit_step(epaperdisplay_epaperdisplay_obj_t *self) { if (ok && self->lag.commit == LAG_COMMIT_ACTIVATE) { // Nothing can differ when the box is empty, so an update would only take time. if (self->lag.commit_drive) { - ok = epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->refresh_sequence, self->refresh_sequence_len); + ok = epaperdisplay_epaper_core_send_command_sequence(self, false, self->refresh_sequence, self->refresh_sequence_len); if (ok) { - epaperdisplay_epaperdisplay_wait_for_update_start(self); + epaperdisplay_epaper_core_wait_for_update_start(self); supervisor_enable_tick(); self->refreshing = true; self->lag.update_start = supervisor_ticks_ms64(); @@ -302,20 +296,31 @@ static bool lag_commit_step(epaperdisplay_epaperdisplay_obj_t *self) { // NULL) over its slot, or white in those areas without rendering, to the other. The history // doesn't advance if the bus can't be had before the slot is touched, so a retry does the same // step. Once it has, the step is owed and true is returned, whatever happens to the rest. -static bool lag_step(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas, bool white) { +static bool lag_step(epaperdisplay_epaper_core_t *self, const displayio_area_t *areas, + uint8_t area_count, bool white) { uint8_t lag = self->lag.frames; uint8_t next = (self->lag.head + 1) % lag; uint8_t *frame = self->lag.slots[next]; displayio_area_t *boxes = self->lag.boxes; uint8_t index = self->lag.box_index; + #if CIRCUITPY_DISPLAYIO_LVGL + bool changed = area_count > 0; + for (uint8_t i = 0; i < area_count; i++) { + displayio_area_t clipped; + if (lag_clip_area(self, &areas[i], &clipped)) { + displayio_area_union(&boxes[index], &clipped, &boxes[index]); + } + } + #else + (void)area_count; bool changed = areas != NULL; - for (const displayio_area_t *area = areas; area != NULL; area = area->next) { displayio_area_t clipped; - if (displayio_display_core_clip_area(&self->core, area, &clipped)) { + if (lag_clip_area(self, area, &clipped)) { displayio_area_union(&boxes[index], &clipped, &boxes[index]); } } + #endif // The oldest entry is lag steps back: only needed to make the planes equal again. uint8_t oldest = (index + 1) % (lag + 1); displayio_area_t drive_box = {0}; @@ -326,7 +331,9 @@ static bool lag_step(epaperdisplay_epaperdisplay_obj_t *self, const displayio_ar } displayio_area_t write_box; if (self->lag.force_full) { - displayio_display_core_clip_area(&self->core, &self->core.area, &write_box); + if (!lag_full_area(self, &write_box)) { + write_box = (displayio_area_t) {0}; + } } else { displayio_area_union(&drive_box, &boxes[oldest], &write_box); } @@ -347,9 +354,15 @@ static bool lag_step(epaperdisplay_epaperdisplay_obj_t *self, const displayio_ar out += self->lag.stride; } } + #if CIRCUITPY_DISPLAYIO_LVGL + for (uint8_t i = 0; i < area_count; i++) { + lag_render_area(self, &areas[i], frame, white); + } + #else for (const displayio_area_t *area = areas; area != NULL; area = area->next) { lag_render_area(self, area, frame, white); } + #endif // The slot no longer holds N-lag, so from here the step has to finish or that drive is lost. self->lag.slot_overwriting = false; self->lag.head = next; @@ -368,33 +381,43 @@ static bool lag_step(epaperdisplay_epaperdisplay_obj_t *self, const displayio_ar return true; } -static bool lag_refresh_unguarded(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas) { +static bool lag_refresh_unguarded(epaperdisplay_epaper_core_t *self, const displayio_area_t *areas, + uint8_t area_count) { + displayio_area_t whole; if (!self->awake || self->lag.state_lost) { // The panel may still hold anything, including ghosts from a run that lost power. if (!lag_clean(self, 0, true) || mp_hal_is_interrupted()) { return false; } - areas = &self->core.area; + if (!lag_full_area(self, &whole)) { + return false; + } + areas = &whole; + area_count = 1; } if (self->lag.commit != LAG_COMMIT_NONE) { // The areas stay marked, so the next refresh draws them. return lag_commit_step(self); } + #if CIRCUITPY_DISPLAYIO_LVGL + if (area_count == 0 && self->lag.settle == 0) { + #else if (areas == NULL && self->lag.settle == 0) { + #endif return true; } if (self->needs_start) { lag_hold_interrupts(self); - epaperdisplay_epaperdisplay_start_refresh(self); + epaperdisplay_epaper_core_start_refresh(self); epaperdisplay_lag_release_interrupts(self); } else { - epaperdisplay_epaperdisplay_start_refresh(self); + epaperdisplay_epaper_core_start_refresh(self); } - bool ok = !self->needs_start && lag_step(self, areas, false); + bool ok = !self->needs_start && lag_step(self, areas, area_count, false); if (ok) { - displayio_display_core_finish_refresh(&self->core); + lag_finish_refresh(self); } else { - self->core.refresh_in_progress = false; + lag_set_refresh_in_progress(self, false); } return ok; } @@ -402,7 +425,7 @@ static bool lag_refresh_unguarded(epaperdisplay_epaperdisplay_obj_t *self, const // An update takes far less than the limit, so a panel still BUSY is stuck, and only a reset can // help. That has to wait for the next refresh or the shutdown, since the bus may be in use here. // Until then a script polling busy can go on. -void epaperdisplay_lag_give_up_if_stuck(epaperdisplay_epaperdisplay_obj_t *self) { +void epaperdisplay_lag_give_up_if_stuck(epaperdisplay_epaper_core_t *self) { if (self->lag.frames > 0 && !self->lag.holding_interrupts && supervisor_ticks_ms64() - self->lag.update_start > EPAPER_WAIT_TIMEOUT_MS) { supervisor_disable_tick(); @@ -414,43 +437,44 @@ void epaperdisplay_lag_give_up_if_stuck(epaperdisplay_epaperdisplay_obj_t *self) // False if the update is still running: interrupted, or the panel is stuck. RAM writes and a reset // would land on that update, so nothing more can be sent. -static bool lag_wait_idle(epaperdisplay_epaperdisplay_obj_t *self) { - epaperdisplay_epaperdisplay_wait_for_busy(self); +static bool lag_wait_idle(epaperdisplay_epaper_core_t *self) { + epaperdisplay_epaper_core_wait_for_busy(self); return common_hal_digitalio_digitalinout_get_value(&self->busy) != self->busy_state; } // The deadline bounds each piece of work, not the whole drive, which can be 32 updates and a clean. // Only called after progress, so a bus that is never free still runs out. -static void lag_renew_deadline(epaperdisplay_epaperdisplay_obj_t *self) { +static void lag_renew_deadline(epaperdisplay_epaper_core_t *self) { if (self->lag.busy_deadline != 0 && !self->lag.last_try) { self->lag.busy_deadline = supervisor_ticks_ms64() + EPAPER_WAIT_TIMEOUT_MS; } } // Give every changed pixel the rest of its drive so the panel is left DC balanced. -void epaperdisplay_lag_flush(epaperdisplay_epaperdisplay_obj_t *self) { +void epaperdisplay_lag_flush(epaperdisplay_epaper_core_t *self) { if (self->lag.frames == 0 || !self->awake) { return; } while (self->lag.settle > 0 || self->lag.commit != LAG_COMMIT_NONE) { - if (!lag_wait_idle(self) || epaperdisplay_epaperdisplay_interrupted(self)) { + if (!lag_wait_idle(self) || epaperdisplay_epaper_core_interrupted(self)) { return; } if (self->refreshing) { supervisor_disable_tick(); self->refreshing = false; } - if (self->lag.commit != LAG_COMMIT_NONE ? !lag_commit_step(self) : !lag_step(self, NULL, false)) { + if (self->lag.commit != LAG_COMMIT_NONE ? !lag_commit_step(self) : !lag_step(self, NULL, 0, false)) { return; } lag_renew_deadline(self); } } -bool epaperdisplay_lag_refresh(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas) { +bool epaperdisplay_lag_refresh(epaperdisplay_epaper_core_t *self, const displayio_area_t *areas, + uint8_t area_count) { nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { - bool ok = lag_refresh_unguarded(self, areas); + bool ok = lag_refresh_unguarded(self, areas, area_count); nlr_pop(); return ok; } @@ -458,7 +482,7 @@ bool epaperdisplay_lag_refresh(epaperdisplay_epaperdisplay_obj_t *self, const di } // Fill a whole RAM plane with one color from a small buffer. -static bool lag_send_solid(epaperdisplay_epaperdisplay_obj_t *self, uint8_t command, bool white) { +static bool lag_send_solid(epaperdisplay_epaper_core_t *self, uint8_t command, bool white) { if (!epaperdisplay_lag_send(self, DISPLAY_COMMAND, &command, 1)) { return false; } @@ -475,9 +499,11 @@ static bool lag_send_solid(epaperdisplay_epaperdisplay_obj_t *self, uint8_t comm return lag_send_ram_commit(self); } -static bool lag_write_solid(epaperdisplay_epaperdisplay_obj_t *self, uint8_t command, bool white) { +static bool lag_write_solid(epaperdisplay_epaper_core_t *self, uint8_t command, bool white) { displayio_area_t box; - displayio_display_core_clip_area(&self->core, &self->core.area, &box); + if (!lag_full_area(self, &box)) { + return true; + } for (uint8_t attempt = 0; attempt < 3; attempt++) { if (!lag_set_region(self, &box) || !displayio_display_bus_begin_transaction(&self->bus)) { return false; @@ -495,13 +521,13 @@ static bool lag_write_solid(epaperdisplay_epaperdisplay_obj_t *self, uint8_t com // Updates with the planes as they are. Background tasks run, so a video keeps decoding. Returns how // many went out. -static uint8_t lag_wipe_phase(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames) { +static uint8_t lag_wipe_phase(epaperdisplay_epaper_core_t *self, uint8_t frames) { for (uint8_t i = 0; i < frames; i++) { lag_renew_deadline(self); - if (!epaperdisplay_epaperdisplay_send_command_sequence(self, false, self->refresh_sequence, self->refresh_sequence_len)) { + if (!epaperdisplay_epaper_core_send_command_sequence(self, false, self->refresh_sequence, self->refresh_sequence_len)) { return i; } - epaperdisplay_epaperdisplay_wait_for_update_start(self); + epaperdisplay_epaper_core_wait_for_update_start(self); if (!lag_wait_idle(self)) { return i + 1; // A stuck panel: writes would be dropped, so nothing more can help. } @@ -512,7 +538,7 @@ static uint8_t lag_wipe_phase(epaperdisplay_epaperdisplay_obj_t *self, uint8_t f // Both planes must be white. Every pixel gets frames toward black, then the same number toward white, // and both planes are white again at the end. The caller holds interrupts, so the phases stay // together. If that can't be done the drive is unknown, and only a stored-waveform refresh is safe. -static void lag_wipe(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames) { +static void lag_wipe(epaperdisplay_epaper_core_t *self, uint8_t frames) { bool ok = lag_write_solid(self, self->write_black_ram_command, false); if (ok) { const uint8_t toward_black = lag_wipe_phase(self, frames); @@ -531,9 +557,9 @@ static void lag_wipe(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames) { // A normal step to white, then the owed steps. Everything changed so far gets all of its drive, // and the ring and both planes end up white with nothing owed. False if interrupted first, with // the drive still owed. -static bool lag_to_white(epaperdisplay_epaperdisplay_obj_t *self) { +static bool lag_to_white(epaperdisplay_epaper_core_t *self) { while (true) { - if (!lag_wait_idle(self) || epaperdisplay_epaperdisplay_interrupted(self)) { + if (!lag_wait_idle(self) || epaperdisplay_epaper_core_interrupted(self)) { return false; } if (self->refreshing) { @@ -547,9 +573,11 @@ static bool lag_to_white(epaperdisplay_epaperdisplay_obj_t *self) { return false; } } - displayio_area_t whole = self->core.area; - whole.next = NULL; - if (!lag_step(self, &whole, true)) { + displayio_area_t whole; + if (!lag_full_area(self, &whole)) { + return false; + } + if (!lag_step(self, &whole, 1, true)) { return false; } lag_renew_deadline(self); @@ -567,12 +595,12 @@ static bool lag_to_white(epaperdisplay_epaperdisplay_obj_t *self) { // An exception came out of a bus send (Ctrl-C during a long transfer raises) or a render. Without // this the bus stays locked and chip select low, and everything after waits for it. The next // step writes all of both planes, since this one may have stopped partway through either. -static void lag_abandon_step(epaperdisplay_epaperdisplay_obj_t *self) { +static void lag_abandon_step(epaperdisplay_epaper_core_t *self) { if (self->lag.bus_held) { displayio_display_bus_end_transaction(&self->bus); self->lag.bus_held = false; } - self->core.refresh_in_progress = false; + lag_set_refresh_in_progress(self, false); self->lag.force_full = true; if (self->lag.slot_overwriting) { // The drive it held can't be sent any more. @@ -581,13 +609,13 @@ static void lag_abandon_step(epaperdisplay_epaperdisplay_obj_t *self) { } } -static void lag_after_raise(epaperdisplay_epaperdisplay_obj_t *self) { +static void lag_after_raise(epaperdisplay_epaper_core_t *self) { lag_abandon_step(self); epaperdisplay_lag_release_interrupts(self); } // Raise once: what was held, if anything, instead of both that and this. -MP_NORETURN void epaperdisplay_lag_raise(epaperdisplay_epaperdisplay_obj_t *self, mp_obj_t raised) { +MP_NORETURN void epaperdisplay_lag_raise(epaperdisplay_epaper_core_t *self, mp_obj_t raised) { if (self->lag.held_exception != MP_OBJ_NULL) { raised = self->lag.held_exception; self->lag.held_exception = MP_OBJ_NULL; @@ -596,11 +624,11 @@ MP_NORETURN void epaperdisplay_lag_raise(epaperdisplay_epaperdisplay_obj_t *self nlr_jump(raised); } -static bool lag_wake(epaperdisplay_epaperdisplay_obj_t *self) { +static bool lag_wake(epaperdisplay_epaper_core_t *self) { self->awake = false; self->bus.bus_reset(self->bus.bus); - epaperdisplay_epaperdisplay_delay_ms(self, self->start_up_time_ms); - if (!epaperdisplay_epaperdisplay_send_command_sequence(self, true, self->start_sequence, self->start_sequence_len)) { + epaperdisplay_epaper_core_delay_ms(self, self->start_up_time_ms); + if (!epaperdisplay_epaper_core_send_command_sequence(self, true, self->start_sequence, self->start_sequence_len)) { return false; } self->awake = true; @@ -610,10 +638,10 @@ static bool lag_wake(epaperdisplay_epaperdisplay_obj_t *self) { // What the panel received is unknown, so paying back could drive pixels the wrong way. Forget the // drive and let the stored waveform, which is balanced by itself, bring the panel to white. -static bool lag_recover(epaperdisplay_epaperdisplay_obj_t *self) { +static bool lag_recover(epaperdisplay_epaper_core_t *self) { // An update that may have started shouldn't be cut. A stuck panel has already been waited for. if (self->awake) { - epaperdisplay_epaperdisplay_wait_for_busy(self); + epaperdisplay_epaper_core_wait_for_busy(self); } if (!lag_wake(self) || !lag_wait_idle(self)) { return false; @@ -621,7 +649,7 @@ static bool lag_recover(epaperdisplay_epaperdisplay_obj_t *self) { lag_renew_deadline(self); if (!lag_write_solid(self, self->write_previous_ram_command, true) || !lag_write_solid(self, self->write_black_ram_command, true) || - !epaperdisplay_epaperdisplay_send_command_sequence(self, true, self->clean_sequence, self->clean_sequence_len) || + !epaperdisplay_epaper_core_send_command_sequence(self, true, self->clean_sequence, self->clean_sequence_len) || !lag_wait_idle(self)) { return false; } @@ -641,12 +669,12 @@ static bool lag_recover(epaperdisplay_epaperdisplay_obj_t *self) { } // A clean can't stop partway, so an interrupt raises when it ends. False if the bus can't be had. -static bool lag_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, bool full) { +static bool lag_clean(epaperdisplay_epaper_core_t *self, uint8_t frames, bool full) { if (!displayio_display_bus_is_free(&self->bus)) { return false; } lag_hold_interrupts(self); - self->core.full_refresh = true; + lag_set_full_refresh(self, true); bool ok; if (self->lag.state_lost) { ok = lag_recover(self); @@ -656,7 +684,7 @@ static bool lag_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, b if (ok && full) { lag_renew_deadline(self); self->lag.force_full = true; - ok = epaperdisplay_epaperdisplay_send_command_sequence(self, true, self->clean_sequence, self->clean_sequence_len) && lag_wait_idle(self); + ok = epaperdisplay_epaper_core_send_command_sequence(self, true, self->clean_sequence, self->clean_sequence_len) && lag_wait_idle(self); if (ok) { lag_renew_deadline(self); ok = lag_wake(self); @@ -671,7 +699,7 @@ static bool lag_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, b return ok; } -bool common_hal_epaperdisplay_epaperdisplay_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, bool full) { +bool epaperdisplay_epaper_core_clean(epaperdisplay_epaper_core_t *self, uint8_t frames, bool full) { nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { bool ok = lag_clean(self, frames, full); @@ -684,7 +712,7 @@ bool common_hal_epaperdisplay_epaperdisplay_clean(epaperdisplay_epaperdisplay_ob // Leave the panel white and balanced when the display goes away: release, or the end of the VM, // where nothing can catch an exception. Interrupts stay held until release_epaperdisplay() has sent // the stop sequence. All of it is bounded so a stuck panel can't hang shutdown. Doesn't allocate. -void epaperdisplay_lag_shutdown(epaperdisplay_epaperdisplay_obj_t *self) { +void epaperdisplay_lag_shutdown(epaperdisplay_epaper_core_t *self) { if (self->lag.frames == 0 || (!self->awake && !self->lag.state_lost)) { return; // Nothing was drawn. } @@ -700,7 +728,7 @@ void epaperdisplay_lag_shutdown(epaperdisplay_epaperdisplay_obj_t *self) { done = lag_recover(self); } else if (lag_to_white(self)) { lag_renew_deadline(self); - done = epaperdisplay_epaperdisplay_send_command_sequence(self, true, self->clean_sequence, self->clean_sequence_len); + done = epaperdisplay_epaper_core_send_command_sequence(self, true, self->clean_sequence, self->clean_sequence_len); } nlr_pop(); RUN_BACKGROUND_TASKS; // Whatever holds the bus may let it go. @@ -712,7 +740,7 @@ void epaperdisplay_lag_shutdown(epaperdisplay_epaperdisplay_obj_t *self) { } } } - epaperdisplay_epaperdisplay_wait_for_busy(self); + epaperdisplay_epaper_core_wait_for_busy(self); if (self->refreshing) { supervisor_disable_tick(); self->refreshing = false; @@ -726,7 +754,7 @@ void epaperdisplay_lag_shutdown(epaperdisplay_epaperdisplay_obj_t *self) { nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { self->bus.bus_reset(self->bus.bus); - epaperdisplay_epaperdisplay_delay_ms(self, self->start_up_time_ms); + epaperdisplay_epaper_core_delay_ms(self, self->start_up_time_ms); if (lag_wait_idle(self)) { lag_recover(self); } diff --git a/shared-module/epaperdisplay/lag_drive.h b/shared-module/epaperdisplay/lag_drive.h index f3062593dce..c182b5ecb44 100644 --- a/shared-module/epaperdisplay/lag_drive.h +++ b/shared-module/epaperdisplay/lag_drive.h @@ -6,20 +6,9 @@ #pragma once -#include "shared-module/epaperdisplay/EPaperDisplay.h" - -// Shared by EPaperDisplay.c and lag_drive.c only. +#include "shared-module/epaperdisplay/epaper_core.h" #if CIRCUITPY_EPAPERDISPLAY_FAST -// Sends a start, stop or refresh sequence. True if every command went out. -bool epaperdisplay_epaperdisplay_send_command_sequence(epaperdisplay_epaperdisplay_obj_t *self, - bool should_wait_for_busy, const uint8_t *sequence, uint32_t sequence_len); -// Runs the start sequence. A fast display that is already awake skips it unless the start -// sequence changed. -void epaperdisplay_epaperdisplay_start_refresh(epaperdisplay_epaperdisplay_obj_t *self); -// Waits for BUSY to clear or an interrupt. On a lag display the wait is bounded. -void epaperdisplay_epaperdisplay_wait_for_busy(epaperdisplay_epaperdisplay_obj_t *self); - // Longer than one update or stored-waveform refresh takes. This bounds each wait for an update on // a lag display, and the wait before writing the previous RAM. A stock display's waits have no bound. #define EPAPER_WAIT_TIMEOUT_MS 30000 @@ -27,34 +16,31 @@ void epaperdisplay_epaperdisplay_wait_for_busy(epaperdisplay_epaperdisplay_obj_t // What the newest lag step still has to send: nothing, its plane, or the update that shows it. enum { LAG_COMMIT_NONE, LAG_COMMIT_PLANE, LAG_COMMIT_ACTIVATE }; -// Delays, but while interrupts are held an interrupt doesn't cut it short. -void epaperdisplay_epaperdisplay_delay_ms(epaperdisplay_epaperdisplay_obj_t *self, uint32_t delay_ms); -// True if interrupted. While interrupts are held it saves the interrupt for the release and -// returns false. -bool epaperdisplay_epaperdisplay_interrupted(epaperdisplay_epaperdisplay_obj_t *self); -// True once BUSY rises after an update command. False if it doesn't within 2 ms. -bool epaperdisplay_epaperdisplay_wait_for_update_start(epaperdisplay_epaperdisplay_obj_t *self); - // Allocates the frame ring outside the VM heap. Raises MemoryError if it can't. -void epaperdisplay_lag_construct(epaperdisplay_epaperdisplay_obj_t *self, uint8_t lag_frames); +void epaperdisplay_lag_construct(epaperdisplay_epaper_core_t *self, mp_obj_base_t *base, uint8_t lag_frames); // Sends the rest of the drive owed. Returns early if interrupted or the panel is stuck. -void epaperdisplay_lag_flush(epaperdisplay_epaperdisplay_obj_t *self); +void epaperdisplay_lag_flush(epaperdisplay_epaper_core_t *self); // Frees the frame ring. -void epaperdisplay_lag_free(epaperdisplay_epaperdisplay_obj_t *self); +void epaperdisplay_lag_free(epaperdisplay_epaper_core_t *self); // Marks a panel BUSY for longer than EPAPER_WAIT_TIMEOUT_MS as lost, for the next refresh to reset. -void epaperdisplay_lag_give_up_if_stuck(epaperdisplay_epaperdisplay_obj_t *self); +void epaperdisplay_lag_give_up_if_stuck(epaperdisplay_epaper_core_t *self); // Abandons the step in progress, ends any hold on interrupts, then raises. An interrupt saved // during the hold is raised instead of raised. -MP_NORETURN void epaperdisplay_lag_raise(epaperdisplay_epaperdisplay_obj_t *self, mp_obj_t raised); -// Sends one lag step for areas, or only the owed drive when areas is NULL. False if the step +MP_NORETURN void epaperdisplay_lag_raise(epaperdisplay_epaper_core_t *self, mp_obj_t raised); +// Sends one lag step for areas, or only the owed drive when there are none. False if the step // couldn't be sent: interrupted, the panel is stuck, or the start sequence changed. The areas // stay marked and the drive stays owed. -bool epaperdisplay_lag_refresh(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas); +// LVGL builds keep dirty areas in an array, because displayio_area_t is lv_area_t and has no list +// link there. Other builds ignore area_count. NULL must be paired with area_count == 0. +bool epaperdisplay_lag_refresh(epaperdisplay_epaper_core_t *self, const displayio_area_t *areas, + uint8_t area_count); // Ends a hold on interrupts and schedules any interrupt saved during it. -void epaperdisplay_lag_release_interrupts(epaperdisplay_epaperdisplay_obj_t *self); +void epaperdisplay_lag_release_interrupts(epaperdisplay_epaper_core_t *self); // Sends bytes on the bus. False only while interrupts are held and the transfer was interrupted. -bool epaperdisplay_lag_send(epaperdisplay_epaperdisplay_obj_t *self, display_byte_type_t type, +bool epaperdisplay_lag_send(epaperdisplay_epaper_core_t *self, display_byte_type_t type, const uint8_t *data, uint32_t length); // Leaves the panel white and balanced when the display goes away. Doesn't raise or allocate. -void epaperdisplay_lag_shutdown(epaperdisplay_epaperdisplay_obj_t *self); +void epaperdisplay_lag_shutdown(epaperdisplay_epaper_core_t *self); +// Brings every pixel to white with balanced drive, optionally using the clean sequence first. +bool epaperdisplay_epaper_core_clean(epaperdisplay_epaper_core_t *self, uint8_t frames, bool full); #endif // CIRCUITPY_EPAPERDISPLAY_FAST diff --git a/shared-module/epaperdisplay/legacy/EPaperDisplay.c b/shared-module/epaperdisplay/legacy/EPaperDisplay.c new file mode 100644 index 00000000000..979042b57d6 --- /dev/null +++ b/shared-module/epaperdisplay/legacy/EPaperDisplay.c @@ -0,0 +1,591 @@ +// This file is part of the CircuitPython project: https://circuitpython.org +// +// SPDX-FileCopyrightText: Copyright (c) 2019 Scott Shawcroft for Adafruit Industries +// +// SPDX-License-Identifier: MIT + +#include "shared-bindings/epaperdisplay/EPaperDisplay.h" + +#include "py/runtime.h" +#include "shared/runtime/interrupt_char.h" +#include "shared-bindings/time/__init__.h" +#include "shared-module/displayio/__init__.h" +#include "shared-module/epaperdisplay/lag_drive.h" +#include "supervisor/shared/display.h" +#include "supervisor/shared/tick.h" + +#if CIRCUITPY_TINYUSB +#include "supervisor/usb.h" +#endif + +#include +#include + +// lag_drive.c calls these only when it is built. Otherwise they stay static, as before it. +#if CIRCUITPY_EPAPERDISPLAY_FAST +#define LAG_SHARED +#else +#define LAG_SHARED static +#endif + +void common_hal_epaperdisplay_epaperdisplay_construct(epaperdisplay_epaperdisplay_obj_t *self, + const epaperdisplay_construct_args_t *args) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + self->epaper.display = self; + #endif + epaperdisplay_epaper_core_construct(&self->epaper, args); + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (args->lag_frames > 0) { + epaperdisplay_lag_construct(&self->epaper, &self->base, args->lag_frames); + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + + // Set the group after initialization otherwise we may send pixels while we delay in + // initialization. + common_hal_epaperdisplay_epaperdisplay_set_root_group(self, &circuitpython_splash); +} + +bool common_hal_epaperdisplay_epaperdisplay_set_root_group(epaperdisplay_epaperdisplay_obj_t *self, displayio_group_t *root_group) { + return displayio_display_core_set_root_group(&self->epaper.core, root_group); +} + +static const displayio_area_t *epaperdisplay_epaperdisplay_get_refresh_areas(epaperdisplay_epaperdisplay_obj_t *self) { + if (self->epaper.core.full_refresh) { + self->epaper.core.area.next = NULL; + return &self->epaper.core.area; + } + const displayio_area_t *first_area = NULL; + if (self->epaper.core.current_group != NULL) { + first_area = displayio_group_get_refresh_areas(self->epaper.core.current_group, NULL); + } + if (first_area != NULL && self->epaper.bus.row_command == NO_COMMAND) { + // Do a full refresh if the display doesn't support partial updates. + self->epaper.core.area.next = NULL; + return &self->epaper.core.area; + } + return first_area; +} + +LAG_SHARED void epaperdisplay_epaper_core_start_refresh(epaperdisplay_epaper_core_t *self) { + if (!displayio_display_bus_is_free(&self->bus)) { + // Can't acquire display bus; skip updating this display. Try next display. + return; + } + if (!displayio_display_core_start_refresh(&self->core)) { + // Refresh on this display already in progress. + return; + } + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->fast && self->awake) { + if (!self->needs_start) { + // The panel is still configured from the previous refresh. + return; + } + epaperdisplay_epaper_core_wait_for_busy(self); + // SSD168x controllers commit the last RAM byte when the next command arrives, so a reset + // can't come straight after a RAM write. + epaperdisplay_epaper_core_send_stop_sequence_guarded(self); + self->awake = false; + } + #endif + + // run start sequence + self->bus.bus_reset(self->bus.bus); + + epaperdisplay_epaper_core_delay_ms(self, self->start_up_time_ms); + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (!epaperdisplay_epaper_core_send_command_sequence(self, true, self->start_sequence, self->start_sequence_len) || + epaperdisplay_epaper_core_interrupted(self)) { + return; + } + self->awake = true; + self->needs_start = false; + #else + epaperdisplay_epaper_core_send_command_sequence(self, true, self->start_sequence, self->start_sequence_len); + #endif +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_backend_full_area(epaperdisplay_epaper_core_t *self, displayio_area_t *area) { + *area = self->core.area; + area->next = NULL; +} + +bool epaperdisplay_backend_clip_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + displayio_area_t *clipped) { + bool ok = displayio_display_core_clip_area(&self->core, area, clipped); + clipped->next = NULL; + return ok; +} + +void epaperdisplay_backend_render_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + uint8_t *frame, uint16_t frame_stride, bool white) { + uint16_t width = displayio_area_width(area); + uint16_t bytes_per_row = width / 8; + if (white) { + for (int16_t row = area->y1; row < area->y2; row++) { + memset(frame + row * frame_stride + area->x1 / 8, self->black_bits_inverted ? 0x00 : 0xff, + bytes_per_row); + } + return; + } + uint16_t rows_per_buffer = MAX(1, 128 * 32 / width); + size_t words = (rows_per_buffer * width + 31) / 32; + uint32_t buffer[words]; + uint32_t mask[words]; + + self->core.colorspace.grayscale = true; + self->core.colorspace.grayscale_bit = 7; + for (int16_t y = area->y1; y < area->y2; y += rows_per_buffer) { + displayio_area_t subrectangle = { + .x1 = area->x1, + .y1 = y, + .x2 = area->x2, + .y2 = MIN(y + rows_per_buffer, area->y2), + }; + memset(mask, 0, sizeof(mask)); + memset(buffer, 0, sizeof(buffer)); + displayio_display_core_fill_area(&self->core, &subrectangle, mask, buffer); + if (self->black_bits_inverted) { + for (size_t k = 0; k < words; k++) { + buffer[k] = ~buffer[k]; + } + } + const uint8_t *in = (const uint8_t *)buffer; + for (int16_t row = subrectangle.y1; row < subrectangle.y2; row++) { + memcpy(frame + row * frame_stride + area->x1 / 8, in, bytes_per_row); + in += bytes_per_row; + } + // Run background tasks like a regular refresh does. + RUN_BACKGROUND_TASKS; + } +} + +void epaperdisplay_backend_finish_refresh(epaperdisplay_epaper_core_t *self) { + displayio_display_core_finish_refresh(&self->core); +} + +void epaperdisplay_backend_set_full_refresh(epaperdisplay_epaper_core_t *self, bool full_refresh) { + self->core.full_refresh = full_refresh; +} + +void epaperdisplay_backend_set_refresh_in_progress(epaperdisplay_epaper_core_t *self, bool in_progress) { + self->core.refresh_in_progress = in_progress; +} +#endif + +#if CIRCUITPY_EPAPERDISPLAY_FAST +static bool epaperdisplay_epaperdisplay_refresh_area(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area, bool write_previous); + +static void epaperdisplay_epaperdisplay_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas) { + // Actually refresh the display now that all pixel RAM has been updated. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.refresh_sequence, self->epaper.refresh_sequence_len); + const uint64_t refresh_start = supervisor_ticks_ms64(); + bool previous_written = true; + mp_obj_t raised = MP_OBJ_NULL; + + if (self->epaper.write_previous_ram_command != NO_COMMAND && areas != NULL) { + // Copy the new image into the previous image RAM so the next partial update compares + // against what is on screen. The controller ignores RAM writes while it is updating. + if (self->epaper.busy.base.type == &mp_type_NoneType) { + common_hal_time_delay_ms(self->epaper.refresh_time); + } else { + previous_written = epaperdisplay_epaper_core_wait_for_update_end(&self->epaper); + } + nlr_buf_t nlr; + if (nlr_push(&nlr) == 0) { + while (areas != NULL && previous_written) { + previous_written = !mp_hal_is_interrupted() && + epaperdisplay_epaperdisplay_refresh_area(self, areas, true); + areas = areas->next; + } + nlr_pop(); + } else { + // Ctrl-C raises from a transfer in progress, and that transaction is still open. + raised = nlr.ret_val; + previous_written = false; + if (!displayio_display_bus_is_free(&self->epaper.bus)) { + displayio_display_bus_end_transaction(&self->epaper.bus); + } + } + } + + supervisor_enable_tick(); + self->epaper.refreshing = true; + + displayio_display_core_finish_refresh(&self->epaper.core); + // The update began before the wait above, and refresh_time and seconds_per_frame count from it. + self->epaper.core.last_refresh = refresh_start; + if (!previous_written) { + // The previous RAM is stale, so the next update has to write everything. + self->epaper.core.full_refresh = true; + } + if (raised != MP_OBJ_NULL) { + nlr_jump(raised); + } +} +#else +static void epaperdisplay_epaperdisplay_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *areas) { + // Actually refresh the display now that all pixel RAM has been updated. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.refresh_sequence, self->epaper.refresh_sequence_len); + + supervisor_enable_tick(); + self->epaper.refreshing = true; + + displayio_display_core_finish_refresh(&self->epaper.core); +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +void common_hal_epaperdisplay_epaperdisplay_set_rotation(epaperdisplay_epaperdisplay_obj_t *self, int rotation) { + displayio_display_core_set_rotation_and_update(&self->epaper.core, rotation, &self->base); +} + +static bool epaperdisplay_epaperdisplay_refresh_area(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area, bool write_previous) { + uint16_t buffer_size = 128; // In uint32_ts + + displayio_area_t clipped; + // Clip the area to the display by overlapping the areas. If there is no overlap then we're done. + if (!displayio_display_core_clip_area(&self->epaper.core, area, &clipped)) { + return true; + } + uint16_t subrectangles = 1; + uint16_t rows_per_buffer = displayio_area_height(&clipped); + uint8_t pixels_per_word = (sizeof(uint32_t) * 8) / self->epaper.core.colorspace.depth; + uint16_t pixels_per_buffer = displayio_area_size(&clipped); + if (displayio_area_size(&clipped) > buffer_size * pixels_per_word) { + rows_per_buffer = buffer_size * pixels_per_word / displayio_area_width(&clipped); + if (rows_per_buffer == 0) { + rows_per_buffer = 1; + } + subrectangles = displayio_area_height(&clipped) / rows_per_buffer; + if (displayio_area_height(&clipped) % rows_per_buffer != 0) { + subrectangles++; + } + pixels_per_buffer = rows_per_buffer * displayio_area_width(&clipped); + buffer_size = pixels_per_buffer / pixels_per_word; + if (pixels_per_buffer % pixels_per_word) { + buffer_size += 1; + } + } + + // Allocated and shared as a uint32_t array so the compiler knows the + // alignment everywhere. + uint32_t buffer[buffer_size]; + volatile uint32_t mask_length = (pixels_per_buffer / 32) + 1; + uint32_t mask[mask_length]; + + uint8_t passes = 1; + if (self->epaper.write_color_ram_command != NO_COMMAND && !write_previous) { + passes = 2; + } + for (uint8_t pass = 0; pass < passes; pass++) { + uint16_t remaining_rows = displayio_area_height(&clipped); + + if (self->epaper.bus.row_command != NO_COMMAND) { + displayio_display_bus_set_region_to_update(&self->epaper.bus, &self->epaper.core.colorspace, &clipped); + } + + uint8_t write_command = self->epaper.write_black_ram_command; + if (pass == 1) { + write_command = self->epaper.write_color_ram_command; + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + else if (write_previous) { + write_command = self->epaper.write_previous_ram_command; + } + #endif + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + // Display bus not available now. + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_COMMAND, self->epaper.chip_select, &write_command, 1); + displayio_display_bus_end_transaction(&self->epaper.bus); + + for (uint16_t j = 0; j < subrectangles; j++) { + displayio_area_t subrectangle = { + .x1 = clipped.x1, + .y1 = clipped.y1 + rows_per_buffer * j, + .x2 = clipped.x2, + .y2 = clipped.y1 + rows_per_buffer * (j + 1) + }; + if (remaining_rows < rows_per_buffer) { + subrectangle.y2 = subrectangle.y1 + remaining_rows; + } + remaining_rows -= rows_per_buffer; + + + uint16_t subrectangle_size_bytes = displayio_area_size(&subrectangle) / (8 / self->epaper.core.colorspace.depth); + + memset(mask, 0, mask_length * sizeof(mask[0])); + memset(buffer, 0, buffer_size * sizeof(buffer[0])); + + if (!self->epaper.acep) { + self->epaper.core.colorspace.grayscale = true; + self->epaper.core.colorspace.grayscale_bit = 7; + } + if (pass == 1) { + if (self->epaper.grayscale) { // 4-color grayscale + self->epaper.core.colorspace.grayscale_bit = 6; + displayio_display_core_fill_area(&self->epaper.core, &subrectangle, mask, buffer); + } else if (self->epaper.core.colorspace.tricolor) { + self->epaper.core.colorspace.grayscale = false; + displayio_display_core_fill_area(&self->epaper.core, &subrectangle, mask, buffer); + } else if (self->epaper.core.colorspace.sixcolor || self->epaper.core.colorspace.sevencolor) { + displayio_display_core_fill_area(&self->epaper.core, &subrectangle, mask, buffer); + } + } else { + displayio_display_core_fill_area(&self->epaper.core, &subrectangle, mask, buffer); + } + + // Invert it all. + if ((pass == 1 && self->epaper.color_bits_inverted) || + (pass == 0 && self->epaper.black_bits_inverted)) { + for (uint16_t k = 0; k < buffer_size; k++) { + buffer[k] = ~buffer[k]; + } + } + + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + // Can't acquire display bus; skip the rest of the data. Try next display. + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_DATA, self->epaper.chip_select, (uint8_t *)buffer, subrectangle_size_bytes); + displayio_display_bus_end_transaction(&self->epaper.bus); + + // Run background tasks so they can run during an explicit refresh. + // Auto-refresh won't run background tasks here because it is a background task itself. + RUN_BACKGROUND_TASKS; + + // Run USB background tasks so they can run during an implicit refresh. + #if CIRCUITPY_TINYUSB + usb_background(); + #endif + } + } + + return true; +} + +static bool _clean_area(epaperdisplay_epaperdisplay_obj_t *self) { + uint16_t width = displayio_display_core_get_width(&self->epaper.core); + uint16_t height = displayio_display_core_get_height(&self->epaper.core); + + uint8_t buffer[width / 2]; + memset(buffer, 0x77, width / 2); + + uint8_t write_command = self->epaper.write_black_ram_command; + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_COMMAND, self->epaper.chip_select, &write_command, 1); + displayio_display_bus_end_transaction(&self->epaper.bus); + + for (uint16_t j = 0; j < height; j++) { + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + // Can't acquire display bus; skip the rest of the data. Try next display. + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_DATA, self->epaper.chip_select, buffer, width / 2); + displayio_display_bus_end_transaction(&self->epaper.bus); + + // TODO(tannewt): Make refresh displays faster so we don't starve other + // background tasks. + #if CIRCUITPY_TINYUSB + usb_background(); + #endif + } + + return true; +} + +bool common_hal_epaperdisplay_epaperdisplay_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + + if (self->epaper.refreshing && self->epaper.busy.base.type == &digitalio_digitalinout_type) { + if (common_hal_digitalio_digitalinout_get_value(&self->epaper.busy) != self->epaper.busy_state) { + supervisor_disable_tick(); + self->epaper.refreshing = false; + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (!self->epaper.fast) { + // Run stop sequence but don't wait for busy because busy is set when sleeping. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + } + #else + // Run stop sequence but don't wait for busy because busy is set when sleeping. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + #endif + } else { + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_give_up_if_stuck(&self->epaper); + #endif + return false; + } + } + if (self->epaper.core.current_group == NULL) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + // Nothing to draw, but the drive already started is still owed. + if (self->epaper.lag.frames > 0 && self->epaper.awake) { + return epaperdisplay_lag_refresh(&self->epaper, NULL, 0); + } + #endif + return true; + } + // Refresh at seconds per frame rate. + if (common_hal_epaperdisplay_epaperdisplay_get_time_to_refresh(self) > 0) { + return false; + } + if (!displayio_display_bus_is_free(&self->epaper.bus)) { + // Can't acquire display bus; skip updating this display. Try next display. + return false; + } + const displayio_area_t *current_area = epaperdisplay_epaperdisplay_get_refresh_areas(self); + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.lag.frames > 0) { + return epaperdisplay_lag_refresh(&self->epaper, current_area, 0); + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + if (current_area == NULL) { + return true; + } + if (self->epaper.acep) { + epaperdisplay_epaper_core_start_refresh(&self->epaper); + _clean_area(self); + epaperdisplay_epaperdisplay_finish_refresh(self, NULL); + while (self->epaper.refreshing && !mp_hal_is_interrupted()) { + RUN_BACKGROUND_TASKS; + } + } + if (mp_hal_is_interrupted()) { + return false; + } + + epaperdisplay_epaper_core_start_refresh(&self->epaper); + const displayio_area_t *first_area = current_area; + while (current_area != NULL) { + epaperdisplay_epaperdisplay_refresh_area(self, current_area, false); + current_area = current_area->next; + } + epaperdisplay_epaperdisplay_finish_refresh(self, first_area); + return true; +} + +void release_epaperdisplay(epaperdisplay_epaperdisplay_obj_t *self) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_shutdown(&self->epaper); + epaperdisplay_lag_free(&self->epaper); + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.refreshing) { + epaperdisplay_epaper_core_wait_for_busy(&self->epaper); + supervisor_disable_tick(); + self->epaper.refreshing = false; + // Run stop sequence but don't wait for busy because busy is set when sleeping. + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.fast) { + epaperdisplay_epaper_core_send_stop_sequence_guarded(&self->epaper); + } else { + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + } + #else + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + #endif + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + else if (self->epaper.fast && self->epaper.awake) { + epaperdisplay_epaper_core_send_stop_sequence_guarded(&self->epaper); + } + self->epaper.awake = false; + #endif + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_release_interrupts(&self->epaper); + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + + release_display_core(&self->epaper.core); + if (self->epaper.busy.base.type == &digitalio_digitalinout_type) { + common_hal_digitalio_digitalinout_deinit(&self->epaper.busy); + } +} + +void epaperdisplay_epaperdisplay_reset(epaperdisplay_epaperdisplay_obj_t *self) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.lag.frames > 0) { + // Only a primary display gets here; reset_displays() has released the others. The heap is + // still here but the sequences won't be, and the display would otherwise persist to draw + // the splash with them. Finish now and stay asleep. Its bus still holds the pins until + // the next VM ends or release_displays(). + epaperdisplay_epaper_core_end_held_bus(&self->epaper); + release_epaperdisplay(self); + self->base.type = &mp_type_NoneType; + return; + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + displayio_display_core_set_root_group(&self->epaper.core, &circuitpython_splash); + self->epaper.core.full_refresh = true; + #if CIRCUITPY_EPAPERDISPLAY_FAST + // Let the panel sleep after the next refresh when code isn't running. + if (self->epaper.fast && self->epaper.awake && !self->epaper.refreshing) { + // Nothing can catch a raise from a send. A reload may be pending. + epaperdisplay_epaper_core_end_held_bus(&self->epaper); + epaperdisplay_epaper_core_send_stop_sequence_guarded(&self->epaper); + self->epaper.awake = false; + } + self->epaper.fast = false; + #endif +} + +uint16_t common_hal_epaperdisplay_epaperdisplay_get_width(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_width(&self->epaper); +} + +uint16_t common_hal_epaperdisplay_epaperdisplay_get_height(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_height(&self->epaper); +} + +uint16_t common_hal_epaperdisplay_epaperdisplay_get_rotation(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_rotation(&self->epaper); +} + +mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_root_group(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_root_group(&self->epaper); +} + +mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_bus(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_bus(&self->epaper); +} + +uint32_t common_hal_epaperdisplay_epaperdisplay_get_time_to_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_time_to_refresh(&self->epaper); +} + +bool common_hal_epaperdisplay_epaperdisplay_get_busy(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_busy(&self->epaper); +} + +void epaperdisplay_epaperdisplay_change_refresh_mode_parameters(epaperdisplay_epaperdisplay_obj_t *self, + mp_buffer_info_t *start_sequence, mp_buffer_info_t *refresh_sequence, float seconds_per_frame) { + epaperdisplay_epaper_core_change_refresh_mode_parameters(&self->epaper, + start_sequence, refresh_sequence, seconds_per_frame); +} + +void epaperdisplay_epaperdisplay_background(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_background(&self->epaper); +} + +void epaperdisplay_epaperdisplay_collect_ptrs(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_collect_ptrs(&self->epaper); +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_epaperdisplay_prepare_release(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_prepare_release(&self->epaper); +} + +void epaperdisplay_epaperdisplay_end_held_bus(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_end_held_bus(&self->epaper); +} + +bool common_hal_epaperdisplay_epaperdisplay_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, bool full) { + return epaperdisplay_epaper_core_clean(&self->epaper, frames, full); +} +#endif diff --git a/shared-module/epaperdisplay/legacy/EPaperDisplay.h b/shared-module/epaperdisplay/legacy/EPaperDisplay.h new file mode 100644 index 00000000000..81a57f71b76 --- /dev/null +++ b/shared-module/epaperdisplay/legacy/EPaperDisplay.h @@ -0,0 +1,14 @@ +// This file is part of the CircuitPython project: https://circuitpython.org +// +// SPDX-FileCopyrightText: Copyright (c) 2019 Scott Shawcroft for Adafruit Industries +// +// SPDX-License-Identifier: MIT + +#pragma once + +#include "shared-module/epaperdisplay/epaper_core.h" + +struct epaperdisplay_epaperdisplay_obj_t { + mp_obj_base_t base; + epaperdisplay_epaper_core_t epaper; +}; diff --git a/shared-module/epaperdisplay/lvgl/EPaperDisplay.c b/shared-module/epaperdisplay/lvgl/EPaperDisplay.c new file mode 100644 index 00000000000..eb9a1459f5f --- /dev/null +++ b/shared-module/epaperdisplay/lvgl/EPaperDisplay.c @@ -0,0 +1,968 @@ +// This file is part of the CircuitPython project: https://circuitpython.org +// +// SPDX-FileCopyrightText: Copyright (c) 2019 Scott Shawcroft for Adafruit Industries +// SPDX-FileCopyrightText: Copyright (c) 2026 Scott Shawcroft for Adafruit Industries +// +// SPDX-License-Identifier: MIT + +#include "shared-bindings/epaperdisplay/EPaperDisplay.h" + +#include "py/runtime.h" +#include "shared-bindings/displayio/ColorConverter.h" +#include "shared-bindings/time/__init__.h" +#include "shared-module/displayio/__init__.h" +#include "shared-module/displayio/lvgl/lvgl_internal.h" +#include "shared-module/epaperdisplay/lag_drive.h" +#include "supervisor/port_heap.h" +#include "supervisor/shared/display.h" +#include "supervisor/shared/tick.h" + +#include "lvgl.h" +#include "lvgl/draw/lv_draw_utils.h" + +#if CIRCUITPY_TINYUSB +#include "supervisor/usb.h" +#endif + +#include +#include + +// LVGL draw buffer height. The flush callback converts complete rows, so this only needs to +// cover a useful part of the screen at a time. +#define EPAPER_LVGL_DRAW_BUF_LINES 20 + +static void epaperdisplay_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map); +static void epaperdisplay_lvgl_mark_dirty(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area); +static void epaperdisplay_lvgl_clear_dirty(epaperdisplay_epaperdisplay_obj_t *self); + +static void epaperdisplay_lvgl_free_buffers(epaperdisplay_epaperdisplay_obj_t *self) { + port_free(self->lv_buf); + port_free(self->lv_rotation_buf); + port_free(self->black_buf); + port_free(self->color_buf); + self->lv_buf = NULL; + self->lv_rotation_buf = NULL; + self->black_buf = NULL; + self->color_buf = NULL; + self->lv_buf_size = 0; + self->lv_rotation_buf_size = 0; + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_free(&self->epaper); + #endif +} + +void common_hal_epaperdisplay_epaperdisplay_construct(epaperdisplay_epaperdisplay_obj_t *self, + const epaperdisplay_construct_args_t *args) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + self->epaper.display = self; + #endif + uint16_t rotation = args->rotation % 360; + epaperdisplay_epaper_core_construct(&self->epaper, args); + + // The converted framebuffer. The panel planes are packed like the controller RAM: + // most significant pixel first, regardless of the LVGL source format. These allocations + // outlive the VM, so they come from the port heap. + self->lv_display = NULL; + self->lv_color_format = LV_COLOR_FORMAT_RGB565; + self->lv_buf = NULL; + self->lv_buf_size = 0; + self->lv_rotation_buf = NULL; + self->lv_rotation_buf_size = 0; + // The constructor's width and height are logical dimensions at the requested rotation. + // LVGL's original resolution and the converted planes use the controller's native RAM + // orientation instead, which is fixed for the lifetime of the display. + bool transposed = rotation == 90 || rotation == 270; + self->canvas_width = transposed ? args->height : args->width; + self->canvas_height = transposed ? args->width : args->height; + self->canvas_depth = self->epaper.core.colorspace.depth; + self->canvas_stride = (self->canvas_width * self->canvas_depth + 7) / 8; + self->black_buf = NULL; + self->color_buf = NULL; + self->dirty_count = 0; + self->dirty_full = false; + self->refresh_in_progress = false; + self->full_refresh = true; + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (args->lag_frames > 0) { + epaperdisplay_lag_construct(&self->epaper, &self->base, args->lag_frames); + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + + size_t canvas_size = (size_t)self->canvas_stride * self->canvas_height; + self->black_buf = port_malloc(canvas_size, false); + if (self->black_buf == NULL) { + epaperdisplay_lvgl_free_buffers(self); + self->base.type = &mp_type_NoneType; + mp_raise_msg(&mp_type_MemoryError, MP_ERROR_TEXT("LVGL buffer alloc failed")); + } + memset(self->black_buf, 0, canvas_size); + if (args->write_color_ram_command != NO_COMMAND && !self->epaper.acep) { + self->color_buf = port_malloc(canvas_size, false); + if (self->color_buf == NULL) { + epaperdisplay_lvgl_free_buffers(self); + self->base.type = &mp_type_NoneType; + mp_raise_msg(&mp_type_MemoryError, MP_ERROR_TEXT("LVGL buffer alloc failed")); + } + memset(self->color_buf, 0, canvas_size); + } + + // Set up LVGL. The display's buffers and flush callback have to exist before the + // compositor can see it as the default display. + displayio_lvgl_port_init(); + displayio_lvgl_lock(); + self->lv_display = lv_display_create(self->canvas_width, self->canvas_height); + if (self->lv_display == NULL) { + displayio_lvgl_unlock(); + epaperdisplay_lvgl_free_buffers(self); + self->base.type = &mp_type_NoneType; + mp_raise_RuntimeError(MP_ERROR_TEXT("LVGL display create failed")); + } + lv_display_set_user_data(self->lv_display, self); + lv_display_set_color_format(self->lv_display, self->lv_color_format); + lv_display_set_flush_cb(self->lv_display, epaperdisplay_lvgl_flush_cb); + + uint16_t max_dimension = MAX(args->width, args->height); + uint16_t lines = MIN(EPAPER_LVGL_DRAW_BUF_LINES, self->canvas_height); + size_t lv_buf_size = lv_draw_buf_width_to_stride(max_dimension, self->lv_color_format) * lines; + lv_buf_size = (lv_buf_size + LV_DRAW_BUF_ALIGN - 1) & ~(LV_DRAW_BUF_ALIGN - 1); + self->lv_buf = port_malloc(lv_buf_size, false); + self->lv_rotation_buf = port_malloc(lv_buf_size, false); + if (self->lv_buf == NULL || self->lv_rotation_buf == NULL) { + lv_display_delete(self->lv_display); + self->lv_display = NULL; + displayio_lvgl_unlock(); + epaperdisplay_lvgl_free_buffers(self); + self->base.type = &mp_type_NoneType; + mp_raise_msg(&mp_type_MemoryError, MP_ERROR_TEXT("LVGL buffer alloc failed")); + } + self->lv_buf_size = lv_buf_size; + self->lv_rotation_buf_size = lv_buf_size; + lv_display_set_buffers(self->lv_display, self->lv_buf, NULL, self->lv_buf_size, + LV_DISPLAY_RENDER_MODE_PARTIAL); + + displayio_lvgl_init(); + lv_display_set_default(self->lv_display); + displayio_lvgl_register_display(self->lv_display); + displayio_display_core_set_root_group(&self->epaper.core, &circuitpython_splash); + displayio_lvgl_set_root_group(&circuitpython_splash); + displayio_lvgl_unlock(); + + if (rotation != 0) { + common_hal_epaperdisplay_epaperdisplay_set_rotation(self, rotation); + } +} + +bool common_hal_epaperdisplay_epaperdisplay_set_root_group(epaperdisplay_epaperdisplay_obj_t *self, displayio_group_t *root_group) { + bool ok = displayio_display_core_set_root_group(&self->epaper.core, root_group); + if (!ok) { + return false; + } + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + if (self->lv_display != NULL) { + lv_display_set_default(self->lv_display); + } + displayio_lvgl_set_root_group(root_group); + self->full_refresh = true; + self->dirty_full = true; + displayio_lvgl_unlock_with_cleanup(); + return true; +} + +// The whole physical panel, which is also the coordinate space the flush callback and the +// controller commands use. +static void epaperdisplay_lvgl_full_area(epaperdisplay_epaperdisplay_obj_t *self, displayio_area_t *area) { + area->x1 = 0; + area->y1 = 0; + area->x2 = self->canvas_width; + area->y2 = self->canvas_height; +} + +// Clip an area to the panel and grow it to a whole byte of packed pixels. The controller +// addresses packed RAM in whole bytes, so a partial byte at either edge has to be sent too. +static bool epaperdisplay_lvgl_clip_area(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area, + displayio_area_t *clipped) { + displayio_area_t whole; + epaperdisplay_lvgl_full_area(self, &whole); + if (!displayio_area_compute_overlap(&whole, area, clipped)) { + return false; + } + uint8_t depth = self->canvas_depth; + if (depth < 8 && self->epaper.core.colorspace.pixels_in_byte_share_row) { + uint8_t pixels_per_byte = 8 / depth * self->epaper.core.colorspace.bytes_per_cell; + clipped->x1 -= clipped->x1 % pixels_per_byte; + if (clipped->x2 % pixels_per_byte != 0) { + clipped->x2 += pixels_per_byte - clipped->x2 % pixels_per_byte; + } + if (clipped->x1 < 0) { + clipped->x1 = 0; + } + // The packed rows have room for the padding pixels in the last byte. They are written + // as zero (or white when inverted) and sent with the rest of the row. + int32_t packed_width = self->canvas_stride * pixels_per_byte; + if (clipped->x2 > packed_width) { + clipped->x2 = packed_width; + } + } + return !displayio_area_empty(clipped); +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +// Copy an already-clipped area from the converted framebuffer into a lag frame, or fill it white. +static void epaperdisplay_lvgl_render_area(epaperdisplay_epaperdisplay_obj_t *self, + const displayio_area_t *area, uint8_t *frame, uint16_t frame_stride, bool white) { + uint16_t bytes_per_row = displayio_area_width(area) / 8; + for (int16_t row = area->y1; row < area->y2; row++) { + uint8_t *dest = frame + row * frame_stride + area->x1 / 8; + if (white) { + memset(dest, self->epaper.black_bits_inverted ? 0x00 : 0xff, bytes_per_row); + } else { + const uint8_t *source = self->black_buf + row * self->canvas_stride + area->x1 / 8; + memcpy(dest, source, bytes_per_row); + } + } +} +#endif + +static bool epaperdisplay_lvgl_begin_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + if (self->refresh_in_progress) { + return false; + } + self->refresh_in_progress = true; + self->epaper.core.last_refresh = supervisor_ticks_ms64(); + return true; +} + +static void epaperdisplay_lvgl_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + self->full_refresh = false; + self->refresh_in_progress = false; + self->epaper.core.last_refresh = supervisor_ticks_ms64(); + epaperdisplay_lvgl_clear_dirty(self); +} + +static void epaperdisplay_lvgl_clear_dirty(epaperdisplay_epaperdisplay_obj_t *self) { + self->dirty_count = 0; + self->dirty_full = false; +} + +static bool epaperdisplay_lvgl_area_contains(const displayio_area_t *outer, const displayio_area_t *inner) { + return outer->x1 <= inner->x1 && outer->y1 <= inner->y1 && + outer->x2 >= inner->x2 && outer->y2 >= inner->y2; +} + +// Keep the areas LVGL flushed since the panel was last updated. Sending them individually +// preserves more of the panel's partial-update window than one screen-sized box would. +static void epaperdisplay_lvgl_mark_dirty(epaperdisplay_epaperdisplay_obj_t *self, const displayio_area_t *area) { + if (self->dirty_full) { + return; + } + displayio_area_t clipped; + if (!epaperdisplay_lvgl_clip_area(self, area, &clipped)) { + return; + } + for (uint8_t i = 0; i < self->dirty_count; i++) { + if (epaperdisplay_lvgl_area_contains(&self->dirty[i], &clipped)) { + return; + } + } + if (self->dirty_count < EPAPER_LVGL_MAX_DIRTY) { + self->dirty[self->dirty_count++] = clipped; + return; + } + // Too many small changes. Merge everything, including this one, into a single box. + displayio_area_t merged = clipped; + for (uint8_t i = 0; i < self->dirty_count; i++) { + displayio_area_union(&merged, &self->dirty[i], &merged); + } + self->dirty[0] = merged; + self->dirty_count = 1; +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_backend_full_area(epaperdisplay_epaper_core_t *self, displayio_area_t *area) { + epaperdisplay_lvgl_full_area(self->display, area); +} + +bool epaperdisplay_backend_clip_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + displayio_area_t *clipped) { + return epaperdisplay_lvgl_clip_area(self->display, area, clipped); +} + +void epaperdisplay_backend_render_area(epaperdisplay_epaper_core_t *self, const displayio_area_t *area, + uint8_t *frame, uint16_t frame_stride, bool white) { + epaperdisplay_lvgl_render_area(self->display, area, frame, frame_stride, white); + RUN_BACKGROUND_TASKS; +} + +void epaperdisplay_backend_finish_refresh(epaperdisplay_epaper_core_t *self) { + epaperdisplay_lvgl_finish_refresh(self->display); +} + +void epaperdisplay_backend_set_full_refresh(epaperdisplay_epaper_core_t *self, bool full_refresh) { + epaperdisplay_epaperdisplay_obj_t *obj = self->display; + obj->full_refresh = full_refresh; +} + +void epaperdisplay_backend_set_refresh_in_progress(epaperdisplay_epaper_core_t *self, bool in_progress) { + epaperdisplay_epaperdisplay_obj_t *obj = self->display; + obj->refresh_in_progress = in_progress; +} +#endif + +// Store one converted panel pixel in a packed plane. Bits run most significant first and each +// row starts on a byte boundary, which is what the controllers and the legacy compositor write. +static void epaperdisplay_lvgl_store_pixel(epaperdisplay_epaperdisplay_obj_t *self, uint8_t *buf, + uint16_t x, uint16_t y, uint8_t value, bool inverted) { + uint8_t depth = self->canvas_depth; + uint8_t pixels_per_byte = 8 / depth; + uint8_t mask = (1u << depth) - 1u; + value &= mask; + if (inverted) { + value ^= mask; + } + uint16_t byte_index = y * self->canvas_stride + x / pixels_per_byte; + uint8_t shift = (pixels_per_byte - 1 - (x % pixels_per_byte)) * depth; + buf[byte_index] = (buf[byte_index] & ~(mask << shift)) | (value << shift); +} + +static uint32_t epaperdisplay_lvgl_rgb565_to_rgb888(uint16_t pixel) { + uint32_t r8 = (pixel >> 11) << 3; + uint32_t g8 = ((pixel >> 5) << 2) & 0xff; + uint32_t b8 = (pixel << 3) & 0xff; + return (r8 << 16) | (g8 << 8) | b8; +} + +static void epaperdisplay_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map) { + epaperdisplay_epaperdisplay_obj_t *self = lv_display_get_user_data(disp); + lv_display_rotation_t rotation = lv_display_get_rotation(disp); + const uint8_t *src = px_map; + lv_area_t rotated_area; + uint32_t src_stride = lv_draw_buf_width_to_stride(lv_area_get_width(area), self->lv_color_format); + + if (rotation != LV_DISPLAY_ROTATION_0) { + rotated_area = *area; + lv_display_rotate_area(disp, &rotated_area); + uint32_t dest_stride = lv_draw_buf_width_to_stride( + lv_area_get_width(&rotated_area), self->lv_color_format); + if ((size_t)dest_stride * lv_area_get_height(&rotated_area) > self->lv_rotation_buf_size) { + // The rotation buffer is sized for the longest edge. A larger flush means the + // display geometry changed without reconfiguring; drop this frame rather than + // writing past the buffer. + lv_display_flush_ready(disp); + return; + } + lv_color_format_t rotate_format = self->lv_color_format; + if (rotate_format == LV_COLOR_FORMAT_RGB565_SWAPPED) { + rotate_format = LV_COLOR_FORMAT_RGB565; + } + lv_draw_rotate(px_map, self->lv_rotation_buf, lv_area_get_width(area), + lv_area_get_height(area), src_stride, dest_stride, rotation, rotate_format); + area = &rotated_area; + src = self->lv_rotation_buf; + src_stride = dest_stride; + } + + _displayio_colorspace_t black_cs = self->epaper.core.colorspace; + if (!self->epaper.acep) { + black_cs.grayscale = true; + black_cs.grayscale_bit = 7; + } + _displayio_colorspace_t color_cs = self->epaper.core.colorspace; + bool color_convert = false; + if (self->color_buf != NULL) { + if (self->epaper.grayscale) { + color_cs.grayscale = true; + color_cs.grayscale_bit = 6; + color_convert = true; + } else if (color_cs.tricolor) { + color_cs.grayscale = false; + color_convert = true; + } else if (color_cs.sixcolor || color_cs.sevencolor) { + color_convert = true; + } + } + + for (int32_t y = area->y1; y <= area->y2; y++) { + // px_map (or the rotated copy) starts at the flush area's first pixel. + const uint8_t *row = src + (y - area->y1) * src_stride; + for (int32_t x = area->x1; x <= area->x2; x++) { + uint16_t source_pixel; + memcpy(&source_pixel, row, sizeof(source_pixel)); + row += sizeof(source_pixel); + uint32_t rgb = epaperdisplay_lvgl_rgb565_to_rgb888(source_pixel); + displayio_input_pixel_t input_pixel = { + .pixel = rgb, + .x = x, + .y = y, + .tile_x = x, + .tile_y = y, + }; + displayio_output_pixel_t output_pixel; + output_pixel.pixel = 0; + output_pixel.opaque = false; + displayio_convert_color(&black_cs, black_cs.dither, &input_pixel, &output_pixel); + epaperdisplay_lvgl_store_pixel(self, self->black_buf, x, y, + output_pixel.pixel, self->epaper.black_bits_inverted); + + if (self->color_buf != NULL) { + if (color_convert) { + displayio_convert_color(&color_cs, color_cs.dither, &input_pixel, &output_pixel); + } else { + output_pixel.pixel = 0; + } + epaperdisplay_lvgl_store_pixel(self, self->color_buf, x, y, + output_pixel.pixel, self->epaper.color_bits_inverted); + } + } + } + + // LVGL area coordinates are inclusive; displayio's are exclusive. + displayio_area_t dirty_area = { + .x1 = area->x1, + .y1 = area->y1, + .x2 = area->x2 + 1, + .y2 = area->y2 + 1, + }; + epaperdisplay_lvgl_mark_dirty(self, &dirty_area); + lv_display_flush_ready(disp); +} + +static void epaperdisplay_lvgl_start_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_t *core = &self->epaper; + if (!displayio_display_bus_is_free(&core->bus)) { + // Can't acquire display bus; skip updating this display. Try next display. + return; + } + if (!epaperdisplay_lvgl_begin_refresh(self)) { + // Refresh on this display already in progress. + return; + } + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (core->fast && core->awake) { + if (!core->needs_start) { + // The panel is still configured from the previous refresh. + return; + } + epaperdisplay_epaper_core_wait_for_busy(core); + // SSD168x controllers commit the last RAM byte when the next command arrives, so a reset + // can't come straight after a RAM write. + epaperdisplay_epaper_core_send_stop_sequence_guarded(core); + core->awake = false; + } + #endif + + // run start sequence + core->bus.bus_reset(core->bus.bus); + + epaperdisplay_epaper_core_delay_ms(core, core->start_up_time_ms); + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (!epaperdisplay_epaper_core_send_command_sequence(core, true, core->start_sequence, core->start_sequence_len) || + epaperdisplay_epaper_core_interrupted(core)) { + return; + } + core->awake = true; + core->needs_start = false; + #else + epaperdisplay_epaper_core_send_command_sequence(core, true, core->start_sequence, core->start_sequence_len); + #endif +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_epaper_core_start_refresh(epaperdisplay_epaper_core_t *self) { + epaperdisplay_lvgl_start_refresh(self->display); +} +#endif + +static bool epaperdisplay_epaperdisplay_refresh_area(epaperdisplay_epaperdisplay_obj_t *self, + const displayio_area_t *area, bool write_previous); + +#if CIRCUITPY_EPAPERDISPLAY_FAST +static void epaperdisplay_epaperdisplay_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self, + const displayio_area_t *areas, uint8_t area_count) { + // Actually refresh the display now that all pixel RAM has been updated. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.refresh_sequence, self->epaper.refresh_sequence_len); + const uint64_t refresh_start = supervisor_ticks_ms64(); + bool previous_written = true; + mp_obj_t raised = MP_OBJ_NULL; + + if (self->epaper.write_previous_ram_command != NO_COMMAND && area_count > 0) { + // Copy the new image into the previous image RAM so the next partial update compares + // against what is on screen. The controller ignores RAM writes while it is updating. + if (self->epaper.busy.base.type == &mp_type_NoneType) { + common_hal_time_delay_ms(self->epaper.refresh_time); + } else { + previous_written = epaperdisplay_epaper_core_wait_for_update_end(&self->epaper); + } + nlr_buf_t nlr; + if (nlr_push(&nlr) == 0) { + for (uint8_t i = 0; i < area_count && previous_written; i++) { + previous_written = !mp_hal_is_interrupted() && + epaperdisplay_epaperdisplay_refresh_area(self, &areas[i], true); + } + nlr_pop(); + } else { + // Ctrl-C raises from a transfer in progress, and that transaction is still open. + raised = nlr.ret_val; + previous_written = false; + if (!displayio_display_bus_is_free(&self->epaper.bus)) { + displayio_display_bus_end_transaction(&self->epaper.bus); + } + } + } + + supervisor_enable_tick(); + self->epaper.refreshing = true; + + epaperdisplay_lvgl_finish_refresh(self); + // The update began before the wait above, and refresh_time and seconds_per_frame count from it. + self->epaper.core.last_refresh = refresh_start; + if (!previous_written) { + // The previous RAM is stale, so the next update has to write everything. + self->full_refresh = true; + } + if (raised != MP_OBJ_NULL) { + nlr_jump(raised); + } +} +#else +static void epaperdisplay_epaperdisplay_finish_refresh(epaperdisplay_epaperdisplay_obj_t *self, + const displayio_area_t *areas, uint8_t area_count) { + // Actually refresh the display now that all pixel RAM has been updated. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.refresh_sequence, self->epaper.refresh_sequence_len); + + supervisor_enable_tick(); + self->epaper.refreshing = true; + + epaperdisplay_lvgl_finish_refresh(self); +} +#endif // CIRCUITPY_EPAPERDISPLAY_FAST + +void common_hal_epaperdisplay_epaperdisplay_set_rotation(epaperdisplay_epaperdisplay_obj_t *self, int rotation) { + // Only the logical dimensions change here. The canvas and LVGL's original resolution stay + // in the controller's native RAM orientation established by the constructor. + bool transposed = (self->epaper.core.rotation == 90 || self->epaper.core.rotation == 270); + bool will_transposed = (rotation == 90 || rotation == 270); + if (transposed != will_transposed) { + int tmp = self->epaper.core.width; + self->epaper.core.width = self->epaper.core.height; + self->epaper.core.height = tmp; + } + displayio_display_core_set_rotation(&self->epaper.core, rotation); + if (self->lv_display != NULL) { + // LVGL rotates the opposite way from displayio for the transposed orientations. + lv_display_rotation_t lv_rotation; + switch (rotation) { + case 90: + lv_rotation = LV_DISPLAY_ROTATION_270; + break; + case 270: + lv_rotation = LV_DISPLAY_ROTATION_90; + break; + case 180: + lv_rotation = LV_DISPLAY_ROTATION_180; + break; + default: + lv_rotation = LV_DISPLAY_ROTATION_0; + break; + } + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + lv_display_set_rotation(self->lv_display, lv_rotation); + lv_display_set_default(self->lv_display); + self->full_refresh = true; + self->dirty_full = true; + displayio_lvgl_unlock_with_cleanup(); + } + if (self == &displays[0].epaper_display) { + supervisor_stop_terminal(); + supervisor_start_terminal(self->epaper.core.width, self->epaper.core.height); + } + if (self->epaper.core.current_group != NULL) { + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + displayio_lvgl_set_root_group(self->epaper.core.current_group); + displayio_lvgl_unlock_with_cleanup(); + } +} + +// Send one packed plane from the converted framebuffer. The area must already be clipped to +// whole bytes of pixels. +static bool epaperdisplay_lvgl_send_plane(epaperdisplay_epaperdisplay_obj_t *self, uint8_t command, + const uint8_t *buf, const displayio_area_t *area) { + displayio_area_t region = *area; + if (self->epaper.bus.row_command != NO_COMMAND) { + displayio_display_bus_set_region_to_update(&self->epaper.bus, &self->epaper.core.colorspace, ®ion); + } + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_COMMAND, self->epaper.chip_select, &command, 1); + displayio_display_bus_end_transaction(&self->epaper.bus); + + uint16_t bytes_per_row = displayio_area_width(area) * self->canvas_depth / 8; + uint16_t first_byte = area->x1 * self->canvas_depth / 8; + uint8_t chunk[512]; + size_t used = 0; + for (int16_t y = area->y1; y < area->y2; y++) { + const uint8_t *row = buf + y * self->canvas_stride + first_byte; + if (bytes_per_row > sizeof(chunk)) { + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_DATA, self->epaper.chip_select, row, bytes_per_row); + displayio_display_bus_end_transaction(&self->epaper.bus); + } else { + if (used + bytes_per_row > sizeof(chunk)) { + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_DATA, self->epaper.chip_select, chunk, used); + displayio_display_bus_end_transaction(&self->epaper.bus); + used = 0; + } + memcpy(chunk + used, row, bytes_per_row); + used += bytes_per_row; + } + // Run background tasks so they can run during an explicit refresh. + // Auto-refresh won't run background tasks here because it is a background task itself. + RUN_BACKGROUND_TASKS; + + // Run USB background tasks so they can run during an implicit refresh. + #if CIRCUITPY_TINYUSB + usb_background(); + #endif + } + if (used > 0) { + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_DATA, self->epaper.chip_select, chunk, used); + displayio_display_bus_end_transaction(&self->epaper.bus); + } + return true; +} + +static bool epaperdisplay_epaperdisplay_refresh_area(epaperdisplay_epaperdisplay_obj_t *self, + const displayio_area_t *area, bool write_previous) { + displayio_area_t clipped; + // Clip the area to the display by overlapping the areas. If there is no overlap then we're done. + if (!epaperdisplay_lvgl_clip_area(self, area, &clipped)) { + return true; + } + if (write_previous) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.write_previous_ram_command != NO_COMMAND) { + return epaperdisplay_lvgl_send_plane(self, self->epaper.write_previous_ram_command, + self->black_buf, &clipped); + } + #endif + return true; + } + if (!epaperdisplay_lvgl_send_plane(self, self->epaper.write_black_ram_command, self->black_buf, &clipped)) { + return false; + } + if (self->epaper.write_color_ram_command != NO_COMMAND && self->color_buf != NULL) { + if (!epaperdisplay_lvgl_send_plane(self, self->epaper.write_color_ram_command, self->color_buf, &clipped)) { + return false; + } + } + return true; +} + +static bool _clean_area(epaperdisplay_epaperdisplay_obj_t *self) { + uint16_t width = self->canvas_width; + uint16_t height = self->canvas_height; + + uint8_t buffer[width / 2]; + memset(buffer, 0x77, width / 2); + + uint8_t write_command = self->epaper.write_black_ram_command; + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_COMMAND, self->epaper.chip_select, &write_command, 1); + displayio_display_bus_end_transaction(&self->epaper.bus); + + for (uint16_t j = 0; j < height; j++) { + if (!displayio_display_bus_begin_transaction(&self->epaper.bus)) { + // Can't acquire display bus; skip the rest of the data. Try next display. + return false; + } + self->epaper.bus.send(self->epaper.bus.bus, DISPLAY_DATA, self->epaper.chip_select, buffer, width / 2); + displayio_display_bus_end_transaction(&self->epaper.bus); + + // TODO(tannewt): Make refresh displays faster so we don't starve other + // background tasks. + #if CIRCUITPY_TINYUSB + usb_background(); + #endif + } + + return true; +} + +bool common_hal_epaperdisplay_epaperdisplay_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + + if (self->epaper.refreshing && self->epaper.busy.base.type == &digitalio_digitalinout_type) { + if (common_hal_digitalio_digitalinout_get_value(&self->epaper.busy) != self->epaper.busy_state) { + supervisor_disable_tick(); + self->epaper.refreshing = false; + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (!self->epaper.fast) { + // Run stop sequence but don't wait for busy because busy is set when sleeping. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + } + #else + // Run stop sequence but don't wait for busy because busy is set when sleeping. + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + #endif + } else { + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_give_up_if_stuck(&self->epaper); + #endif + return false; + } + } + if (self->epaper.core.current_group == NULL) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + // Nothing to draw, but the drive already started is still owed. + if (self->epaper.lag.frames > 0 && self->epaper.awake) { + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + bool ok = epaperdisplay_lag_refresh(&self->epaper, NULL, 0); + displayio_lvgl_unlock_with_cleanup(); + return ok; + } + #endif + return true; + } + // Refresh at seconds per frame rate. + if (common_hal_epaperdisplay_epaperdisplay_get_time_to_refresh(self) > 0) { + return false; + } + if (!displayio_display_bus_is_free(&self->epaper.bus)) { + // Can't acquire display bus; skip updating this display. Try next display. + return false; + } + + // Hold the LVGL lock from the compose and flush that brings the converted framebuffer up to + // date through the transfers that read it. The render task otherwise shares this display. + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + + if (self->full_refresh && self->lv_display != NULL) { + self->dirty_full = true; + lv_obj_t *screen = lv_display_get_screen_active(self->lv_display); + if (screen != NULL) { + lv_obj_invalidate(screen); + } + } + if (self->lv_display != NULL) { + lv_refr_now(self->lv_display); + } + + displayio_area_t areas[EPAPER_LVGL_MAX_DIRTY]; + uint8_t area_count = 0; + if (self->dirty_full || self->epaper.bus.row_command == NO_COMMAND) { + // Without a RAM window, a short transfer would start at the controller's current cursor + // instead of the dirty area's coordinates, leaving a mixture of old and new frames. + epaperdisplay_lvgl_full_area(self, &areas[0]); + area_count = 1; + } else if (self->dirty_count > 0) { + memcpy(areas, self->dirty, self->dirty_count * sizeof(areas[0])); + area_count = self->dirty_count; + } + + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.lag.frames > 0) { + bool ok = epaperdisplay_lag_refresh(&self->epaper, area_count > 0 ? areas : NULL, area_count); + displayio_lvgl_unlock_with_cleanup(); + return ok; + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + + if (area_count == 0) { + displayio_lvgl_unlock_with_cleanup(); + return true; + } + + if (self->epaper.acep) { + epaperdisplay_lvgl_start_refresh(self); + _clean_area(self); + epaperdisplay_epaperdisplay_finish_refresh(self, NULL, 0); + while (self->epaper.refreshing && !mp_hal_is_interrupted()) { + RUN_BACKGROUND_TASKS; + } + } + if (mp_hal_is_interrupted()) { + displayio_lvgl_unlock_with_cleanup(); + return false; + } + + epaperdisplay_lvgl_start_refresh(self); + for (uint8_t i = 0; i < area_count; i++) { + epaperdisplay_epaperdisplay_refresh_area(self, &areas[i], false); + } + epaperdisplay_epaperdisplay_finish_refresh(self, areas, area_count); + displayio_lvgl_unlock_with_cleanup(); + return true; +} + +void release_epaperdisplay(epaperdisplay_epaperdisplay_obj_t *self) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_shutdown(&self->epaper); + epaperdisplay_lag_free(&self->epaper); + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.refreshing) { + epaperdisplay_epaper_core_wait_for_busy(&self->epaper); + supervisor_disable_tick(); + self->epaper.refreshing = false; + // Run stop sequence but don't wait for busy because busy is set when sleeping. + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.fast) { + epaperdisplay_epaper_core_send_stop_sequence_guarded(&self->epaper); + } else { + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + } + #else + epaperdisplay_epaper_core_send_command_sequence(&self->epaper, false, self->epaper.stop_sequence, self->epaper.stop_sequence_len); + #endif + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + else if (self->epaper.fast && self->epaper.awake) { + epaperdisplay_epaper_core_send_stop_sequence_guarded(&self->epaper); + } + self->epaper.awake = false; + #endif + #if CIRCUITPY_EPAPERDISPLAY_FAST + epaperdisplay_lag_release_interrupts(&self->epaper); + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + + if (self->lv_display != NULL) { + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + displayio_lvgl_set_root_group(NULL); + lv_display_delete(self->lv_display); + self->lv_display = NULL; + displayio_lvgl_unlock_with_cleanup(); + } + // These allocations are from the port heap and outlive the VM, so free them explicitly. + port_free(self->lv_buf); + port_free(self->lv_rotation_buf); + self->lv_buf = NULL; + self->lv_rotation_buf = NULL; + self->lv_buf_size = 0; + self->lv_rotation_buf_size = 0; + port_free(self->black_buf); + port_free(self->color_buf); + self->black_buf = NULL; + self->color_buf = NULL; + self->dirty_count = 0; + self->dirty_full = false; + self->refresh_in_progress = false; + release_display_core(&self->epaper.core); + if (self->epaper.busy.base.type == &digitalio_digitalinout_type) { + common_hal_digitalio_digitalinout_deinit(&self->epaper.busy); + } +} + +void epaperdisplay_epaperdisplay_reset(epaperdisplay_epaperdisplay_obj_t *self) { + #if CIRCUITPY_EPAPERDISPLAY_FAST + if (self->epaper.lag.frames > 0) { + // Only a primary display gets here; reset_displays() has released the others. The heap is + // still here but the sequences won't be, and the display would otherwise persist to draw + // the splash with them. Finish now and stay asleep. Its bus still holds the pins until + // the next VM ends or release_displays(). + epaperdisplay_epaper_core_end_held_bus(&self->epaper); + release_epaperdisplay(self); + self->base.type = &mp_type_NoneType; + return; + } + #endif // CIRCUITPY_EPAPERDISPLAY_FAST + displayio_display_core_set_root_group(&self->epaper.core, &circuitpython_splash); + if (self->lv_display != NULL) { + nlr_jump_callback_node_t cleanup; + displayio_lvgl_lock_with_cleanup(&cleanup); + self->full_refresh = true; + self->dirty_full = true; + lv_display_set_default(self->lv_display); + displayio_lvgl_set_root_group(&circuitpython_splash); + lv_obj_t *screen = lv_display_get_screen_active(self->lv_display); + if (screen != NULL) { + lv_obj_invalidate(screen); + } + displayio_lvgl_unlock_with_cleanup(); + } else { + self->full_refresh = true; + self->dirty_full = true; + } + #if CIRCUITPY_EPAPERDISPLAY_FAST + // Let the panel sleep after the next refresh when code isn't running. + if (self->epaper.fast && self->epaper.awake && !self->epaper.refreshing) { + // Nothing can catch a raise from a send. A reload may be pending. + epaperdisplay_epaper_core_end_held_bus(&self->epaper); + epaperdisplay_epaper_core_send_stop_sequence_guarded(&self->epaper); + self->epaper.awake = false; + } + self->epaper.fast = false; + #endif +} + +uint16_t common_hal_epaperdisplay_epaperdisplay_get_width(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_width(&self->epaper); +} + +uint16_t common_hal_epaperdisplay_epaperdisplay_get_height(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_height(&self->epaper); +} + +uint16_t common_hal_epaperdisplay_epaperdisplay_get_rotation(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_rotation(&self->epaper); +} + +mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_root_group(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_root_group(&self->epaper); +} + +mp_obj_t common_hal_epaperdisplay_epaperdisplay_get_bus(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_bus(&self->epaper); +} + +uint32_t common_hal_epaperdisplay_epaperdisplay_get_time_to_refresh(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_time_to_refresh(&self->epaper); +} + +bool common_hal_epaperdisplay_epaperdisplay_get_busy(epaperdisplay_epaperdisplay_obj_t *self) { + return epaperdisplay_epaper_core_get_busy(&self->epaper); +} + +void epaperdisplay_epaperdisplay_change_refresh_mode_parameters(epaperdisplay_epaperdisplay_obj_t *self, + mp_buffer_info_t *start_sequence, mp_buffer_info_t *refresh_sequence, float seconds_per_frame) { + epaperdisplay_epaper_core_change_refresh_mode_parameters(&self->epaper, + start_sequence, refresh_sequence, seconds_per_frame); +} + +void epaperdisplay_epaperdisplay_background(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_background(&self->epaper); +} + +void epaperdisplay_epaperdisplay_collect_ptrs(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_collect_ptrs(&self->epaper); +} + +#if CIRCUITPY_EPAPERDISPLAY_FAST +void epaperdisplay_epaperdisplay_prepare_release(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_prepare_release(&self->epaper); +} + +void epaperdisplay_epaperdisplay_end_held_bus(epaperdisplay_epaperdisplay_obj_t *self) { + epaperdisplay_epaper_core_end_held_bus(&self->epaper); +} + +bool common_hal_epaperdisplay_epaperdisplay_clean(epaperdisplay_epaperdisplay_obj_t *self, uint8_t frames, bool full) { + return epaperdisplay_epaper_core_clean(&self->epaper, frames, full); +} +#endif diff --git a/shared-module/epaperdisplay/lvgl/EPaperDisplay.h b/shared-module/epaperdisplay/lvgl/EPaperDisplay.h new file mode 100644 index 00000000000..34d89d0f604 --- /dev/null +++ b/shared-module/epaperdisplay/lvgl/EPaperDisplay.h @@ -0,0 +1,47 @@ +// This file is part of the CircuitPython project: https://circuitpython.org +// +// SPDX-FileCopyrightText: Copyright (c) 2019 Scott Shawcroft for Adafruit Industries +// SPDX-FileCopyrightText: Copyright (c) 2026 Scott Shawcroft for Adafruit Industries +// +// SPDX-License-Identifier: MIT + +#pragma once + +#include "shared-module/epaperdisplay/epaper_core.h" + +#include "lvgl.h" + +// Dirty rectangles kept since the last panel refresh. When more than this arrive they are +// merged into one bounding box, which is still correct because every one is inside it. +#define EPAPER_LVGL_MAX_DIRTY 8 + +struct epaperdisplay_epaperdisplay_obj_t { + mp_obj_base_t base; + epaperdisplay_epaper_core_t epaper; + + // LVGL display. The draw buffer is RGB565; the flush callback converts it into the + // packed panel planes below. + lv_display_t *lv_display; + lv_color_format_t lv_color_format; + uint8_t *lv_buf; + size_t lv_buf_size; + uint8_t *lv_rotation_buf; + size_t lv_rotation_buf_size; + + // The converted framebuffer. Each byte holds (8 / canvas_depth) panel pixels, most + // significant pixel first, exactly as the panel RAM does. black_buf always exists. + // color_buf exists when the panel has a separate color RAM. + uint8_t *black_buf; + uint8_t *color_buf; + uint16_t canvas_stride; + uint16_t canvas_width; // Physical panel width, not the rotated display width. + uint16_t canvas_height; + uint8_t canvas_depth; + + // Areas the flush callback changed since the last panel refresh. + displayio_area_t dirty[EPAPER_LVGL_MAX_DIRTY]; + uint8_t dirty_count; + bool dirty_full; + bool refresh_in_progress; + bool full_refresh; +}; diff --git a/shared-module/framebufferio/legacy/FramebufferDisplay.c b/shared-module/framebufferio/legacy/FramebufferDisplay.c index d9d9bdbd494..f8fbd83fd5d 100644 --- a/shared-module/framebufferio/legacy/FramebufferDisplay.c +++ b/shared-module/framebufferio/legacy/FramebufferDisplay.c @@ -269,21 +269,7 @@ static void _refresh_display(framebufferio_framebufferdisplay_obj_t *self) { } void common_hal_framebufferio_framebufferdisplay_set_rotation(framebufferio_framebufferdisplay_obj_t *self, int rotation) { - bool transposed = (self->core.rotation == 90 || self->core.rotation == 270); - bool will_transposed = (rotation == 90 || rotation == 270); - if (transposed != will_transposed) { - int tmp = self->core.width; - self->core.width = self->core.height; - self->core.height = tmp; - } - displayio_display_core_set_rotation(&self->core, rotation); - if (self == &displays[0].framebuffer_display) { - supervisor_stop_terminal(); - supervisor_start_terminal(self->core.width, self->core.height); - } - if (self->core.current_group != NULL) { - displayio_group_update_transform(self->core.current_group, &self->core.transform); - } + displayio_display_core_set_rotation_and_update(&self->core, rotation, &self->base); } uint16_t common_hal_framebufferio_framebufferdisplay_get_rotation(framebufferio_framebufferdisplay_obj_t *self) {