busdisplay
Displays a displayio object tree on an external device with a built-in
framebuffer
Available on these boards
- busdisplay._DisplayBus
fourwire.FourWire,paralleldisplaybus.ParallelBusori2cdisplaybus.I2CDisplayBus
- class busdisplay.BusDisplay(display_bus: _DisplayBus, init_sequence: circuitpython_typing.ReadableBuffer, *, width: int, height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, color_depth: int = 16, grayscale: bool = False, pixels_in_byte_share_row: bool = True, bytes_per_cell: int = 1, reverse_pixels_in_byte: bool = False, set_column_command: int = 42, set_row_command: int = 43, write_ram_command: int = 44, backlight_pin: microcontroller.Pin | None = None, brightness_command: int | None = None, brightness: float = 1.0, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60, backlight_on_high: bool = True, SH1107_addressing: bool = False)
Manage updating a display over a display bus
This initializes a display and connects it into CircuitPython. Unlike other objects in CircuitPython, display objects live until
displayio.release_displays()is called. This is done so that CircuitPython can use the display itself.Most people should not use this class directly. Use a specific display driver instead that will contain the initialization sequence at minimum.
Create a Display object on the given display bus (
FourWire,paralleldisplaybus.ParallelBusorI2CDisplayBus).The
init_sequenceis bitpacked to minimize the ram impact. Every command begins with a command byte followed by a byte to determine the parameter count and delay. When the top bit of the second byte is 1 (0x80), a delay will occur after the command parameters are sent. The remaining 7 bits are the parameter count excluding any delay byte. The bytes following are the parameters. When the delay bit is set, a single byte after the parameters specifies the delay duration in milliseconds. The value 0xff will lead to an extra long 500 ms delay instead of 255 ms. The next byte will begin a new command definition. Here is an example:init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms) b"\x29\x81\xaa\x78"# Display on then delay 0x78 (120ms) ) display = busdisplay.BusDisplay(display_bus, init_sequence, width=320, height=240)
The first command is 0xe1 with 15 (0xf) parameters following. The second is 0x11 with 0 parameters and a 120ms (0x78) delay. The third command is 0x29 with one parameter 0xaa and a 120ms delay (0x78). Multiple byte literals (b””) are merged together on load. The parens are needed to allow byte literals on subsequent lines.
The initialization sequence should always leave the display memory access inline with the scan of the display to minimize tearing artifacts.
- Parameters:
display_bus – The bus that the display is connected to
init_sequence (ReadableBuffer) – Byte-packed initialization sequence.
width (int) – Width in pixels
height (int) – Height in pixels
colstart (int) – The index if the first visible column
rowstart (int) – The index if the first visible row
rotation (int) – The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270)
color_depth (int) – The number of bits of color per pixel transmitted. (Some displays support 18 bit but 16 is easier to transmit. The last bit is extrapolated.)
grayscale (bool) – True if the display only shows a single color.
pixels_in_byte_share_row (bool) – True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column.
bytes_per_cell (int) – Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row.
reverse_pixels_in_byte (bool) – Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.)
reverse_bytes_in_word (bool) – Reverses the order of bytes within a word when color_depth == 16
set_column_command (int) – Command used to set the start and end columns to update
set_row_command (int) – Command used so set the start and end rows to update
write_ram_command (int) – Command used to write pixels values into the update region. Ignored if data_as_commands is set.
backlight_pin (microcontroller.Pin) – Pin connected to the display’s backlight
brightness_command (int) – Command to set display brightness. Usually available in OLED controllers.
brightness (float) – Initial display brightness.
single_byte_bounds (bool) – Display column and row commands use single bytes
data_as_commands (bool) – Treat all init and boundary data as SPI commands. Certain displays require this.
auto_refresh (bool) – Automatically refresh the screen
native_frames_per_second (int) – Number of display refreshes per second that occur with the given init_sequence.
backlight_on_high (bool) – If True, pulling the backlight pin high turns the backlight on.
SH1107_addressing (bool) – Special quirk for SH1107, use upper/lower column set and page set
set_vertical_scroll (int) – This parameter is accepted but ignored for backwards compatibility. It will be removed in a future release.
backlight_pwm_frequency (int) – The frequency to use to drive the PWM for backlight brightness control. Default is 50000.
- refresh(*, target_frames_per_second: int | None = None, minimum_frames_per_second: int = 0) bool
When auto_refresh is off, and
target_frames_per_secondis notNonethis waits for the target frame rate and then refreshes the display, returningTrue. If the call has taken too long since the last refresh call for the given target frame rate, then the refresh returnsFalseimmediately without updating the screen to hopefully help getting caught up.If the time since the last successful refresh is below the minimum frame rate, then an exception will be raised. The default
minimum_frames_per_secondof 0 disables this behavior.When auto_refresh is off, and
target_frames_per_secondisNonethis will update the display immediately.When auto_refresh is on, updates the display immediately. (The display will also update without calls to this.)
- bus: _DisplayBus
The bus being used by the display
- root_group: displayio.Group
The root group on the display. If the root group is set to
displayio.CIRCUITPYTHON_TERMINAL, the default CircuitPython terminal will be shown. If the root group is set toNone, no output will be shown.
- fill_row(y: int, buffer: circuitpython_typing.WriteableBuffer) circuitpython_typing.WriteableBuffer
Extract the pixels from a single row
- Parameters:
y (int) – The top edge of the area
buffer (WriteableBuffer) – The buffer in which to place the pixel data