M5Stack PaperS3 display driver improved (#647)

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

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

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 <stdint.h>
+#include "epdiy.h"
+
+#include <output_lcd/lcd_driver.h>
+#include "esp_log.h"
+
+#include <driver/gpio.h>
+#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,
+};

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 <epd_board.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern const EpdBoardDefinition epd_board_m5papers3;
+
+#ifdef __cplusplus
+}
+#endif

Devices/m5stack-papers3/source/drivers/papers3_display.cpp

@@ -7,8 +7,10 @@
 #include <tactility/error.h>
 #include <tactility/log.h>
 #include <tactility/module.h>
+#include <tactility/time.h>
+
+#include "epd_board_m5papers3.h"
 
-#include <epd_board.h>
 #include <epdiy.h>
 
 #include <esp_heap_caps.h>
@@ -19,6 +21,70 @@
 #define TAG "Papers3Display"
 #define GET_CONFIG(device) (static_cast<const Papers3DisplayConfig*>((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<uint32_t>(luminance) * 15U + threshold) / 255U;
+    return static_cast<uint8_t>(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<uint32_t>(width) * static_cast<uint32_t>(height);
+    const bool is_full_screen_change = area >= static_cast<uint32_t>(
+        static_cast<float>(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<const uint8_t*>(color_data);
     const size_t src_stride = static_cast<size_t>(width);
     const size_t packed_stride = static_cast<size_t>(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<size_t>(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<uint8_t>((p1 << 4U) | p0);
         }
         if (col < width) { // odd width: last column has no pair, low nibble unused
-            dst_row[col / 2] = static_cast<uint8_t>(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<EpdDrawMode>(config->draw_mode | MODE_PACKING_2PPB),
+        static_cast<EpdDrawMode>(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<uint16_t>(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<uint32_t>(epd_rotated_display_width()) * static_cast<uint32_t>(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());

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