`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() → Any¶

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 :Any¶: Width of the bitmap. (read only)

height :Any¶: Height of the bitmap. (read only)

__getitem__(self, index: Any)¶

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: Any, value: Any)¶

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: Any)¶: Fills the bitmap with the supplied palette index value.

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

Converts one color format to another.

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

convert(self, color: Any)¶: Converts the given RGB888 color to RGB565

class displayio.Display(display_bus: Any, init_sequence: buffer, *, width: int = None, height: int = None, 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: microcontroller.Pin = None, brightness_command: int = None, brightness: bool = 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 :Any¶: True when the display is refreshed automatically.

brightness :Any¶: 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 :Any¶: 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 :Any¶

height :Any¶

rotation :Any¶: The rotation of the display as an int in degrees.

bus :Any¶

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: bytearray)¶

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: Any, start_sequence: buffer, stop_sequence: buffer, *, width: int = None, height: int = None, ram_width: int = None, ram_height: int = None, colstart: int = 0, rowstart: int = 0, rotation: int = 0, set_column_window_command: int = None, set_row_window_command: int = None, single_byte_bounds: Any = False, write_black_ram_command: int = None, black_bits_inverted: bool = False, write_color_ram_command: int = None, color_bits_inverted: bool = False, highlight_color: int = 0, refresh_display_command: int = None, refresh_time: float = 40, busy_pin: 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 :Any¶: Time, in fractional seconds, until the ePaper display can be refreshed.

width :Any¶: Gets the width of the display in pixels

height :Any¶

bus :Any¶

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 = None, chip_select: microcontroller.Pin = None, reset: 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: Any, data: Any, *, toggle_every_byte: Any = 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 :Any¶: 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 :Any¶: Scales each pixel within the Group in both directions. For example, when scale=2 each pixel will be represented by 2x2 pixels.

x :Any¶: X position of the Group in the parent.

y :Any¶: Y position of the Group in the parent.

append(self, layer: Any)¶: Append a layer to the group. It will be drawn above other layers.

insert(self, index: Any, layer: Any)¶: Insert a layer into the group.

index(self, layer: Any)¶: Returns the index of the first copy of layer. Raises ValueError if not found.

pop(self, i: Any = - 1)¶: Remove the ith item and return it.

remove(self, layer: Any)¶: Remove the first copy of layer. Raises ValueError if it is not present.

__len__(self)¶: Returns the number of layers in a Group

__getitem__(self, index: Any)¶

Returns the value at the given index.

This allows you to:

print(group[0])

__setitem__(self, index: Any, value: Any)¶

Sets the value at the given index.

This allows you to:

group[0] = sprite

__delitem__(self, index: Any)¶

Deletes the value at the given index.

This allows you to:

del group[0]

class displayio.I2CDisplay(i2c_bus: busio.I2C, *, device_address: int = None, reset: 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: Any, data: Any)¶: 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: file)¶

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 :Any¶: Width of the bitmap. (read only)

height :Any¶: 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.

__len__(self)¶: Returns the number of colors in a Palette

__setitem__(self, index: Any, value: Any)¶

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: Any)¶

make_opaque(self, palette_index: Any)¶

class displayio.ParallelBus(*, data0: microcontroller.Pin = None, command: microcontroller.Pin = None, chip_select: microcontroller.Pin = None, write: microcontroller.Pin = None, read: microcontroller.Pin = None, reset: microcontroller.Pin = None)¶

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: Any, data: Any)¶: 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: Any, start_x: Any, end_x: Any)¶: Loads pre-packed data into the given row.

class displayio.TileGrid(bitmap: displayio.Bitmap, *, pixel_shader: displayio.Palette = None, width: int = 1, height: int = 1, tile_width: int = None, tile_height: 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 :Any¶: True when the TileGrid is hidden. This may be False even when a part of a hidden Group.

x :Any¶: X position of the left edge in the parent.

y :Any¶: Y position of the top edge in the parent.

flip_x :Any¶: If true, the left edge rendered will be the right edge of the right-most tile.

flip_y :Any¶: If true, the top edge rendered will be the bottom edge of the bottom-most tile.

transpose_xy :Any¶: 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 :Any¶: The pixel shader of the tilegrid.

__getitem__(self, index: Any)¶

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: Any, tile_index: Any)¶

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

`displayio`¶

Previous topic

Next topic

This Page

displayio¶

`displayio`¶