From 5d4d91f77512ca7aa2f0dd07cbb09385f397834c Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Tue, 5 Mar 2024 14:53:42 +1300
Subject: [PATCH 01/19] Move Wireless Paper V1.1 custom hibernate behavior to
 GxEPD2

---
 src/graphics/EInkDisplay2.cpp            | 6 +++---
 variants/heltec_wireless_paper/variant.h | 1 -
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp
index aee30c7f84..026a65e6dc 100644
--- a/src/graphics/EInkDisplay2.cpp
+++ b/src/graphics/EInkDisplay2.cpp
@@ -84,10 +84,10 @@ bool EInkDisplay::forceDisplay(uint32_t msecLimit)
     adafruitDisplay->nextPage();
 #endif
 
-#ifndef EINK_NO_HIBERNATE // Only hibernate if controller IC will preserve image memory
-    // Put screen to sleep to save power (possibly not necessary because we already did poweroff inside of display)
+    // Power off display hardware
+    // Most models: deep sleep.
+    // Wireless Paper V1.1: power off only. Deep sleep clears memory - problems with fast refresh
     adafruitDisplay->hibernate();
-#endif
 
     LOG_DEBUG("done\n");
     return true;
diff --git a/variants/heltec_wireless_paper/variant.h b/variants/heltec_wireless_paper/variant.h
index 28bc8628a5..29b8bbbd14 100644
--- a/variants/heltec_wireless_paper/variant.h
+++ b/variants/heltec_wireless_paper/variant.h
@@ -5,7 +5,6 @@
 #define I2C_SCL SCL
 
 #define USE_EINK
-#define EINK_NO_HIBERNATE
 
 /*
  * eink display pins

From 07da13058684b0d5517d3bfd54a3e2d857e9e5a8 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Thu, 7 Mar 2024 03:26:31 +1300
Subject: [PATCH 02/19] Async full-refresh for EInkDynamicDisplay

---
 src/graphics/EInkDisplay2.cpp                 | 25 +++---
 src/graphics/EInkDisplay2.h                   |  7 ++
 src/graphics/EInkDynamicDisplay.cpp           | 90 +++++++++++++++++--
 src/graphics/EInkDynamicDisplay.h             | 15 +++-
 variants/heltec_wireless_paper/platformio.ini |  3 +-
 .../heltec_wireless_paper_v1/platformio.ini   |  3 +-
 6 files changed, 117 insertions(+), 26 deletions(-)

diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp
index 026a65e6dc..a544833c16 100644
--- a/src/graphics/EInkDisplay2.cpp
+++ b/src/graphics/EInkDisplay2.cpp
@@ -71,28 +71,24 @@ bool EInkDisplay::forceDisplay(uint32_t msecLimit)
         }
     }
 
+    // Trigger the refresh in GxEPD2
     LOG_DEBUG("Updating E-Paper... ");
-
-#if false
-    // Currently unused; rescued from commented-out line during a refactor
-    // Use a meaningful macro here if variant doesn't want fast refresh
-
-    // Full update mode (slow)
-    adafruitDisplay->display(false)
-#else
-    // Fast update mode
     adafruitDisplay->nextPage();
-#endif
 
-    // Power off display hardware
-    // Most models: deep sleep.
-    // Wireless Paper V1.1: power off only. Deep sleep clears memory - problems with fast refresh
-    adafruitDisplay->hibernate();
+    // End the update process
+    endUpdate();
 
     LOG_DEBUG("done\n");
     return true;
 }
 
+// End the update process - virtual method, overriden in derived class
+void EInkDisplay::endUpdate()
+{
+    // Power off display hardware, then deep-sleep (Except Wireless Paper V1.1, no deep-sleep)
+    adafruitDisplay->hibernate();
+}
+
 // Write the buffer to the display memory
 void EInkDisplay::display(void)
 {
@@ -193,6 +189,7 @@ bool EInkDisplay::connect()
         // Init GxEPD2
         adafruitDisplay->init();
         adafruitDisplay->setRotation(3);
+        adafruitDisplay->clearScreen(); // Clearing now, so the boot logo will draw nice and smoothe (fast refresh)
     }
 #elif defined(PCA10059)
     {
diff --git a/src/graphics/EInkDisplay2.h b/src/graphics/EInkDisplay2.h
index 75770a3bcf..f744164949 100644
--- a/src/graphics/EInkDisplay2.h
+++ b/src/graphics/EInkDisplay2.h
@@ -45,6 +45,13 @@ class EInkDisplay : public OLEDDisplay
      */
     virtual bool forceDisplay(uint32_t msecLimit = 1000);
 
+    /**
+     * Run any code needed to complete an update, after the physical refresh has completed.
+     * Split from forceDisplay(), to enable async refresh in derived EInkDynamicDisplay class.
+     *
+     */
+    virtual void endUpdate();
+
     /**
      * shim to make the abstraction happy
      *
diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index ae1e30fe1e..75db0e33fe 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -94,19 +94,29 @@ void EInkDynamicDisplay::adjustRefreshCounters()
 // Trigger the display update by calling base class
 bool EInkDynamicDisplay::update()
 {
+    // Detemine the refresh mode to use, and start the update
     bool refreshApproved = determineMode();
     if (refreshApproved)
         EInkDisplay::forceDisplay(0); // Bypass base class' own rate-limiting system
-    return refreshApproved;           // (Unutilized) Base class promises to return true if update ran
+
+#if defined(HAS_EINK_ASYNCFULL)
+    if (refreshApproved)
+        endOrDetach(); // Either endUpdate() right now (fast refresh), or set the async flag (full refresh)
+#endif
+
+    return refreshApproved; // (Unutilized) Base class promises to return true if update ran
 }
 
 // Assess situation, pick a refresh type
 bool EInkDynamicDisplay::determineMode()
 {
-    checkWasFlooded();
+    checkForPromotion();
+#if defined(HAS_EINK_ASYNCFULL)
+    checkAsyncFullRefresh();
+#endif
     checkRateLimiting();
 
-    // If too soon for a new time, abort here
+    // If too soon for a new frame, or display busy, abort early
     if (refresh == SKIPPED) {
         storeAndReset();
         return false; // No refresh
@@ -116,7 +126,7 @@ bool EInkDynamicDisplay::determineMode()
 
     resetRateLimiting(); // Once determineMode() ends, will have to wait again
     hashImage();         // Generate here, so we can still copy it to previousImageHash, even if we skip the comparison check
-    LOG_DEBUG("EInkDynamicDisplay: "); // Begin log entry
+    LOG_DEBUG("determineMode(): "); // Begin log entry
 
     // Once mode determined, any remaining checks will bypass
     checkCosmetic();
@@ -151,13 +161,25 @@ bool EInkDynamicDisplay::determineMode()
     }
 }
 
-// Did RESPONSIVE frames previously exceed the rate-limit for fast refresh?
-void EInkDynamicDisplay::checkWasFlooded()
+// Was a frame skipped (rate, display busy) that should have been a FAST refresh?
+void EInkDynamicDisplay::checkForPromotion()
 {
-    if (previousReason == EXCEEDED_RATELIMIT_FAST) {
-        // If so, allow a BACKGROUND frame to draw as RESPONSIVE
-        // Because we DID want a RESPONSIVE frame last time, we just didn't get it
+    // If a frame was skipped (rate, display busy), then promote a BACKGROUND frame
+    // Because we DID want a RESPONSIVE/COSMETIC/DEMAND_FULL frame last time, we just didn't get it
+
+    switch (previousReason) {
+    case ASYNC_REFRESH_BLOCKED_DEMANDFAST:
+        setFrameFlag(DEMAND_FAST);
+        break;
+    case ASYNC_REFRESH_BLOCKED_COSMETIC:
+        setFrameFlag(COSMETIC);
+        break;
+    case ASYNC_REFRESH_BLOCKED_RESPONSIVE:
+    case EXCEEDED_RATELIMIT_FAST:
         setFrameFlag(RESPONSIVE);
+        break;
+    default:
+        break;
     }
 }
 
@@ -381,4 +403,54 @@ void EInkDynamicDisplay::resetGhostPixelTracking()
 }
 #endif // EINK_LIMIT_GHOSTING_PX
 
+#ifdef HAS_EINK_ASYNCFULL
+// Check the status of an "async full-refresh", and run the finish-up code if the hardware is ready
+void EInkDynamicDisplay::checkAsyncFullRefresh()
+{
+    // No refresh taking place, continue with determineMode()
+    if (!asyncRefreshRunning)
+        return;
+
+    // Full refresh still running
+    if (adafruitDisplay->epd2.isBusy()) {
+        // No refresh
+        refresh = SKIPPED;
+
+        // Set the reason, marking what type of frame we're skipping
+        if (frameFlags & DEMAND_FAST)
+            reason = ASYNC_REFRESH_BLOCKED_DEMANDFAST;
+        else if (frameFlags & COSMETIC)
+            reason = ASYNC_REFRESH_BLOCKED_COSMETIC;
+        else if (frameFlags & RESPONSIVE)
+            reason = ASYNC_REFRESH_BLOCKED_RESPONSIVE;
+        else
+            reason = ASYNC_REFRESH_BLOCKED_BACKGROUND;
+
+        return;
+    }
+
+    // If we asyncRefreshRunning flag is still set, but display's BUSY pin reports the refresh is done
+    adafruitDisplay->endAsyncFull(); // Run the end of nextPage() code
+    EInkDisplay::endUpdate();        // Run base-class code to finish off update (NOT our derived class override)
+    asyncRefreshRunning = false;     // Unset the flag
+    LOG_DEBUG("Async full-refresh complete\n");
+
+    // Note: this code only works because of a modification to meshtastic/GxEPD2.
+    // It is only equipped to intercept calls to nextPage()
+}
+
+// Figure out who runs the post-update code
+void EInkDynamicDisplay::endOrDetach()
+{
+    if (previousRefresh == FULL) {  // Note: previousRefresh is the refresh from this loop.
+        asyncRefreshRunning = true; // Set the flag - picked up at start of determineMode(), next loop.
+        LOG_DEBUG("Async full-refresh begins\n");
+    }
+
+    // Fast Refresh
+    else
+        EInkDisplay::endUpdate(); // Still block while updating, but EInkDisplay needs us to call endUpdate() ourselves.
+}
+#endif // HAS_EINK_ASYNCFULL
+
 #endif // USE_EINK_DYNAMICDISPLAY
\ No newline at end of file
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index 2880c716b0..3dc00ba7c8 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -44,6 +44,11 @@ class EInkDynamicDisplay : public EInkDisplay
     };
     enum reasonTypes : uint8_t { // How was the decision reached
         NO_OBJECTIONS,
+        ASYNC_REFRESH_BLOCKED_DEMANDFAST,
+        ASYNC_REFRESH_BLOCKED_COSMETIC,
+        ASYNC_REFRESH_BLOCKED_RESPONSIVE,
+        ASYNC_REFRESH_BLOCKED_BACKGROUND,
+        DISPLAY_NOT_READY_FOR_FULL,
         EXCEEDED_RATELIMIT_FAST,
         EXCEEDED_RATELIMIT_FULL,
         FLAGGED_COSMETIC,
@@ -64,7 +69,7 @@ class EInkDynamicDisplay : public EInkDisplay
     bool update();                // Trigger the display update - determine mode, then call base class
 
     // Checks as part of determineMode()
-    void checkWasFlooded();               // Was the previous frame skipped for exceeding EINK_LIMIT_RATE_RESPONSIVE_SEC?
+    void checkForPromotion();             // Was a frame skipped (rate, display busy) that should have been a FAST refresh?
     void checkRateLimiting();             // Is this frame too soon?
     void checkCosmetic();                 // Was the COSMETIC flag set?
     void checkDemandingFast();            // Was the DEMAND_FAST flag set?
@@ -99,6 +104,14 @@ class EInkDynamicDisplay : public EInkDisplay
     uint8_t *dirtyPixels;           // Any pixels that have been black since last full-refresh (dynamically allocated mem)
     uint32_t ghostPixelCount = 0;   // Number of pixels with problematic ghosting. Retained here for LOG_DEBUG use
 #endif
+
+    // Conditional - async full refresh - only with modified meshtastic/GxEPD2
+#if defined(HAS_EINK_ASYNCFULL)
+    void checkAsyncFullRefresh(); // Check the status of "async full-refresh"; run the post-update code if the hardware is ready
+    void endOrDetach();           // Run the post-update code, or delegate it off to checkAsyncFullRefresh()
+    void endUpdate() override {}  // Disable base-class behavior of running post-update immediately after forceDisplay()
+    bool asyncRefreshRunning = false; // Flag, checked by checkAsyncFullRefresh()
+#endif
 };
 
 #endif
\ No newline at end of file
diff --git a/variants/heltec_wireless_paper/platformio.ini b/variants/heltec_wireless_paper/platformio.ini
index 0abbe085e8..7aebef0148 100644
--- a/variants/heltec_wireless_paper/platformio.ini
+++ b/variants/heltec_wireless_paper/platformio.ini
@@ -16,7 +16,8 @@ build_flags =
   -D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  https://github.com/meshtastic/GxEPD2
+  ; https://github.com/meshtastic/GxEPD2/
+  https://github.com/todd-herbert/meshtastic-GxEPD2#async ; Revert to meshtastic/firmware before submitting PR before final merge
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file
diff --git a/variants/heltec_wireless_paper_v1/platformio.ini b/variants/heltec_wireless_paper_v1/platformio.ini
index 4e5e291e08..8cd8703532 100644
--- a/variants/heltec_wireless_paper_v1/platformio.ini
+++ b/variants/heltec_wireless_paper_v1/platformio.ini
@@ -16,7 +16,8 @@ build_flags =
   ;-D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  https://github.com/meshtastic/GxEPD2/
+  ; https://github.com/meshtastic/GxEPD2/
+  https://github.com/todd-herbert/meshtastic-GxEPD2#async ; Revert to meshtastic/firmware before submitting PR before final merge
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file

From ac89bb33871a37005a50ef2b7410b8102186c1d9 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Fri, 8 Mar 2024 13:16:06 +1300
Subject: [PATCH 03/19] initial config for T-Echo

---
 variants/t-echo/platformio.ini | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/variants/t-echo/platformio.ini b/variants/t-echo/platformio.ini
index 49ba3bb34b..f894b12031 100644
--- a/variants/t-echo/platformio.ini
+++ b/variants/t-echo/platformio.ini
@@ -11,6 +11,12 @@ build_flags = ${nrf52840_base.build_flags} -Ivariants/t-echo
   -DEINK_DISPLAY_MODEL=GxEPD2_154_D67
   -DEINK_WIDTH=200
   -DEINK_HEIGHT=200
+  -D USE_EINK_DYNAMICDISPLAY            ; Enable Dynamic EInk
+  -D EINK_LIMIT_FASTREFRESH=10          ; How many consecutive fast-refreshes are permitted
+  -D EINK_LIMIT_RATE_BACKGROUND_SEC=30  ; Minimum interval between BACKGROUND updates
+  -D EINK_LIMIT_RATE_RESPONSIVE_SEC=1   ; Minimum interval between RESPONSIVE updates
+  -D EINK_LIMIT_GHOSTING_PX=2000        ; (Optional) How much image ghosting is tolerated
+  -D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 build_src_filter = ${nrf52_base.build_src_filter} +<../variants/t-echo>
 lib_deps = 
   ${nrf52840_base.lib_deps}

From 7275c21f6b054e57a9c2c1b8a418cb1aa047bab5 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sat, 9 Mar 2024 09:34:53 +1300
Subject: [PATCH 04/19] formatting responds to
 https://github.com/meshtastic/firmware/pull/3339#discussion_r1518175434

---
 variants/t-echo/platformio.ini | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/variants/t-echo/platformio.ini b/variants/t-echo/platformio.ini
index f894b12031..076f1a747d 100644
--- a/variants/t-echo/platformio.ini
+++ b/variants/t-echo/platformio.ini
@@ -11,12 +11,12 @@ build_flags = ${nrf52840_base.build_flags} -Ivariants/t-echo
   -DEINK_DISPLAY_MODEL=GxEPD2_154_D67
   -DEINK_WIDTH=200
   -DEINK_HEIGHT=200
-  -D USE_EINK_DYNAMICDISPLAY            ; Enable Dynamic EInk
-  -D EINK_LIMIT_FASTREFRESH=10          ; How many consecutive fast-refreshes are permitted
-  -D EINK_LIMIT_RATE_BACKGROUND_SEC=30  ; Minimum interval between BACKGROUND updates
-  -D EINK_LIMIT_RATE_RESPONSIVE_SEC=1   ; Minimum interval between RESPONSIVE updates
-  -D EINK_LIMIT_GHOSTING_PX=2000        ; (Optional) How much image ghosting is tolerated
-  -D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
+  -DUSE_EINK_DYNAMICDISPLAY            ; Enable Dynamic EInk
+  -DEINK_LIMIT_FASTREFRESH=10          ; How many consecutive fast-refreshes are permitted
+  -DEINK_LIMIT_RATE_BACKGROUND_SEC=30  ; Minimum interval between BACKGROUND updates
+  -DEINK_LIMIT_RATE_RESPONSIVE_SEC=1   ; Minimum interval between RESPONSIVE updates
+  -DEINK_LIMIT_GHOSTING_PX=2000        ; (Optional) How much image ghosting is tolerated
+  -DEINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 build_src_filter = ${nrf52_base.build_src_filter} +<../variants/t-echo>
 lib_deps = 
   ${nrf52840_base.lib_deps}

From 23926210d1bcd841b27e15a5119941621be94c72 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sat, 9 Mar 2024 09:57:30 +1300
Subject: [PATCH 05/19] increase fast-refresh limit for T-Echo
 https://github.com/meshtastic/firmware/pull/3339#issuecomment-1986245727

---
 variants/t-echo/platformio.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/variants/t-echo/platformio.ini b/variants/t-echo/platformio.ini
index 076f1a747d..94b6ee0870 100644
--- a/variants/t-echo/platformio.ini
+++ b/variants/t-echo/platformio.ini
@@ -12,7 +12,7 @@ build_flags = ${nrf52840_base.build_flags} -Ivariants/t-echo
   -DEINK_WIDTH=200
   -DEINK_HEIGHT=200
   -DUSE_EINK_DYNAMICDISPLAY            ; Enable Dynamic EInk
-  -DEINK_LIMIT_FASTREFRESH=10          ; How many consecutive fast-refreshes are permitted
+  -DEINK_LIMIT_FASTREFRESH=20          ; How many consecutive fast-refreshes are permitted
   -DEINK_LIMIT_RATE_BACKGROUND_SEC=30  ; Minimum interval between BACKGROUND updates
   -DEINK_LIMIT_RATE_RESPONSIVE_SEC=1   ; Minimum interval between RESPONSIVE updates
   -DEINK_LIMIT_GHOSTING_PX=2000        ; (Optional) How much image ghosting is tolerated

From d5c11d18922301864617ff160468bb39751916e0 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 02:11:49 +1300
Subject: [PATCH 06/19] change dependency from private repo to
 meshtastic/GxEPD2

---
 variants/heltec_wireless_paper/platformio.ini    | 3 +--
 variants/heltec_wireless_paper_v1/platformio.ini | 3 +--
 variants/t-echo/platformio.ini                   | 2 +-
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/variants/heltec_wireless_paper/platformio.ini b/variants/heltec_wireless_paper/platformio.ini
index 7aebef0148..14275830a2 100644
--- a/variants/heltec_wireless_paper/platformio.ini
+++ b/variants/heltec_wireless_paper/platformio.ini
@@ -16,8 +16,7 @@ build_flags =
   -D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  ; https://github.com/meshtastic/GxEPD2/
-  https://github.com/todd-herbert/meshtastic-GxEPD2#async ; Revert to meshtastic/firmware before submitting PR before final merge
+  https://github.com/meshtastic/GxEPD2/
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file
diff --git a/variants/heltec_wireless_paper_v1/platformio.ini b/variants/heltec_wireless_paper_v1/platformio.ini
index 8cd8703532..4e5e291e08 100644
--- a/variants/heltec_wireless_paper_v1/platformio.ini
+++ b/variants/heltec_wireless_paper_v1/platformio.ini
@@ -16,8 +16,7 @@ build_flags =
   ;-D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  ; https://github.com/meshtastic/GxEPD2/
-  https://github.com/todd-herbert/meshtastic-GxEPD2#async ; Revert to meshtastic/firmware before submitting PR before final merge
+  https://github.com/meshtastic/GxEPD2/
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file
diff --git a/variants/t-echo/platformio.ini b/variants/t-echo/platformio.ini
index 94b6ee0870..c97341a3b0 100644
--- a/variants/t-echo/platformio.ini
+++ b/variants/t-echo/platformio.ini
@@ -20,7 +20,7 @@ build_flags = ${nrf52840_base.build_flags} -Ivariants/t-echo
 build_src_filter = ${nrf52_base.build_src_filter} +<../variants/t-echo>
 lib_deps = 
   ${nrf52840_base.lib_deps}
-  https://github.com/meshtastic/GxEPD2#afce87a97dda1ac31d8a28dc8fa7c6f55dc96a61
+  https://github.com/meshtastic/GxEPD2
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 ;upload_protocol = fs

From 576f582cd9a41ac877f11129a834cac9d18e4b81 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 02:30:16 +1300
Subject: [PATCH 07/19] rename setFrameFlag() method

---
 src/graphics/EInkDynamicDisplay.cpp | 12 ++++++------
 src/graphics/EInkDynamicDisplay.h   |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index 75db0e33fe..c9bd5b22bb 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -25,19 +25,19 @@ EInkDynamicDisplay::~EInkDynamicDisplay()
 // Screen requests a BACKGROUND frame
 void EInkDynamicDisplay::display()
 {
-    setFrameFlag(BACKGROUND);
+    addFrameFlag(BACKGROUND);
     update();
 }
 
 // Screen requests a RESPONSIVE frame
 bool EInkDynamicDisplay::forceDisplay(uint32_t msecLimit)
 {
-    setFrameFlag(RESPONSIVE);
+    addFrameFlag(RESPONSIVE);
     return update(); // (Unutilized) Base class promises to return true if update ran
 }
 
 // Add flag for the next frame
-void EInkDynamicDisplay::setFrameFlag(frameFlagTypes flag)
+void EInkDynamicDisplay::addFrameFlag(frameFlagTypes flag)
 {
     // OR the new flag into the existing flags
     this->frameFlags = (frameFlagTypes)(this->frameFlags | flag);
@@ -169,14 +169,14 @@ void EInkDynamicDisplay::checkForPromotion()
 
     switch (previousReason) {
     case ASYNC_REFRESH_BLOCKED_DEMANDFAST:
-        setFrameFlag(DEMAND_FAST);
+        addFrameFlag(DEMAND_FAST);
         break;
     case ASYNC_REFRESH_BLOCKED_COSMETIC:
-        setFrameFlag(COSMETIC);
+        addFrameFlag(COSMETIC);
         break;
     case ASYNC_REFRESH_BLOCKED_RESPONSIVE:
     case EXCEEDED_RATELIMIT_FAST:
-        setFrameFlag(RESPONSIVE);
+        addFrameFlag(RESPONSIVE);
         break;
     default:
         break;
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index 3dc00ba7c8..1eeb28f81e 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -29,7 +29,7 @@ class EInkDynamicDisplay : public EInkDisplay
         COSMETIC = (1 << 2),    // For splashes
         DEMAND_FAST = (1 << 3), // Special case only
     };
-    void setFrameFlag(frameFlagTypes flag);
+    void addFrameFlag(frameFlagTypes flag);
 
     // Set the correct frame flag, then call universal "update()" method
     void display() override;

From efd818fe903dc042aa92ae78ea940466689e67ae Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 03:07:13 +1300
Subject: [PATCH 08/19] move storeAndReset() to end of update()

---
 src/graphics/EInkDynamicDisplay.cpp | 14 +++++++-------
 src/graphics/EInkDynamicDisplay.h   |  7 ++++---
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index c9bd5b22bb..0a4d9691df 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -104,6 +104,7 @@ bool EInkDynamicDisplay::update()
         endOrDetach(); // Either endUpdate() right now (fast refresh), or set the async flag (full refresh)
 #endif
 
+    storeAndReset();        // Store the result of this loop for next time
     return refreshApproved; // (Unutilized) Base class promises to return true if update ran
 }
 
@@ -117,10 +118,8 @@ bool EInkDynamicDisplay::determineMode()
     checkRateLimiting();
 
     // If too soon for a new frame, or display busy, abort early
-    if (refresh == SKIPPED) {
-        storeAndReset();
+    if (refresh == SKIPPED)
         return false; // No refresh
-    }
 
     // -- New frame is due --
 
@@ -152,12 +151,12 @@ bool EInkDynamicDisplay::determineMode()
 #endif
 
     // Return - call a refresh or not?
-    if (refresh == SKIPPED) {
-        storeAndReset();
+    if (refresh == SKIPPED)
         return false; // Don't trigger a refresh
-    } else {
-        storeAndReset();
+    else
         return true; // Do trigger a refresh
+}
+
     }
 }
 
@@ -335,6 +334,7 @@ void EInkDynamicDisplay::hashImage()
 // Store the results of determineMode() for future use, and reset for next call
 void EInkDynamicDisplay::storeAndReset()
 {
+    previousFrameFlags = frameFlags;
     previousRefresh = refresh;
     previousReason = reason;
 
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index 1eeb28f81e..ad4d9bfd92 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -82,13 +82,14 @@ class EInkDynamicDisplay : public EInkDisplay
     void storeAndReset();     // Keep results of determineMode() for later, tidy-up for next call
 
     // What we are determining for this frame
-    frameFlagTypes frameFlags = BACKGROUND; // Frame type(s) - determineMode() input
+    frameFlagTypes frameFlags = BACKGROUND; // Frame characteristics - determineMode() input
     refreshTypes refresh = UNSPECIFIED;     // Refresh type - determineMode() output
     reasonTypes reason = NO_OBJECTIONS;     // Reason - why was refresh type used
 
     // What happened last time determineMode() ran
-    refreshTypes previousRefresh = UNSPECIFIED; // (Previous) Outcome
-    reasonTypes previousReason = NO_OBJECTIONS; // (Previous) Reason
+    frameFlagTypes previousFrameFlags = BACKGROUND; // (Previous) Frame flags
+    refreshTypes previousRefresh = UNSPECIFIED;     // (Previous) Outcome
+    reasonTypes previousReason = NO_OBJECTIONS;     // (Previous) Reason
 
     uint32_t previousRunMs = -1;       // When did determineMode() last run (rather than rejecting for rate-limiting)
     uint32_t imageHash = 0;            // Hash of the current frame. Don't bother updating if nothing has changed!

From 95b6f27d2a9dcd436070b81524fbe583e342aa6a Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 03:38:39 +1300
Subject: [PATCH 09/19] change order of determineMode() checks

---
 src/graphics/EInkDynamicDisplay.cpp | 34 ++++++++++++++---------------
 src/graphics/EInkDynamicDisplay.h   |  2 +-
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index 0a4d9691df..7666820bd5 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -130,11 +130,11 @@ bool EInkDynamicDisplay::determineMode()
     // Once mode determined, any remaining checks will bypass
     checkCosmetic();
     checkDemandingFast();
-    checkConsecutiveFastRefreshes();
 #ifdef EINK_LIMIT_GHOSTING_PX
     checkExcessiveGhosting();
 #endif
     checkFrameMatchesPrevious();
+    checkConsecutiveFastRefreshes();
     checkFastRequested();
 
     if (refresh == UNSPECIFIED)
@@ -244,21 +244,6 @@ void EInkDynamicDisplay::checkDemandingFast()
     }
 }
 
-// Have too many fast-refreshes occured consecutively, since last full refresh?
-void EInkDynamicDisplay::checkConsecutiveFastRefreshes()
-{
-    // If a decision was already reached, don't run the check
-    if (refresh != UNSPECIFIED)
-        return;
-
-    // If too many FAST refreshes consecutively - force a FULL refresh
-    if (fastRefreshCount >= EINK_LIMIT_FASTREFRESH) {
-        refresh = FULL;
-        reason = EXCEEDED_LIMIT_FASTREFRESH;
-        LOG_DEBUG("refresh=FULL, reason=EXCEEDED_LIMIT_FASTREFRESH\n");
-    }
-}
-
 // Does the new frame match the currently displayed image?
 void EInkDynamicDisplay::checkFrameMatchesPrevious()
 {
@@ -283,7 +268,22 @@ void EInkDynamicDisplay::checkFrameMatchesPrevious()
     // Not redrawn, not COSMETIC, not DEMAND_FAST
     refresh = SKIPPED;
     reason = FRAME_MATCHED_PREVIOUS;
-    LOG_DEBUG("refresh=SKIPPED, reason=FRAME_MATCHED_PREVIOUS\n");
+    LOG_DEBUG("refresh=SKIPPED, reason=FRAME_MATCHED_PREVIOUS, frameFlags=0x%x\n", frameFlags);
+}
+
+// Have too many fast-refreshes occured consecutively, since last full refresh?
+void EInkDynamicDisplay::checkConsecutiveFastRefreshes()
+{
+    // If a decision was already reached, don't run the check
+    if (refresh != UNSPECIFIED)
+        return;
+
+    // If too many FAST refreshes consecutively - force a FULL refresh
+    if (fastRefreshCount >= EINK_LIMIT_FASTREFRESH) {
+        refresh = FULL;
+        reason = EXCEEDED_LIMIT_FASTREFRESH;
+        LOG_DEBUG("refresh=FULL, reason=EXCEEDED_LIMIT_FASTREFRESH\n");
+    }
 }
 
 // No objections, we can perform fast-refresh, if desired
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index ad4d9bfd92..b3e091fb27 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -73,8 +73,8 @@ class EInkDynamicDisplay : public EInkDisplay
     void checkRateLimiting();             // Is this frame too soon?
     void checkCosmetic();                 // Was the COSMETIC flag set?
     void checkDemandingFast();            // Was the DEMAND_FAST flag set?
-    void checkConsecutiveFastRefreshes(); // Too many fast-refreshes consecutively?
     void checkFrameMatchesPrevious();     // Does the new frame match the existing display image?
+    void checkConsecutiveFastRefreshes(); // Too many fast-refreshes consecutively?
     void checkFastRequested();            // Was the flag set for RESPONSIVE, or only BACKGROUND?
 
     void resetRateLimiting(); // Set previousRunMs - this now counts as an update, for rate-limiting

From 94794edd43392836ddbd88471f6575bc859ac676 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 03:43:07 +1300
Subject: [PATCH 10/19] add init code as a determineMode() check

---
 src/graphics/EInkDisplay2.cpp       |  1 -
 src/graphics/EInkDynamicDisplay.cpp | 16 ++++++++++++++++
 src/graphics/EInkDynamicDisplay.h   |  2 ++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp
index 6f7885b45b..0c5fab4fb4 100644
--- a/src/graphics/EInkDisplay2.cpp
+++ b/src/graphics/EInkDisplay2.cpp
@@ -184,7 +184,6 @@ bool EInkDisplay::connect()
         // Init GxEPD2
         adafruitDisplay->init();
         adafruitDisplay->setRotation(3);
-        adafruitDisplay->clearScreen(); // Clearing now, so the boot logo will draw nice and smoothe (fast refresh)
     }
 #elif defined(PCA10059)
     {
diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index 7666820bd5..8ff8dc4afb 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -111,6 +111,7 @@ bool EInkDynamicDisplay::update()
 // Assess situation, pick a refresh type
 bool EInkDynamicDisplay::determineMode()
 {
+    checkInitialized();
     checkForPromotion();
 #if defined(HAS_EINK_ASYNCFULL)
     checkAsyncFullRefresh();
@@ -157,6 +158,21 @@ bool EInkDynamicDisplay::determineMode()
         return true; // Do trigger a refresh
 }
 
+// Is this the very first frame?
+void EInkDynamicDisplay::checkInitialized()
+{
+    if (!initialized) {
+        // Undo GxEPD2_BW::partialWindow(), if set by developer in EInkDisplay::connect()
+        configForFullRefresh();
+
+        // Clear any existing image, so we can draw logo with fast-refresh, but also to set GxEPD2_EPD::_initial_write
+        adafruitDisplay->clearScreen();
+
+        LOG_DEBUG("initialized, ");
+        initialized = true;
+
+        // Use a fast-refresh for the next frame; no skipping or else blank screen when waking from deep sleep
+        addFrameFlag(DEMAND_FAST);
     }
 }
 
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index b3e091fb27..48540a132f 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -69,6 +69,7 @@ class EInkDynamicDisplay : public EInkDisplay
     bool update();                // Trigger the display update - determine mode, then call base class
 
     // Checks as part of determineMode()
+    void checkInitialized();              // Is this the very first frame?
     void checkForPromotion();             // Was a frame skipped (rate, display busy) that should have been a FAST refresh?
     void checkRateLimiting();             // Is this frame too soon?
     void checkCosmetic();                 // Was the COSMETIC flag set?
@@ -91,6 +92,7 @@ class EInkDynamicDisplay : public EInkDisplay
     refreshTypes previousRefresh = UNSPECIFIED;     // (Previous) Outcome
     reasonTypes previousReason = NO_OBJECTIONS;     // (Previous) Reason
 
+    bool initialized = false;          // Have we drawn at least one frame yet?
     uint32_t previousRunMs = -1;       // When did determineMode() last run (rather than rejecting for rate-limiting)
     uint32_t imageHash = 0;            // Hash of the current frame. Don't bother updating if nothing has changed!
     uint32_t previousImageHash = 0;    // Hash of the previous update's frame

From e232e3462c58bd67711a1706351f3d5a4adb61d6 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 03:48:59 +1300
Subject: [PATCH 11/19] add BLOCKING modifier to frameFlagTypes

---
 src/graphics/EInkDynamicDisplay.cpp | 21 +++++++++++++++++++--
 src/graphics/EInkDynamicDisplay.h   |  2 ++
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index 8ff8dc4afb..2b36590993 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -458,15 +458,32 @@ void EInkDynamicDisplay::checkAsyncFullRefresh()
 // Figure out who runs the post-update code
 void EInkDynamicDisplay::endOrDetach()
 {
-    if (previousRefresh == FULL) {  // Note: previousRefresh is the refresh from this loop.
+    if (refresh == FULL) {
         asyncRefreshRunning = true; // Set the flag - picked up at start of determineMode(), next loop.
-        LOG_DEBUG("Async full-refresh begins\n");
+
+        if (frameFlags & BLOCKING)
+            awaitRefresh();
+        else
+            LOG_DEBUG("Async full-refresh begins\n");
     }
 
     // Fast Refresh
     else
         EInkDisplay::endUpdate(); // Still block while updating, but EInkDisplay needs us to call endUpdate() ourselves.
 }
+
+// Hold control while an async refresh runs
+void EInkDynamicDisplay::awaitRefresh()
+{
+    // Continually poll the BUSY pin
+    while (adafruitDisplay->epd2.isBusy())
+        yield();
+
+    // End the full-refresh process
+    adafruitDisplay->endAsyncFull(); // Run the end of nextPage() code
+    EInkDisplay::endUpdate();        // Run base-class code to finish off update (NOT our derived class override)
+    asyncRefreshRunning = false;     // Unset the flag
+}
 #endif // HAS_EINK_ASYNCFULL
 
 #endif // USE_EINK_DYNAMICDISPLAY
\ No newline at end of file
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index 48540a132f..ed5be70cde 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -28,6 +28,7 @@ class EInkDynamicDisplay : public EInkDisplay
         RESPONSIVE = (1 << 1),  // For frames via forceDisplay()
         COSMETIC = (1 << 2),    // For splashes
         DEMAND_FAST = (1 << 3), // Special case only
+        BLOCKING = (1 << 4),    // Modifier - block while refresh runs
     };
     void addFrameFlag(frameFlagTypes flag);
 
@@ -112,6 +113,7 @@ class EInkDynamicDisplay : public EInkDisplay
 #if defined(HAS_EINK_ASYNCFULL)
     void checkAsyncFullRefresh(); // Check the status of "async full-refresh"; run the post-update code if the hardware is ready
     void endOrDetach();           // Run the post-update code, or delegate it off to checkAsyncFullRefresh()
+    void awaitRefresh();          // Hold control while an async refresh runs
     void endUpdate() override {}  // Disable base-class behavior of running post-update immediately after forceDisplay()
     bool asyncRefreshRunning = false; // Flag, checked by checkAsyncFullRefresh()
 #endif

From a9c07a4c016f330cf6a50c3dd8ed61ab0e535453 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 04:07:51 +1300
Subject: [PATCH 12/19] add frameFlags to LOG_DEBUG() messages

---
 src/graphics/EInkDynamicDisplay.cpp | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index 2b36590993..d539695407 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -241,7 +241,7 @@ void EInkDynamicDisplay::checkCosmetic()
     if (frameFlags & COSMETIC) {
         refresh = FULL;
         reason = FLAGGED_COSMETIC;
-        LOG_DEBUG("refresh=FULL, reason=FLAGGED_COSMETIC\n");
+        LOG_DEBUG("refresh=FULL, reason=FLAGGED_COSMETIC, frameFlags=0x%x\n", frameFlags);
     }
 }
 
@@ -256,7 +256,7 @@ void EInkDynamicDisplay::checkDemandingFast()
     if (frameFlags & DEMAND_FAST) {
         refresh = FAST;
         reason = FLAGGED_DEMAND_FAST;
-        LOG_DEBUG("refresh=FAST, reason=FLAGGED_DEMAND_FAST\n");
+        LOG_DEBUG("refresh=FAST, reason=FLAGGED_DEMAND_FAST, frameFlags=0x%x\n", frameFlags);
     }
 }
 
@@ -276,7 +276,7 @@ void EInkDynamicDisplay::checkFrameMatchesPrevious()
     if (frameFlags == BACKGROUND && fastRefreshCount > 0) {
         refresh = FULL;
         reason = REDRAW_WITH_FULL;
-        LOG_DEBUG("refresh=FULL, reason=REDRAW_WITH_FULL\n");
+        LOG_DEBUG("refresh=FULL, reason=REDRAW_WITH_FULL, frameFlags=0x%x\n", frameFlags);
         return;
     }
 #endif
@@ -298,7 +298,7 @@ void EInkDynamicDisplay::checkConsecutiveFastRefreshes()
     if (fastRefreshCount >= EINK_LIMIT_FASTREFRESH) {
         refresh = FULL;
         reason = EXCEEDED_LIMIT_FASTREFRESH;
-        LOG_DEBUG("refresh=FULL, reason=EXCEEDED_LIMIT_FASTREFRESH\n");
+        LOG_DEBUG("refresh=FULL, reason=EXCEEDED_LIMIT_FASTREFRESH, frameFlags=0x%x\n", frameFlags);
     }
 }
 
@@ -313,7 +313,8 @@ void EInkDynamicDisplay::checkFastRequested()
         // If we want BACKGROUND to use fast. (FULL only when a limit is hit)
         refresh = FAST;
         reason = BACKGROUND_USES_FAST;
-        LOG_DEBUG("refresh=FAST, reason=BACKGROUND_USES_FAST, fastRefreshCount=%lu\n", fastRefreshCount);
+        LOG_DEBUG("refresh=FAST, reason=BACKGROUND_USES_FAST, fastRefreshCount=%lu, frameFlags=0x%x\n", fastRefreshCount,
+                  frameFlags);
 #else
         // If we do want to use FULL for BACKGROUND updates
         refresh = FULL;
@@ -326,7 +327,7 @@ void EInkDynamicDisplay::checkFastRequested()
     if (frameFlags & RESPONSIVE) {
         refresh = FAST;
         reason = NO_OBJECTIONS;
-        LOG_DEBUG("refresh=FAST, reason=NO_OBJECTIONS, fastRefreshCount=%lu\n", fastRefreshCount);
+        LOG_DEBUG("refresh=FAST, reason=NO_OBJECTIONS, fastRefreshCount=%lu, frameFlags=0x%x\n", fastRefreshCount, frameFlags);
     }
 }
 
@@ -407,7 +408,7 @@ void EInkDynamicDisplay::checkExcessiveGhosting()
     if (ghostPixelCount > EINK_LIMIT_GHOSTING_PX) {
         refresh = FULL;
         reason = EXCEEDED_GHOSTINGLIMIT;
-        LOG_DEBUG("refresh=FULL, reason=EXCEEDED_GHOSTINGLIMIT\n");
+        LOG_DEBUG("refresh=FULL, reason=EXCEEDED_GHOSTINGLIMIT, frameFlags=0x%x\n", frameFlags);
     }
 }
 

From 94eb837ee8c506ef4838d720f343a51914cd0a94 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 04:14:45 +1300
Subject: [PATCH 13/19] function macro for tidier addFramFlag() calls

---
 src/graphics/EInkDynamicDisplay.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index ed5be70cde..495d20e7bd 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -119,4 +119,10 @@ class EInkDynamicDisplay : public EInkDisplay
 #endif
 };
 
+// Tidier calls to addFrameFlag() from outside class
+#define EINK_ADD_FRAMEFLAG(display, flag) static_cast<EInkDynamicDisplay *>(display)->addFrameFlag(EInkDynamicDisplay::flag)
+
+#else // !USE_EINK_DYNAMICDISPLAY
+// Dummy-macro, removes the need for include guards
+#define EINK_ADD_FRAMEFLAG(display, flag)
 #endif
\ No newline at end of file

From 7b703244351eb5bbee8542a638a04e12e965db28 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 05:00:51 +1300
Subject: [PATCH 14/19] handle special frames in Screen.cpp

---
 src/graphics/Screen.cpp | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/graphics/Screen.cpp b/src/graphics/Screen.cpp
index 3ffea4a606..7f20b56661 100644
--- a/src/graphics/Screen.cpp
+++ b/src/graphics/Screen.cpp
@@ -260,6 +260,10 @@ static void drawWelcomeScreen(OLEDDisplay *display, OLEDDisplayUiState *state, i
 /// Used on eink displays while in deep sleep
 static void drawSleepScreen(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y)
 {
+    // Next frame should use full-refresh, and block while running, else device will sleep before async callback
+    EINK_ADD_FRAMEFLAG(display, COSMETIC);
+    EINK_ADD_FRAMEFLAG(display, BLOCKING);
+
     drawIconScreen("Sleeping...", display, state, x, y);
 }
 #endif
@@ -1170,6 +1174,7 @@ int32_t Screen::runOnce()
             break;
         case Cmd::STOP_BLUETOOTH_PIN_SCREEN:
         case Cmd::STOP_BOOT_SCREEN:
+            EINK_ADD_FRAMEFLAG(dispdev, COSMETIC); // E-Ink: Explicitly use full-refresh for next frame
             setFrames();
             break;
         case Cmd::PRINT:
@@ -1350,6 +1355,7 @@ void Screen::handleStartBluetoothPinScreen(uint32_t pin)
 {
     LOG_DEBUG("showing bluetooth screen\n");
     showingNormalScreen = false;
+    EINK_ADD_FRAMEFLAG(dispdev, DEMAND_FAST); // E-Ink: Explicitly use fast-refresh for next frame
 
     static FrameCallback frames[] = {drawFrameBluetooth};
     snprintf(btPIN, sizeof(btPIN), "%06u", pin);
@@ -1367,6 +1373,7 @@ void Screen::handleShutdownScreen()
 {
     LOG_DEBUG("showing shutdown screen\n");
     showingNormalScreen = false;
+    EINK_ADD_FRAMEFLAG(dispdev, DEMAND_FAST); // E-Ink: Explicitly use fast-refresh for next frame
 
     auto frame = [](OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y) -> void {
         drawFrameText(display, state, x, y, "Shutting down...");
@@ -1380,6 +1387,7 @@ void Screen::handleRebootScreen()
 {
     LOG_DEBUG("showing reboot screen\n");
     showingNormalScreen = false;
+    EINK_ADD_FRAMEFLAG(dispdev, DEMAND_FAST); // E-Ink: Explicitly use fast-refresh for next frame
 
     auto frame = [](OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y) -> void {
         drawFrameText(display, state, x, y, "Rebooting...");
@@ -1392,6 +1400,7 @@ void Screen::handleStartFirmwareUpdateScreen()
 {
     LOG_DEBUG("showing firmware screen\n");
     showingNormalScreen = false;
+    EINK_ADD_FRAMEFLAG(dispdev, DEMAND_FAST); // E-Ink: Explicitly use fast-refresh for next frame
 
     static FrameCallback frames[] = {drawFrameFirmware};
     setFrameImmediateDraw(frames);

From 3daae24d29d2962d38fa33f2b4577c09698b04db Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 13:43:57 +1300
Subject: [PATCH 15/19] fix fallback behavior for unmodified GxEPD2 Issues
 exposed by
 https://github.com/meshtastic/firmware/pull/3356#issuecomment-1986950317

---
 src/graphics/EInkDynamicDisplay.cpp | 58 +++++++++++++++++------------
 src/graphics/EInkDynamicDisplay.h   |  2 +-
 2 files changed, 35 insertions(+), 25 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index d539695407..2f3c2fd0e4 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -96,18 +96,45 @@ bool EInkDynamicDisplay::update()
 {
     // Detemine the refresh mode to use, and start the update
     bool refreshApproved = determineMode();
-    if (refreshApproved)
+    if (refreshApproved) {
         EInkDisplay::forceDisplay(0); // Bypass base class' own rate-limiting system
+        storeAndReset();              // Store the result of this loop for next time. Note: call *before* endOrDetach()
+        endOrDetach();                // endUpdate() right now, or set the async refresh flag (if FULL and HAS_EINK_ASYNC)
+    } else
+        storeAndReset(); // No update, no post-update code, just store the results
 
-#if defined(HAS_EINK_ASYNCFULL)
-    if (refreshApproved)
-        endOrDetach(); // Either endUpdate() right now (fast refresh), or set the async flag (full refresh)
-#endif
-
-    storeAndReset();        // Store the result of this loop for next time
     return refreshApproved; // (Unutilized) Base class promises to return true if update ran
 }
 
+// Figure out who runs the post-update code
+void EInkDynamicDisplay::endOrDetach()
+{
+    // If the GxEPD2 version reports that it has the async modifications
+#ifdef HAS_EINK_ASYNCFULL
+    if (previousRefresh == FULL) {
+        asyncRefreshRunning = true; // Set the flag - picked up at start of determineMode(), next loop.
+
+        if (previousFrameFlags & BLOCKING)
+            awaitRefresh();
+        else
+            LOG_DEBUG("Async full-refresh begins\n");
+    }
+
+    // Fast Refresh
+    else if (previousRefresh == FAST)
+        EInkDisplay::endUpdate(); // Still block while updating, but EInkDisplay needs us to call endUpdate() ourselves.
+
+        // Fallback - If using an unmodified version of GxEPD2 for some reason
+#else
+    if (previousRefresh == FULL || previousRefresh == FAST) { // If refresh wasn't skipped (on unspecified..)
+        LOG_WARN(
+            "GxEPD2 version has not been modified to support async refresh; using fallback behavior. Please update lib_deps in "
+            "variant's platformio.ini file\n");
+        EInkDisplay::endUpdate();
+    }
+#endif
+}
+
 // Assess situation, pick a refresh type
 bool EInkDynamicDisplay::determineMode()
 {
@@ -456,23 +483,6 @@ void EInkDynamicDisplay::checkAsyncFullRefresh()
     // It is only equipped to intercept calls to nextPage()
 }
 
-// Figure out who runs the post-update code
-void EInkDynamicDisplay::endOrDetach()
-{
-    if (refresh == FULL) {
-        asyncRefreshRunning = true; // Set the flag - picked up at start of determineMode(), next loop.
-
-        if (frameFlags & BLOCKING)
-            awaitRefresh();
-        else
-            LOG_DEBUG("Async full-refresh begins\n");
-    }
-
-    // Fast Refresh
-    else
-        EInkDisplay::endUpdate(); // Still block while updating, but EInkDisplay needs us to call endUpdate() ourselves.
-}
-
 // Hold control while an async refresh runs
 void EInkDynamicDisplay::awaitRefresh()
 {
diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index 495d20e7bd..dcae056c67 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -68,6 +68,7 @@ class EInkDynamicDisplay : public EInkDisplay
     void applyRefreshMode();      // Run any relevant GxEPD2 code, so next update will use correct refresh type
     void adjustRefreshCounters(); // Update fastRefreshCount
     bool update();                // Trigger the display update - determine mode, then call base class
+    void endOrDetach();           // Run the post-update code, or delegate it off to checkAsyncFullRefresh()
 
     // Checks as part of determineMode()
     void checkInitialized();              // Is this the very first frame?
@@ -112,7 +113,6 @@ class EInkDynamicDisplay : public EInkDisplay
     // Conditional - async full refresh - only with modified meshtastic/GxEPD2
 #if defined(HAS_EINK_ASYNCFULL)
     void checkAsyncFullRefresh(); // Check the status of "async full-refresh"; run the post-update code if the hardware is ready
-    void endOrDetach();           // Run the post-update code, or delegate it off to checkAsyncFullRefresh()
     void awaitRefresh();          // Hold control while an async refresh runs
     void endUpdate() override {}  // Disable base-class behavior of running post-update immediately after forceDisplay()
     bool asyncRefreshRunning = false; // Flag, checked by checkAsyncFullRefresh()

From c0a3b20aa3eec657300b9c83b97dc1b3e8d8d00c Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Sun, 10 Mar 2024 13:45:35 +1300
Subject: [PATCH 16/19] while drafting, build from
 todd-herbert/meshtastic-GxEPD2#async

---
 variants/heltec_wireless_paper/platformio.ini    | 2 +-
 variants/heltec_wireless_paper_v1/platformio.ini | 2 +-
 variants/t-echo/platformio.ini                   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/variants/heltec_wireless_paper/platformio.ini b/variants/heltec_wireless_paper/platformio.ini
index 14275830a2..8ff475d06e 100644
--- a/variants/heltec_wireless_paper/platformio.ini
+++ b/variants/heltec_wireless_paper/platformio.ini
@@ -16,7 +16,7 @@ build_flags =
   -D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  https://github.com/meshtastic/GxEPD2/
+  https://github.com/todd-herbert/meshtastic-GxEPD2#async
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file
diff --git a/variants/heltec_wireless_paper_v1/platformio.ini b/variants/heltec_wireless_paper_v1/platformio.ini
index 4e5e291e08..9327ed256b 100644
--- a/variants/heltec_wireless_paper_v1/platformio.ini
+++ b/variants/heltec_wireless_paper_v1/platformio.ini
@@ -16,7 +16,7 @@ build_flags =
   ;-D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  https://github.com/meshtastic/GxEPD2/
+  https://github.com/todd-herbert/meshtastic-GxEPD2#async
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file
diff --git a/variants/t-echo/platformio.ini b/variants/t-echo/platformio.ini
index c97341a3b0..1a35f2f280 100644
--- a/variants/t-echo/platformio.ini
+++ b/variants/t-echo/platformio.ini
@@ -20,7 +20,7 @@ build_flags = ${nrf52840_base.build_flags} -Ivariants/t-echo
 build_src_filter = ${nrf52_base.build_src_filter} +<../variants/t-echo>
 lib_deps = 
   ${nrf52840_base.lib_deps}
-  https://github.com/meshtastic/GxEPD2
+  https://github.com/todd-herbert/meshtastic-GxEPD2#async
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 ;upload_protocol = fs

From 1032e16ea44d824fdfe49ffc0c4bf5c146bf712c Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Mon, 11 Mar 2024 01:02:03 +1300
Subject: [PATCH 17/19] reorder determineMode() checks

---
 src/graphics/EInkDynamicDisplay.cpp | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/graphics/EInkDynamicDisplay.cpp b/src/graphics/EInkDynamicDisplay.cpp
index 2f3c2fd0e4..732f6d3fb8 100644
--- a/src/graphics/EInkDynamicDisplay.cpp
+++ b/src/graphics/EInkDynamicDisplay.cpp
@@ -99,7 +99,7 @@ bool EInkDynamicDisplay::update()
     if (refreshApproved) {
         EInkDisplay::forceDisplay(0); // Bypass base class' own rate-limiting system
         storeAndReset();              // Store the result of this loop for next time. Note: call *before* endOrDetach()
-        endOrDetach();                // endUpdate() right now, or set the async refresh flag (if FULL and HAS_EINK_ASYNC)
+        endOrDetach();                // endUpdate() right now, or set the async refresh flag (if FULL and HAS_EINK_ASYNCFULL)
     } else
         storeAndReset(); // No update, no post-update code, just store the results
 
@@ -158,11 +158,11 @@ bool EInkDynamicDisplay::determineMode()
     // Once mode determined, any remaining checks will bypass
     checkCosmetic();
     checkDemandingFast();
+    checkFrameMatchesPrevious();
+    checkConsecutiveFastRefreshes();
 #ifdef EINK_LIMIT_GHOSTING_PX
     checkExcessiveGhosting();
 #endif
-    checkFrameMatchesPrevious();
-    checkConsecutiveFastRefreshes();
     checkFastRequested();
 
     if (refresh == UNSPECIFIED)

From 1d31be939ff36dd2ad675a72893d502aa91808e2 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Tue, 12 Mar 2024 03:06:01 +1300
Subject: [PATCH 18/19] Swap Wireless Paper V1.0 dependency to
 meshtastic/GxEPD2

---
 variants/heltec_wireless_paper_v1/platformio.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/variants/heltec_wireless_paper_v1/platformio.ini b/variants/heltec_wireless_paper_v1/platformio.ini
index 9327ed256b..de832d6d7c 100644
--- a/variants/heltec_wireless_paper_v1/platformio.ini
+++ b/variants/heltec_wireless_paper_v1/platformio.ini
@@ -16,7 +16,7 @@ build_flags =
   ;-D EINK_BACKGROUND_USES_FAST          ; (Optional) Use FAST refresh for both BACKGROUND and RESPONSIVE, until a limit is reached.
 lib_deps =
   ${esp32s3_base.lib_deps}
-  https://github.com/todd-herbert/meshtastic-GxEPD2#async
+  https://github.com/meshtastic/GxEPD2#55f618961db45a23eff0233546430f1e5a80f63a
   adafruit/Adafruit BusIO@^1.13.2
   lewisxhe/PCF8563_Library@^1.0.1
 upload_speed = 115200
\ No newline at end of file

From 1f766a04aa036c83094eb34c6048f8ab6774f0f4 Mon Sep 17 00:00:00 2001
From: Todd Herbert <herbert.todd@gmail.com>
Date: Tue, 12 Mar 2024 04:04:28 +1300
Subject: [PATCH 19/19] purge unused enum val

---
 src/graphics/EInkDynamicDisplay.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/graphics/EInkDynamicDisplay.h b/src/graphics/EInkDynamicDisplay.h
index dcae056c67..81963df585 100644
--- a/src/graphics/EInkDynamicDisplay.h
+++ b/src/graphics/EInkDynamicDisplay.h
@@ -49,7 +49,6 @@ class EInkDynamicDisplay : public EInkDisplay
         ASYNC_REFRESH_BLOCKED_COSMETIC,
         ASYNC_REFRESH_BLOCKED_RESPONSIVE,
         ASYNC_REFRESH_BLOCKED_BACKGROUND,
-        DISPLAY_NOT_READY_FOR_FULL,
         EXCEEDED_RATELIMIT_FAST,
         EXCEEDED_RATELIMIT_FULL,
         FLAGGED_COSMETIC,