Reimplement "Dynamic E-Ink" as a derived class

[todd-herbert]

Aim

Enable developers to configure E-Ink displays' refresh behavior, to balance performance and display health.

How is it implemented

New EInkDynamicDisplay class derives from the existing EInkDisplay class. It hooks the existing display() and forceDisplay() calls. If the macro USE_EINK_DYNAMICDISPLAY is defined, EInkDynamicDisplay is instantiated in Screen.cpp, instead of the EInkDisplay class

Configuration

The behavior of the E-Ink display is configured by several macros which are added to a variant's platformio.ini file as build_flags.

• USE_EINK_DYNAMICDISPLAY

  Defining this macro enables the "Dynamic E-Ink" behavior. If this macro is not defined, the existing EInkDisplay class behavior is used.

• EINK_LIMIT_FASTREFRESH

  This macro specifies how many consecutive fast-refreshes are permitted, before a full-refresh is enforced.

• EINK_LIMIT_RATE_BACKGROUND_SEC

  This macro specifies the minimum interval, in seconds, between "BACKGROUND" updates. Currently, frames drawn by calling display() are flagged as BACKGROUND.

• EINK_LIMIT_RATE_RESPONSIVE_SEC

  This macro specifies the minimum interval, in seconds, between "RESPONSIVE" updates. Currently, frames drawn by calling forceDisplay() are flagged as RESPONSIVE. (Unless specified otherwise with setFrameFlag())

• (Optional) EINK_LIMIT_GHOSTING_PX

  This macro specifies, in pixel count, the amount of "image ghosting" to be tolerated, before a full-refresh is enforced.
  This option has a modest additional overhead. If this macro is omitted, the "ghost pixel" tracking code will not run, and no additional resources will be used.

• (Optional) EINK_BACKGROUND_USES_FAST

  By default, BACKGROUND updates are drawn with a full-refresh. If this macro is defined, the display will use fast-refresh for even these BACKGROUND updates, until another limit eventually forces a full-refresh (EINK_LIMIT_FASTREFRESH, EINK_LIMIT_GHOSTING_PX)

Implementing for additional displays

The display should first be configured to use the existing EInkDisplay class. So long as GxEPD2 supports "fast partial refresh" for the model, it should then be as simple as defining the macros in the variant's platformio.ini or variant.h file.

Performance

Most calls, the code has negligible impact (measured<20µs). When a new frame is eventually due, the impact of all checks running (including ghost pixel tracking) is <15ms. As the physical operation of updating an E-Ink display can take several seconds, a net gain in performance is expected.

In two different scenarios, performance was compared between the existing EInkDisplay class, and the new EInkDynamicDisplay class.

• Scenario 1: Display remains on default screen after boot
• Scenario 2: "Carousel" is set for 20 seconds

Test device was Heltec Wireless Paper V1.1
No other nodes present

#define USE_EINK_DYNAMICDISPLAY
#define EINK_LIMIT_FASTREFRESH 10
#define EINK_LIMIT_RATE_BACKGROUND_SEC 30
#define EINK_LIMIT_RATE_RESPONSIVE_SEC 1
#define EINK_LIMIT_GHOSTING_PX 1000
#define EINK_BACKGROUND_USES_FAST

Default Screen	Carousel

What next

• Real-world Testing

  The values set in this PR for Heltec Wireless Paper V1.0 are only a suggested start point. They haven't been tested in the real world. Please do adjust the configuration for this display, and any future displays, if you feel that the settings could be improved

• Heltec Wireless Paper V1.1

  A rewrite of the GxEPD2 code for LCMEN2R13EFC1 is ready to push, which will enable fast refresh, and dynamic E-Ink config. There is also a minor tweak to the V1.0 GxEPD2 code.

• Mark specific frames as COSMETIC or DEMAND_FAST in Screen.cpp

  This should be along shortly. A few non-invasive lines of code will ensure that some key splash screens are explicitly marked for either full-refresh or fast-refresh.

• Expose Dynamic-EInk settings to end user?

  Unsure if this would be desirable, or exactly what it would involve, but I see no reason theoretically that the macros configuring the E-Ink behavior couldn't be exposed as runtime settings to the user.

Simplified flow diagram

For future reference, code maintenance.

[github-actions]

🤖 Pull request artifacts

empty string

file	commit
firmware-2.2.25.517ed49.zip	517ed49