Display – 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.

class displayio.Display(display_bus, init_sequence, *, width, height, colstart=0, rowstart=0, rotation=0, color_depth=16, set_column_command=0x2a, set_row_command=0x2b, write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False)

Create a Display object on the given display bus (displayio.FourWire or displayio.ParallelBus).

The init_sequence is bitpacked to minimize the ram impact. Every command begins with a command byte followed by a byte to determine the parameter count and if a delay is need after. When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds. The remaining 7 bits are the parameter count excluding any delay byte. The third through final bytes are the remaining command parameters. The next byte will begin a new command definition. Here is a portion of ILI9341 init code:

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\x80\x78"# Display on then delay 0x78 (120ms)
                )
 display = displayio.Display(display_bus, init_sequence, width=320, height=240)

The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. 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 (displayio.FourWire or displayio.ParallelBus) – The bus that the display is connected to
  • init_sequence (buffer) – 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.)
  • 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
  • set_vertical_scroll (int) – Command used to set the first row to show
  • backlight_pin (microcontroller.Pin) – Pin connected to the display’s backlight
  • brightness (bool) – Initial display brightness. This value is ignored if auto_brightness is True.
  • auto_brightness (bool) – If True, brightness is controlled via an ambient light sensor or other mechanism.
  • 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.
show(group)

Switches to displaying the given group of layers. When group is None, the default CircuitPython terminal will be shown.

Parameters:group (Group) – The group to show.
refresh_soon()

Queues up a display refresh that happens in the background.

wait_for_frame()

Waits until the next frame has been transmitted to the display unless the wait count is behind the rendered frames. In that case, this will return immediately with the wait count.

brightness

The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When auto_brightness is True, the value of brightness will change automatically. If brightness is set, auto_brightness will be disabled and will be set to False.

auto_brightness

True when the display brightness is adjusted automatically, based on an ambient light sensor or other method. Note that some displays may have this set to True by default, but not actually implement automatic brightness adjustment. auto_brightness is set to False if brightness is set manually.

width
height
bus