displayio

Native helpers for driving displays

The displayio module contains classes to manage display output including synchronizing with refresh rates and partial updating.

displayio.release_displays() → None

Releases any actively used displays so their busses and pins can be used again. This will also release the builtin display on boards that have one. You will need to reinitialize it yourself afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing.

Use this once in your code.py if you initialize a display. Place it right before the initialization so the display is active as long as possible.

class displayio.Bitmap(width: int, height: int, value_count: int)

Stores values of a certain size in a 2D array

width :int

Width of the bitmap. (read only)

height :int

Height of the bitmap. (read only)

__getitem__(self, index: Union[Tuple[int, int], int])

Returns the value at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

print(bitmap[0,1])
__setitem__(self, index: Union[Tuple[int, int], int], value: int)

Sets the value at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

bitmap[0,1] = 3
fill(self, value: int)

Fills the bitmap with the supplied palette index value.

class displayio.ColorConverter(*, dither: bool = False)

Converts one color format to another.

dither :bool

When true the color converter dithers the output by adding random noise when truncating to display bitdepth

convert(self, color: int)

Converts the given RGB888 color to RGB565

displayio._DisplayBus

FourWire, ParallelBus or I2CDisplay

class displayio.Display(display_bus: _DisplayBus, init_sequence: 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, set_vertical_scroll: int = 0, backlight_pin: Optional[microcontroller.Pin] = None, brightness_command: Optional[int] = None, brightness: float = 1.0, auto_brightness: bool = False, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60)

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.

auto_refresh :bool

True when the display is refreshed automatically.

brightness :float

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 :bool

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 :int
height :int
rotation :int

The rotation of the display as an int in degrees.

bus :_DisplayBus
show(self, group: 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(self, *, target_frames_per_second: int = 60, minimum_frames_per_second: int = 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.)

Parameters:
  • 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.
fill_row(self, y: int, buffer: WriteableBuffer)

Extract the pixels from a single row

Parameters:
  • y (int) – The top edge of the area
  • buffer (bytearray) – The buffer in which to place the pixel data
class displayio.EPaperDisplay(display_bus: _DisplayBus, start_sequence: ReadableBuffer, stop_sequence: ReadableBuffer, *, width: int, height: int, ram_width: int, ram_height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, set_column_window_command: Optional[int] = None, set_row_window_command: Optional[int] = None, single_byte_bounds: bool = False, write_black_ram_command: int, black_bits_inverted: bool = False, write_color_ram_command: Optional[int] = None, color_bits_inverted: bool = False, highlight_color: int = 0, refresh_display_command: int, refresh_time: float = 40, busy_pin: Optional[microcontroller.Pin] = None, busy_state: bool = True, seconds_per_frame: float = 180, always_toggle_chip_select: bool = False)

Manage updating an epaper display over a display bus

This initializes an epaper display and connects it into CircuitPython. Unlike other objects in CircuitPython, EPaperDisplay 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 startup and shutdown sequences at minimum.

time_to_refresh :float

Time, in fractional seconds, until the ePaper display can be refreshed.

width :int

Gets the width of the display in pixels

height :int
bus :_DisplayBus
show(self, group: 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(self)

Refreshes the display immediately or raises an exception if too soon. Use time.sleep(display.time_to_refresh) to sleep until a refresh can occur.

class displayio.FourWire(spi_bus: busio.SPI, *, command: microcontroller.Pin, chip_select: microcontroller.Pin, reset: Optional[microcontroller.Pin] = None, baudrate: int = 24000000, polarity: int = 0, phase: int = 0)

Manage updating a display over SPI four wire protocol in the background while Python code runs. It doesn’t handle display initialization.

reset(self)

Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin is available.

send(self, command: int, data: FourWire, *, toggle_every_byte: bool = False)

Sends the given command value followed by the full set of data. Display state, such as vertical scroll, set via send may or may not be reset once the code is done.

class displayio.Group(*, max_size: int = 4, scale: int = 1, x: int = 0, y: int = 0)

Manage a group of sprites and groups and how they are inter-related.

hidden :bool

True when the Group and all of it’s layers are not visible. When False, the Group’s layers are visible if they haven’t been hidden.

scale :int

Scales each pixel within the Group in both directions. For example, when scale=2 each pixel will be represented by 2x2 pixels.

x :int

X position of the Group in the parent.

y :int

Y position of the Group in the parent.

append(self, layer: Union[vectorio.Shape, Group, TileGrid])

Append a layer to the group. It will be drawn above other layers.

insert(self, index: int, layer: Union[vectorio.Shape, Group, TileGrid])

Insert a layer into the group.

index(self, layer: Union[vectorio.Shape, Group, TileGrid])

Returns the index of the first copy of layer. Raises ValueError if not found.

pop(self, i: int = -1)

Remove the ith item and return it.

remove(self, layer: Union[vectorio.Shape, Group, TileGrid])

Remove the first copy of layer. Raises ValueError if it is not present.

__bool__(self)
__len__(self)

Returns the number of layers in a Group

__getitem__(self, index: int)

Returns the value at the given index.

This allows you to:

print(group[0])
__setitem__(self, index: int, value: Union[vectorio.Shape, Group, TileGrid])

Sets the value at the given index.

This allows you to:

group[0] = sprite
__delitem__(self, index: int)

Deletes the value at the given index.

This allows you to:

del group[0]
class displayio.I2CDisplay(i2c_bus: busio.I2C, *, device_address: int, reset: Optional[microcontroller.Pin] = None)

Manage updating a display over I2C in the background while Python code runs. It doesn’t handle display initialization.

reset(self)

Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin is available.

send(self, command: int, data: ReadableBuffer)

Sends the given command value followed by the full set of data. Display state, such as vertical scroll, set via send may or may not be reset once the code is done.

class displayio.OnDiskBitmap(file: typing.BinaryIO)

Loads values straight from disk. This minimizes memory use but can lead to much slower pixel load times. These load times may result in frame tearing where only part of the image is visible.

It’s easiest to use on a board with a built in display such as the Hallowing M0 Express.

import board
import displayio
import time
import pulseio

board.DISPLAY.auto_brightness = False
board.DISPLAY.brightness = 0
splash = displayio.Group()
board.DISPLAY.show(splash)

with open("/sample.bmp", "rb") as f:
    odb = displayio.OnDiskBitmap(f)
    face = displayio.TileGrid(odb, pixel_shader=displayio.ColorConverter())
    splash.append(face)
    # Wait for the image to load.
    board.DISPLAY.refresh(target_frames_per_second=60)

    # Fade up the backlight
    for i in range(100):
        board.DISPLAY.brightness = 0.01 * i
        time.sleep(0.05)

    # Wait forever
    while True:
        pass
width :int

Width of the bitmap. (read only)

height :int

Height of the bitmap. (read only)

class displayio.Palette(color_count: int)

Map a pixel palette_index to a full color. Colors are transformed to the display’s format internally to save memory.

__bool__(self)
__len__(self)

Returns the number of colors in a Palette

__getitem__(self, index: int)

Return the pixel color at the given index as an integer.

__setitem__(self, index: int, value: Union[int, ReadableBuffer, Tuple[int, int, int]])

Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.

The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value). Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray, or a tuple or list of 3 integers.

This allows you to:

palette[0] = 0xFFFFFF                     # set using an integer
palette[1] = b'\xff\xff\x00'              # set using 3 bytes
palette[2] = b'\xff\xff\x00\x00'          # set using 4 bytes
palette[3] = bytearray(b'\x00\x00\xFF')   # set using a bytearay of 3 or 4 bytes
palette[4] = (10, 20, 30)                 # set using a tuple of 3 integers
make_transparent(self, palette_index: int)
make_opaque(self, palette_index: int)
class displayio.ParallelBus(*, data0: microcontroller.Pin, command: microcontroller.Pin, chip_select: microcontroller.Pin, write: microcontroller.Pin, read: microcontroller.Pin, reset: microcontroller.Pin)

Manage updating a display over 8-bit parallel bus in the background while Python code runs. This protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn’t handle display initialization.

reset(self)

Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin is available.

send(self, command: int, data: ReadableBuffer)

Sends the given command value followed by the full set of data. Display state, such as vertical scroll, set via send may or may not be reset once the code is done.

class displayio.Shape(width: int, height: int, *, mirror_x: bool = False, mirror_y: bool = False)

Represents a shape made by defining boundaries that may be mirrored.

set_boundary(self, y: int, start_x: int, end_x: int)

Loads pre-packed data into the given row.

class displayio.TileGrid(bitmap: Bitmap, *, pixel_shader: Union[ColorConverter, Palette], width: int = 1, height: int = 1, tile_width: Optional[int] = None, tile_height: Optional[int] = None, default_tile: int = 0, x: int = 0, y: int = 0)

A grid of tiles sourced out of one bitmap

Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids can share bitmaps and pixel shaders.

A single tile grid is also known as a Sprite.

hidden :bool

True when the TileGrid is hidden. This may be False even when a part of a hidden Group.

x :int

X position of the left edge in the parent.

y :int

Y position of the top edge in the parent.

flip_x :bool

If true, the left edge rendered will be the right edge of the right-most tile.

flip_y :bool

If true, the top edge rendered will be the bottom edge of the bottom-most tile.

transpose_xy :bool

If true, the TileGrid’s axis will be swapped. When combined with mirroring, any 90 degree rotation can be achieved along with the corresponding mirrored version.

pixel_shader :Union[ColorConverter, Palette]

The pixel shader of the tilegrid.

__getitem__(self, index: Union[Tuple[int, int], int])

Returns the tile index at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

print(grid[0])
__setitem__(self, index: Union[Tuple[int, int], int], value: int)

Sets the tile index at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

grid[0] = 10

or:

grid[0,0] = 10