Skip to content

Add deinit() to displays; deprecate displayio.release_displays() - #11914

Merged
tannewt merged 5 commits into
adafruit:mainfrom
dhalbert:display-deinit
Nov 19, 2026
Merged

tannewt merged 5 commits into
adafruit:mainfrom
dhalbert:display-deinit

Conversation

@dhalbert

@dhalbert dhalbert commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Code by Claude, reviewed by @dhalbert.

This is the first stage of #8675. Displays get deinit(), and displayio.release_displays() is deprecated in the docs only. It still works, with no runtime warning.

We can add a FutureWarning once 11.x has largely replaced 10.x.

Moving I2C and SPI objects and removing release_displays() are left for later.

Problem

The only way to release a display was displayio.release_displays(), which releases every display and display bus at once. None of the display classes had deinit().

Fix

  • These display classes now have deinit():
    • busdisplay.BusDisplay
    • epaperdisplay.EPaperDisplay
    • framebufferio.FramebufferDisplay
    • zephyr_display.Display (zephyr-cp)
  • deinit() releases the display and its display bus (such as fourwire.FourWire or i2cdisplaybus.I2CDisplayBus), so their pins can be used again. The display bus is not released if another display still uses it.
  • Otherwise, deinit() does what release_displays() does, but for just the one display:
    • A busio.SPI or busio.I2C object passed to the display bus is not deinitialized, so a bus shared with other devices keeps working. It is deinitialized only when the display bus took it over from an earlier run.
    • If the display is the primary display, supervisor.runtime.display becomes None and the terminal stops.
    • On an EPaperDisplay, it waits for a refresh in progress.
    • A direct instance of a display class becomes None-typed, so calling a method on it raises AttributeError.
  • supervisor.runtime.display.deinit() can and should replace release_displays() at the top of code.py. Since Release extra displays when code finishes #11702, the primary display is the only one that can outlive a run.
  • After deinit() or release_displays(), a method called on an instance of a display subclass (such as adafruit_st7789.ST7789) now raises "Object has been deinitialized". Before, it incorrectly used the released display's memory.
  • However, if a new display later reuses the released display's slot, the old object refers to the new display, and calls on it don't raise an error. For a subclass instance, this happens only when the new display is the same class. This was already true before.
  • release_displays() is marked deprecated in its docstring. Other docstrings, the qspibus and usb_video examples, and docs/environment.rst now refer to deinit().
  • The error "Too many display busses; forgot displayio.release_displays() ?" is now "Too many display buses; deinit() unused displays".
  • The display bus classes don't get a deinit() method in this PR.

Testing

deinit() and supervisor.runtime.display.deinit() were tested on:

  • PyPortal: BusDisplay, FourWire
  • Feather ESP32-S3 Reverse TFT: built-in BusDisplay
  • MagTag: EPaperDisplay, during a refresh
  • Fruit Jam: FramebufferDisplay, picodvi
  • ESP32-P4 Function EV Board (LVGL build): FramebufferDisplay, mipidsi, with a user-created display
  • CLUE (zephyr-cp): zephyr_display.Display

release_displays() was checked to still work as before.

dhalbert and others added 5 commits November 18, 2026 20:43
BusDisplay, EPaperDisplay, FramebufferDisplay and zephyr_display.Display
get a deinit() method. It releases the display and, unless another
display uses it, the display's bus, freeing their pins. If the display
is supervisor.runtime.display, the primary display is cleared and the
terminal stops.

supervisor.runtime.display.deinit() does what release_displays() is
used for: release a built-in display, or one kept from an earlier run.

Methods called on a released display subclass instance now raise
"Object has been deinitialized" instead of using the released slot.

Refs adafruit#8675

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mark displayio.release_displays() deprecated in its docstring, and point
other docstrings, examples and docs/environment.rst to deinit() on the
display instead. It still works, with no runtime warning.

Refs adafruit#8675

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"Too many display busses; forgot displayio.release_displays() ?" is
now "Too many display buses; deinit() unused displays".

Regenerating circuitpython.pot also drops two stale source locations
for "%q must be <= %d".

Refs adafruit#8675

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The display deinit() changes add about 240 bytes of flash, which made
some translated builds of these boards overflow.

- itsybitsy_m0_express, qtpy_m0_haxpress, snekboard: turn off codeop,
  errno and rainbowio, as on Feather M0 Express and Metro M0 Express.
  pulseio stays off on itsybitsy_m0_express, which doesn't fit with it
  on.
- bluemicro840, bless_dev_board_multi_sensor: turn off codeop and
  rainbowio.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@mikeysklar mikeysklar left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good.

Non-blocking question:

should a second deinit() be a no-op? On a direct instance it raises AttributeError, on a subclass it does nothing.

Tested on a Metro RP2350 with FourWire + BusDisplay on D9/D10, no panel attached.

CI builds: main at 101416a vs this PR at 78249b6.

Case main PR
d.deinit() AttributeError ok
D9 free after deinit in use free
User busio.SPI still usable ok ok
Bound method called after deinit ran on released display deinitialized error
Second d.deinit(), direct instance n/a AttributeError
Second deinit(), subclass n/a no-op
Subclass method after deinit returned 64 deinitialized error
runtime.display.deinit(), then runtime.display still <BusDisplay> None, D9 free
release_displays(), then old object AttributeError AttributeError
Too many buses error old text new text

@dhalbert

dhalbert commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator Author

@mikeysklar Thanks for the testing and review!

Right now a display in the internal static display table is set to have the None type after deinit(), which causes the AttributeError. We could have a placeholder type, but it's more code, and on boards with almost-full flash, we'd probably have to shrink the boards again.

In a later stage of addressing #8675, we would probably start allocating displays separately, which would remove some code (and add some), and could have a deinited flag. Right now adding that flag would add a lot of extra code.

@mikeysklar

Copy link
Copy Markdown
Collaborator

That is fair. I don't want to deal with flash shortages due to code bloat on this either.

Good to merge.

@dhalbert

Copy link
Copy Markdown
Collaborator Author

@tannewt since this is an API change and also deep in displayio, I'll wait for your review too.

@tannewt tannewt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good to me! I'm surprised they didn't have deinit() already!

@tannewt
tannewt merged commit 02e39f5 into adafruit:main Nov 19, 2026
17 checks passed
@dhalbert
dhalbert deleted the display-deinit branch November 19, 2026 18:25
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.

3 participants