From 2496dea5c21190d7588ffe2c4e2cdf565ff55397 Mon Sep 17 00:00:00 2001 From: Shadowtrance Date: Wed, 9 Sep 2026 05:57:41 +1000 Subject: [PATCH] M5Stack PaperS3 display driver improved (#647) --- .../bindings/m5stack,papers3-display.yaml | 9 +- Devices/m5stack-papers3/device.properties | 2 +- .../source/drivers/epd_board_m5papers3.c | 177 ++++++++++++++++++ .../source/drivers/epd_board_m5papers3.h | 20 ++ .../source/drivers/papers3_display.cpp | 154 +++++++++++++-- .../source/drivers/papers3_display.h | 2 +- Tactility/idf_component.yml | 4 +- 7 files changed, 347 insertions(+), 21 deletions(-) create mode 100644 Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.c create mode 100644 Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.h diff --git a/Devices/m5stack-papers3/bindings/m5stack,papers3-display.yaml b/Devices/m5stack-papers3/bindings/m5stack,papers3-display.yaml index 5e6836f3..f0c534fa 100644 --- a/Devices/m5stack-papers3/bindings/m5stack,papers3-display.yaml +++ b/Devices/m5stack-papers3/bindings/m5stack,papers3-display.yaml @@ -10,10 +10,13 @@ properties: type: int default: 20 description: Ambient temperature in °C, used for waveform timing compensation - draw-mode: + quality-draw-mode: type: int - default: MODE_DU - description: Default EpdDrawMode waveform used for screen updates (e.g. MODE_DU, MODE_GC16) + default: MODE_GC16 + description: > + EpdDrawMode waveform used for full-quality refreshes (e.g. MODE_GC16, MODE_GL16). + Fast partial updates always use MODE_DU internally and are not configurable - see + driver comments. rotation: type: int default: EPD_ROT_PORTRAIT diff --git a/Devices/m5stack-papers3/device.properties b/Devices/m5stack-papers3/device.properties index ab703f9d..66f6a403 100644 --- a/Devices/m5stack-papers3/device.properties +++ b/Devices/m5stack-papers3/device.properties @@ -7,7 +7,7 @@ apps.launcherAppId=tactility.launcher hardware.target=esp32s3 hardware.flashSize=16MB hardware.spiRam=true -hardware.spiRamMode=OPI +hardware.spiRamMode=OCT hardware.spiRamSpeed=80M hardware.esptoolFlashFreq=80M hardware.tinyUsbMsc=true diff --git a/Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.c b/Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.c new file mode 100644 index 00000000..24362913 --- /dev/null +++ b/Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.c @@ -0,0 +1,177 @@ +// SPDX-License-Identifier: Apache-2.0 +/** + * Board definition for M5Stack PaperS3. + * + * Kept out-of-tree (see epd_board_m5papers3.h) instead of forking epdiy: this file only + * uses epdiy's public API, so it builds as an ordinary consumer of the upstream component. + * + * Pin mapping from M5GFX source code (authoritative reference): + * https://github.com/m5stack/M5GFX/blob/master/src/M5GFX.cpp + * + * Data bus: DB0-DB7 on GPIO 6,14,7,12,9,11,8,10 + * Control: STH=13, LEH=15, STV=17, CKV=18, CKH=16 + * Power: PWR=46, OE=45 + */ + +#include "epd_board_m5papers3.h" + +#include +#include "epdiy.h" + +#include +#include "esp_log.h" + +#include +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" + +#ifndef CONFIG_IDF_TARGET_ESP32S3 +#error "M5Paper S3 board only supports ESP32-S3" +#endif + +static const char* TAG = "m5paper_s3"; + +/* Data Lines - from M5GFX source */ +#define D0 GPIO_NUM_6 +#define D1 GPIO_NUM_14 +#define D2 GPIO_NUM_7 +#define D3 GPIO_NUM_12 +#define D4 GPIO_NUM_9 +#define D5 GPIO_NUM_11 +#define D6 GPIO_NUM_8 +#define D7 GPIO_NUM_10 + +/* Control Lines - from M5GFX source */ +#define STH GPIO_NUM_13 /* Start pulse horizontal (active low) */ +#define LEH GPIO_NUM_15 /* Latch enable horizontal */ +#define STV GPIO_NUM_17 /* Start vertical */ +#define CKV GPIO_NUM_18 /* Clock vertical */ +#define CKH GPIO_NUM_16 /* Clock horizontal - LCD peripheral clock output */ + +/* Power control - from M5GFX source */ +#define PWR_PIN GPIO_NUM_46 /* Main power enable */ +#define OE_PIN GPIO_NUM_45 /* Output enable */ + + +static lcd_bus_config_t lcd_config = { + .clock = CKH, + .ckv = CKV, + .leh = LEH, + .start_pulse = STH, + .stv = STV, + .data[0] = D0, + .data[1] = D1, + .data[2] = D2, + .data[3] = D3, + .data[4] = D4, + .data[5] = D5, + .data[6] = D6, + .data[7] = D7, +}; + +static void epd_board_init(uint32_t epd_row_width, const EpdInitConfig* init_config) { + (void)init_config; + ESP_LOGI(TAG, "Initializing M5Paper S3 board"); + + /* Configure power pin - start with power off */ + gpio_reset_pin(PWR_PIN); + gpio_set_direction(PWR_PIN, GPIO_MODE_OUTPUT); + gpio_set_level(PWR_PIN, 0); + + /* Configure output enable pin - active high */ + gpio_reset_pin(OE_PIN); + gpio_set_direction(OE_PIN, GPIO_MODE_OUTPUT); + gpio_set_level(OE_PIN, 0); + + const EpdDisplay_t* display = epd_get_display(); + + LcdEpdConfig_t config = { + .pixel_clock = display->bus_speed * 1000 * 1000, + .ckv_high_time = 60, + .line_front_porch = 4, + .le_high_time = 4, + .bus_width = display->bus_width, + .bus = lcd_config, + }; + + epd_lcd_init(&config, display->width, display->height); + + ESP_LOGI(TAG, "Board initialized: %dx%d @ %dMHz", + display->width, display->height, display->bus_speed); +} + +static void epd_board_deinit() { + ESP_LOGI(TAG, "Deinitializing M5Paper S3 board"); + + /* Disable output first */ + gpio_set_level(OE_PIN, 0); + + /* Power off display */ + gpio_set_level(PWR_PIN, 0); + + epd_lcd_deinit(); +} + +static void epd_board_set_ctrl(epd_ctrl_state_t* state, const epd_ctrl_state_t* const mask) { + /* Handle output enable changes */ + if (mask->ep_output_enable) { + gpio_set_level(OE_PIN, state->ep_output_enable ? 1 : 0); + } +} + +static void epd_board_poweron(epd_ctrl_state_t* state) { + ESP_LOGI(TAG, "Powering on display"); + + /* Enable main power first */ + gpio_set_level(PWR_PIN, 1); + + /* Wait for power to stabilize */ + vTaskDelay(pdMS_TO_TICKS(100)); + + /* Enable output */ + gpio_set_level(OE_PIN, 1); + + /* Update state */ + state->ep_stv = true; + state->ep_mode = false; + state->ep_output_enable = true; + state->ep_sth = true; +} + +static void epd_board_poweroff(epd_ctrl_state_t* state) { + ESP_LOGI(TAG, "Powering off display"); + + /* Disable output first */ + gpio_set_level(OE_PIN, 0); + + state->ep_stv = false; + state->ep_output_enable = false; + state->ep_mode = false; + state->ep_sth = false; + + /* Small delay before cutting power */ + vTaskDelay(pdMS_TO_TICKS(10)); + + /* Cut main power */ + gpio_set_level(PWR_PIN, 0); +} + +static float epd_board_ambient_temperature() { + /* TODO: Could read from BMI270 temperature sensor */ + return 20.0f; +} + +const EpdBoardDefinition epd_board_m5papers3 = { + .init = epd_board_init, + .deinit = epd_board_deinit, + .set_ctrl = epd_board_set_ctrl, + .poweron = epd_board_poweron, + .poweroff = epd_board_poweroff, + .get_temperature = epd_board_ambient_temperature, + // No hardware VCOM control path on this board yet - a non-null callback that doesn't touch + // hardware would let epd_set_vcom() complete without changing anything on the panel. + .set_vcom = NULL, + .gpio_set_direction = NULL, + .gpio_read = NULL, + .gpio_write = NULL, +}; diff --git a/Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.h b/Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.h new file mode 100644 index 00000000..88c9e618 --- /dev/null +++ b/Devices/m5stack-papers3/source/drivers/epd_board_m5papers3.h @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: Apache-2.0 +/** + * @file "epd_board_m5papers3.h" + * @brief Board definition for M5Stack PaperS3, kept out-of-tree because upstream epdiy + * (https://github.com/vroland/epdiy) does not support this board. + */ + +#pragma once + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern const EpdBoardDefinition epd_board_m5papers3; + +#ifdef __cplusplus +} +#endif diff --git a/Devices/m5stack-papers3/source/drivers/papers3_display.cpp b/Devices/m5stack-papers3/source/drivers/papers3_display.cpp index 949c1d43..81ff1b92 100644 --- a/Devices/m5stack-papers3/source/drivers/papers3_display.cpp +++ b/Devices/m5stack-papers3/source/drivers/papers3_display.cpp @@ -7,8 +7,10 @@ #include #include #include +#include + +#include "epd_board_m5papers3.h" -#include #include #include @@ -19,6 +21,70 @@ #define TAG "Papers3Display" #define GET_CONFIG(device) (static_cast((device)->config)) +// Fast partial updates are always MODE_DU (strict black/white); config->quality_draw_mode is +// only used for the periodic full-quality pass. +static constexpr EpdDrawMode FAST_DRAW_MODE = MODE_DU; + +// A partial update covering at least this fraction of the panel is a full-screen content change +// (e.g. an app switch rebuilding the whole window, see lvgl.md) rather than a small widget +// redraw, and is promoted to a quality refresh immediately. +static constexpr float FULL_AREA_QUALITY_THRESHOLD = 0.6f; + +// Bounds worst-case ghost accumulation during sustained fast-mode interaction (e.g. scrolling), +// regardless of idle time. LVGL's PARTIAL-mode draw buffer covers vres/10 rows (see +// lvgl-module/source/devices/devices.cpp's buffer_height), so a single full-screen redraw is +// already ~10 tiles - this must clear a full sweep comfortably, or a normal full-screen redraw +// gets promoted to slow GC16 partway through. +static constexpr uint32_t QUALITY_REFRESH_PARTIAL_COUNT = 20; + +// Cleans up ghosting left behind after interaction stops, since nothing else triggers a refresh +// once draw_bitmap() calls stop arriving. Matches the M5Stack official demo's timer. +static constexpr uint32_t QUALITY_REFRESH_IDLE_SECONDS = 10; + +// LVGL's PARTIAL render mode flushes one draw_bitmap() call per still-unjoined dirty rect, so +// one visual refresh is usually several back-to-back calls, not one; this holds quality mode +// across a sibling rect's near-zero gap so they don't end up on inconsistent modes. Must stay +// well under a GC16 draw's own duration (400ms+), or it also bridges the much larger gap between +// separate real frames and pins a whole multi-frame interaction to GC16. +static constexpr uint32_t QUALITY_HOLD_MS = 50; + +// epd_fullclear() (white fill + GC16 draw + 3-cycle black/white flash, see epdiy's +// highlevel.c/render.c) only runs once, at boot (papers3_display_init()), never periodically: +// it wipes the whole panel, and this driver has no way to force LVGL to redraw everything +// afterward - only whatever rect is drawn next gets restored, leaving the rest blank. + +// 4x4 ordered (Bayer) dither thresholds, spread evenly across a 0-15 nibble range. +static constexpr uint8_t BAYER_4X4[4][4] = { + { 0, 8, 2, 10 }, + { 12, 4, 14, 6 }, + { 3, 11, 1, 9 }, + { 15, 7, 13, 5 }, +}; + +// Dithers an 8-bit luminance sample (0x00=black..0xFF=white) down to a 4-bit nibble +// (0x0=black..0xF=white, matching EPDiy's MODE_PACKING_2PPB), spreading the rounding error +// spatially instead of truncating every pixel the same way - this is what turns flat/banded +// output into something that reads as smooth grayscale. +static inline uint8_t dither_to_nibble(uint8_t luminance, int32_t x, int32_t y) { + // BAYER_4X4 is 0-15; scaled by 17 it spans a full 0-255 quantization step (one increment of + // luminance*15), so the dither bias is actually comparable to the rounding it perturbs + // instead of a few percent of one step. + const uint32_t threshold = BAYER_4X4[y & 3][x & 3] * 17U; + const uint32_t level = (static_cast(luminance) * 15U + threshold) / 255U; + return static_cast(level > 15U ? 15U : level); +} + +// Binary variant for MODE_DU, which only supports pure black/white (see epdiy.h) - dithering +// still applies so a partial-update area doesn't look coarser than the quality pass that +// preceded it. +static inline uint8_t dither_to_bw_nibble(uint8_t luminance, int32_t x, int32_t y) { + // *16 (not 17) keeps the max threshold at 240, strictly below 255 - otherwise luminance 0xFF + // (pure white) would tie the top Bayer cell's threshold and the strict ">" would misclassify + // it as black. + const uint32_t threshold = BAYER_4X4[y & 3][x & 3] * 16U; + return luminance > threshold ? 0xF : 0x0; +} + extern "C" { extern Module m5stack_papers3_module; @@ -34,6 +100,15 @@ struct Papers3DisplayInternal { // Scratch buffer for the grayscale8->EPDiy(4bpp packed, 2px/byte) conversion in draw_bitmap(). uint8_t* packed_buffer; bool powered; + uint32_t panel_pixel_count; + // Fast (MODE_DU) partial updates since the last quality refresh; see + // QUALITY_REFRESH_PARTIAL_COUNT. + uint32_t partial_count_since_quality; + // get_ticks() at the last quality refresh; see QUALITY_REFRESH_IDLE_SECONDS. + TickType_t last_quality_refresh_tick; + // While get_ticks() < this, every draw_bitmap() call uses quality mode regardless of the + // other triggers; see QUALITY_HOLD_MS. + TickType_t quality_hold_until_tick; }; static void power_on(Papers3DisplayInternal* internal) { @@ -64,9 +139,48 @@ static error_t papers3_display_init(Device* device) { // pass, leaving a faint ghost. Run a full clear now, before LVGL's first flush ever reaches // draw_bitmap(), so it never has to undo content LVGL already put on screen. epd_fullclear(&internal->hl_state, config->temperature_celsius); + internal->partial_count_since_quality = 0; + internal->last_quality_refresh_tick = get_ticks(); + internal->quality_hold_until_tick = 0; return ERROR_NONE; } +// Decides whether this update should be a full-quality (config->quality_draw_mode) refresh or +// a fast MODE_DU one. Read-only - see commit_quality_mode_decision() for the state this decision +// leads to. +static bool should_use_quality_mode(Papers3DisplayInternal* internal, int32_t width, int32_t height) { + const TickType_t now = get_ticks(); + + const uint32_t area = static_cast(width) * static_cast(height); + const bool is_full_screen_change = area >= static_cast( + static_cast(internal->panel_pixel_count) * FULL_AREA_QUALITY_THRESHOLD + ); + const bool partial_count_exceeded = internal->partial_count_since_quality >= QUALITY_REFRESH_PARTIAL_COUNT; + // Idle refresh is too problematic to worth the possible gains. So it isn't done on purpose. + // Ghosting is very minimal now anyway (it's still around but way less bad) + const bool idle_exceeded = now - internal->last_quality_refresh_tick >= seconds_to_ticks(QUALITY_REFRESH_IDLE_SECONDS); + const bool within_hold = now < internal->quality_hold_until_tick; + + return is_full_screen_change || partial_count_exceeded || idle_exceeded || within_hold; +} + +// Applies should_use_quality_mode()'s decision, but only commits the quality-mode reset once the +// draw actually succeeded - a failed quality refresh must not make a still-ghosting panel look +// freshly cleaned to every trigger above. A failed fast update still counts toward the partial +// count, since it was still MODE_DU content, not a clean slate. +static void commit_quality_mode_decision(Papers3DisplayInternal* internal, bool used_quality, bool draw_succeeded) { + if (used_quality) { + if (draw_succeeded) { + const TickType_t now = get_ticks(); + internal->partial_count_since_quality = 0; + internal->last_quality_refresh_tick = now; + internal->quality_hold_until_tick = now + millis_to_ticks(QUALITY_HOLD_MS); + } + } else { + internal->partial_count_since_quality++; + } +} + // Reports GRAYSCALE8 (not MONOCHROME) so LVGL uses partial/tile updates instead of forcing // full-frame - the bridge hardcodes full-frame for MONOCHROME/I1 regardless of capability flags. // So draw_bitmap is called once per changed tile, not necessarily the whole panel. @@ -76,11 +190,12 @@ static error_t papers3_display_draw_bitmap(Device* device, int32_t x_start, int3 const int32_t width = x_end - x_start; const int32_t height = y_end - y_start; + const bool use_quality = should_use_quality_mode(internal, width, height); // color_data is DISPLAY_COLOR_FORMAT_GRAYSCALE8: row-major, 1 byte/pixel luminance // (0x00=black..0xFF=white, matching LVGL's L8). EPDiy wants 4bpp packed (2px/byte, 0x0=black, - // 0xF=white) - a plain >>4 truncation preserves all 16 real gray levels the panel supports - // (this panel is not B/W-only; see MODE_GC16/GL16 in papers3-display.yaml's draw-mode doc). + // 0xF=white); Bayer dithering (full 16-level for the quality pass, binary for MODE_DU) + // spreads the rounding error instead of a flat truncation. const auto* src = static_cast(color_data); const size_t src_stride = static_cast(width); const size_t packed_stride = static_cast(width + 1) / 2; @@ -90,12 +205,18 @@ static error_t papers3_display_draw_bitmap(Device* device, int32_t x_start, int3 uint8_t* dst_row = internal->packed_buffer + static_cast(row) * packed_stride; int32_t col = 0; for (; col + 2 <= width; col += 2) { - const uint8_t p0 = src_row[col] >> 4U; - const uint8_t p1 = src_row[col + 1] >> 4U; + const uint8_t p0 = use_quality + ? dither_to_nibble(src_row[col], x_start + col, y_start + row) + : dither_to_bw_nibble(src_row[col], x_start + col, y_start + row); + const uint8_t p1 = use_quality + ? dither_to_nibble(src_row[col + 1], x_start + col + 1, y_start + row) + : dither_to_bw_nibble(src_row[col + 1], x_start + col + 1, y_start + row); dst_row[col / 2] = static_cast((p1 << 4U) | p0); } if (col < width) { // odd width: last column has no pair, low nibble unused - dst_row[col / 2] = static_cast(src_row[col] >> 4U); + dst_row[col / 2] = use_quality + ? dither_to_nibble(src_row[col], x_start + col, y_start + row) + : dither_to_bw_nibble(src_row[col], x_start + col, y_start + row); } } @@ -108,13 +229,15 @@ static error_t papers3_display_draw_bitmap(Device* device, int32_t x_start, int3 power_on(internal); epd_draw_rotated_image(update_area, internal->packed_buffer, internal->framebuffer); + const auto draw_mode = use_quality ? config->quality_draw_mode : FAST_DRAW_MODE; auto draw_result = epd_hl_update_area( &internal->hl_state, - static_cast(config->draw_mode | MODE_PACKING_2PPB), + static_cast(draw_mode | MODE_PACKING_2PPB), config->temperature_celsius, update_area ); + commit_quality_mode_decision(internal, use_quality, draw_result == EPD_DRAW_SUCCESS); return draw_result == EPD_DRAW_SUCCESS ? ERROR_NONE : ERROR_RESOURCE; } @@ -133,13 +256,11 @@ static DisplayColorFormat papers3_display_get_color_format(Device*) { return DISPLAY_COLOR_FORMAT_GRAYSCALE8; } -// epd_width()/epd_height() are the panel's native, unrotated dimensions (display->width/height in -// epdiy.c) - epd_rotated_display_width()/height() swap them for EPD_ROT_PORTRAIT/INVERTED_PORTRAIT. -// epd_draw_rotated_image() clamps its input rect against the *rotated* dims and epd_draw_pixel() -// applies the rotation transform on top of that (see _rotate() in epdiy.c), so both LVGL's canvas -// size and draw_bitmap()'s rect must be in rotated-space, not native-space - using the native -// epd_width()/epd_height() here fed rotated-space code a landscape-sized canvas, which produced -// exactly the "rotated + landscape" symptom this was fixed for. +// epd_width()/epd_height() are the panel's native, unrotated dimensions; epd_rotated_display_ +// width()/height() swap them for EPD_ROT_PORTRAIT/INVERTED_PORTRAIT. epd_draw_rotated_image() +// clamps its input rect against the rotated dims and epd_draw_pixel() applies the rotation +// transform on top of that (see _rotate() in epdiy.c), so both LVGL's canvas size and +// draw_bitmap()'s rect must be in rotated-space, not native-space. static uint16_t papers3_display_get_resolution_x(Device*) { return static_cast(epd_rotated_display_width()); } @@ -232,6 +353,11 @@ static error_t start(Device* device) { return ERROR_OUT_OF_MEMORY; } + internal->panel_pixel_count = static_cast(epd_rotated_display_width()) * static_cast(epd_rotated_display_height()); + internal->partial_count_since_quality = 0; + internal->last_quality_refresh_tick = get_ticks(); + internal->quality_hold_until_tick = 0; + device_set_driver_data(device, internal); LOG_I(TAG, "EPDiy initialized (%dx%d native, %dx%d rotated)", epd_width(), epd_height(), epd_rotated_display_width(), epd_rotated_display_height()); diff --git a/Devices/m5stack-papers3/source/drivers/papers3_display.h b/Devices/m5stack-papers3/source/drivers/papers3_display.h index f293e83a..297ff1ed 100644 --- a/Devices/m5stack-papers3/source/drivers/papers3_display.h +++ b/Devices/m5stack-papers3/source/drivers/papers3_display.h @@ -10,7 +10,7 @@ extern "C" { struct Papers3DisplayConfig { int temperature_celsius; - enum EpdDrawMode draw_mode; + enum EpdDrawMode quality_draw_mode; enum EpdRotation rotation; }; diff --git a/Tactility/idf_component.yml b/Tactility/idf_component.yml index 797cf644..962baf3e 100644 --- a/Tactility/idf_component.yml +++ b/Tactility/idf_component.yml @@ -77,8 +77,8 @@ dependencies: espressif/esp_lvgl_port: "2.7.2" lvgl/lvgl: "9.3.0" epdiy: - git: https://github.com/Shadowtrance/epdiy.git - version: 2.0.1 + git: https://github.com/vroland/epdiy.git + version: 2.1.3 rules: # More hardware might be supported - enable as needed - if: "target in [esp32s3]"