[mikeysklar]

What

E-paper displays can update in about 50 ms and drive every pixel equally both ways.

Why

Unbalanced fast updates can damage a panel.

Part 2 of 3, stacked on #11738.

display = epaperdisplay.EPaperDisplay(
    bus, START, STOP, clean_sequence=CLEAN,
    refresh_display_command=REFRESH, seconds_per_frame=0,
    write_previous_ram_command=0x26, fast=True,
    ...)
while True:
    if not display.busy:
        display.refresh()

Addition	Behavior
write_previous_ram_command	Writes previous RAM after each refresh (#6872)
fast	Starts once, stops on release, drives with lag
lag_frames	4 by default, 1 to 32, only with fast
clean_sequence, clean()	Full refresh at start and code end, wipe on demand
update_refresh_mode(refresh_sequence=)	Changes the refresh command

All off by default. fast is on for espressif and raspberrypi; other ports raise NotImplementedError.

Tested on Feather RP2040 ThinkInk, 4.2" SSD1683	Result
Update time	52.9 ms, stock 6.1 s
8 ways code can end, 3 each	24/24 clean, back to REPL
Flash	+8.5 KB

The docs warn that this exceeds panel makers' refresh limits, and long-term wear is unknown.

Question: should the previous RAM write move from refresh() into the background task?

AI assistance

Written with Claude Code.

🤖 Generated with Claude Code

[tannewt]

This PR description is way too long. Please simplify it.

[tannewt]

Please explain these changes concisely.

[mikeysklar]

Trimmed the description.

What this PR does:

• Adds fast partial updates to EPaperDisplay
• Updates take about 50 ms, not 6 s
• Lag drive keeps every pixel balanced
• Panel cleans itself when code ends
• clean() wipes ghosting on demand

[tannewt]

The lag stuff is a lot of complexity and I don't really understand why/how they work to keep things balanced. I'd like to understand it more before we commit it.

[mikeysklar]

Did some review to make sure I have this right. Updating code comments as well so the explanation is easy to find.

Fast updates compare the new frame with the last one, so each change gets one weak push.

Lag frames compare with the frame lag_frames updates back, so each change gets several pushes. The multiple pushes give e-ink crisp images without ghosting.

Each frame is used twice:

1. Pixels are pushed toward it when it is new.
2. Then away from it lag_frames updates later.

So the pushes always cancel.

That is the balance: every pixel gets as many pushes toward black as toward white.

Example with lag_frames=3: a pixel is black for 2 updates, then white.

Update	1	2	3	4	5	6	7
New frame	⬜	⬛	⬛	⬜	⬜	⬜	⬜
Old, 3 updates back	⬜	⬜	⬜	⬜	⬛	⬛	⬜
Push	none	to black	to black	none	to white	to white	none

2 pushes to black, 2 to white: balanced.

[tannewt]

That is the balance: every pixel gets as many pushes toward black as toward white.

Example with lag_frames=3: a pixel is black for 2 updates, then white.
Update 1 2 3 4 5 6 7
New frame ⬜ ⬛ ⬛ ⬜ ⬜ ⬜ ⬜
Old, 3 updates back ⬜ ⬜ ⬜ ⬜ ⬛ ⬛ ⬜
Push none to black to black none to white to white none

2 pushes to black, 2 to white: balanced.

Wouldn't frame 4 incorrectly show black? Maybe that's ok for a fast change.

It seems like we always want lag frames when doing fast updates. Maybe we tie it's use to the FAST and partial ability? Then we omit both from SAMD and nRF52.

[tannewt]

What would inform the number of lag frames? That seems like an implementation detail that we could decide. I feel like we could simplify the API surface of this by simply having a "fast" mode that could be set. However, I don't know how dependent on the driver IC that is.

[mikeysklar]

Wouldn't frame 4 incorrectly show black?

Yep! Briefly. Frame 4 still shows black and clears at 5.

On moving content that looks like a short trail. That's tradeoff for drive balanced.

Maybe we tie it's use to the FAST and partial ability? Then we omit both from SAMD and nRF52.

Agreed. This is a good plan. I'll fold LAG into FAST and turn FAST off for SAMD and nRF52.

What would inform the number of lag frames?

The two factors that would influence lag frame are :

1. What looks good
2. How much memory - 6 frames @ 400x300 is 90 KB.

The vendors don't specific guidance for these fast partial updates.

We can use lag=4 to save memory and it looks acceptable.

How about fast=True with a built in default lag of 4. Plus an optional override so users can tune easily tune it.

[mikeysklar]

Simplified as you suggested.

fast=True now turns on fast updates and lag drive together.

lag_frames defaults to 4, so most code never sets it.

It trades darker motion against smear and memory, so I kept it as an optional setting.

keep_awake is gone, since fast covers it.

[tannewt]

Getting there! I like having LAG + FAST combined. Folks at supercon really wanted this for the badge epaper.

[tannewt]

(FYI there are still unresolved/unresponded to comments.)

[mikeysklar]

Sorry about that. I totally missed those.