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, grayscale=False, pixels_in_byte_share_row=True, bytes_per_cell=1, reverse_pixels_in_byte=False, set_column_command=0x2a, set_row_command=0x2b, write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness_command=None, brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False, auto_refresh=True, native_frames_per_second=60)

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.

  • 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.)
  • 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.
  • 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_command (int) – Command to set display brightness. Usually available in OLED controllers.
  • 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.
  • 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.

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(*, target_frames_per_second=60, minimum_frames_per_second=1)

When auto refresh is off, waits for the target frame rate and then refreshes the display, returning True. If the call has taken too long since the last refresh call for the given target frame rate, then the refresh returns False immediately 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. Set minimum_frames_per_second to 0 to disable.

When auto refresh is on, updates the display immediately. (The display will also update without calls to this.)

  • target_frames_per_second (int) – How many times a second refresh should be called and the screen updated.
  • minimum_frames_per_second (int) – The minimum number of times the screen should be updated per second.

True when the display is refreshed automatically.


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.


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.


The rotation of the display as an int in degrees.

fill_row(y, buffer)

Extract the pixels from a single row

  • y (int) – The top edge of the area
  • buffer (bytearray) – The buffer in which to place the pixel data