Skip to content

Fix e-paper release hang that blocked deep sleep after a refresh - #11939

Open
dhalbert wants to merge 1 commit into
adafruit:mainfrom
dhalbert:epaper-deep-sleep-wait
Open

dhalbert wants to merge 1 commit into
adafruit:mainfrom
dhalbert:epaper-deep-sleep-wait

Conversation

@dhalbert

@dhalbert dhalbert commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Diagnosis, fix, and testing by Claude, with review by @dhalbert.

@gglockner @bablokb How does this fix seem to you?

Problem

release_epaperdisplay() waits for BUSY if a refresh is in progress. The display was still marked as refreshing during that wait, so the background task could see the refresh end and send the stop sequence. The SSD1680 (MagTag 2025 and other recent MagTags) keeps BUSY set while asleep, so the wait never ended.

alarm.exit_and_deep_sleep_until_alarms() releases the displays before sleeping, so a refresh still running when code.py finished could hang the board instead of sleeping. The hang was intermittent, because the panel had to finish between the wait loop's read of BUSY and the background task's read.

(The IL0373 on older MagTags drives BUSY to its not-busy level while asleep, so it can't hang this way.)

Fix

Mark the refresh done and stop the supervisor tick before waiting. The background task then leaves the display alone, and the release finishes the refresh and sends the stop sequence itself.

Testing

  • MagTag with SSD1680, firmware with an added 1 ms delay inside the BUSY wait to widen the race: main hung at the first deep sleep on every boot; with this fix, no hangs.
  • MagTag with SSD1680, this fix, 100 true deep sleep cycles of refresh then exit_and_deep_sleep_until_alarms(): no hangs.
  • MagTag with IL0373, this fix, 100 fake deep sleep cycles: no hangs.

With this fix, adafruit/Adafruit_CircuitPython_MagTag#96 is no longer needed to avoid the hang.

release_epaperdisplay() waited for BUSY while the refresh was still
marked in progress. The background task could then see the refresh end
during the wait and send the stop sequence. The SSD1680 keeps BUSY set
while asleep, so the wait never ended, and alarm deep sleep hung after
code.py finished.

Mark the refresh done and stop the tick before waiting, so release
finishes the refresh and sends the stop sequence itself. Do this in both
the legacy and LVGL release_epaperdisplay().

Also reword the comments by each stop sequence send to say that some
panels set busy when sleeping, and that the skipped wait is the one
after the stop sequence.

Fixes adafruit#10639.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dhalbert
dhalbert force-pushed the epaper-deep-sleep-wait branch from 29aa081 to 4962dab Compare November 21, 2026 03:00
@bablokb

bablokb commented Nov 21, 2026

Copy link
Copy Markdown

Does this solve the problem that refresh() is async, i.e. it returns before the refresh actually finishes? I think this is the real problem. True, many displays will refresh and then try to enter deep sleep and this fix may handle this case. But there are other displays that don't (only) enter deep sleep.

Two examples: many Pimoroni boards can shut themselves down, so they don't use deep sleep, they just turn power off. And I have an e-ink from Seeed that has circuitry to power down the panel, which I call before deep-sleep, but after refresh() finished.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Code randomly does not invoke Magtag.exit_and_deep_sleep()

2 participants