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
Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to index into a corresponding palette. This enables differently colored sprites to share the underlying Bitmap. value_count is used to minimize the memory used to store the Bitmap.
- Parameters
-
width
:int¶ Width of the bitmap. (read only)
-
height
:int¶ Height of the bitmap. (read only)
-
__getitem__
(self, index: Union[Tuple[int, 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])
-
class
displayio.
ColorConverter
(*, dither: bool = False)¶ Converts one color format to another.
Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 currently. :param bool dither: Adds random noise to dither the output image
-
dither
:bool¶ When true the color converter dithers the output by adding random noise when truncating to display bitdepth
-
-
displayio.
_DisplayBus
¶
-
class
displayio.
Display
(display_bus: _DisplayBus, init_sequence: ReadableBuffer, *, 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: 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.
Create a Display object on the given display bus (
FourWire
,ParallelBus
orI2CDisplay
).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 – 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.
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 (float) – 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.
-
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 ofbrightness
will change automatically. Ifbrightness
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 ifbrightness
is set manually.
-
width
:int¶ Gets the width of the board
-
height
:int¶ Gets the height of the board
-
rotation
:int¶ The rotation of the display as an int in degrees.
-
bus
:_DisplayBus¶ The bus being used by the display
-
show
(self, group: Group) → None¶ 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) → bool¶ 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.)
-
fill_row
(self, y: int, buffer: WriteableBuffer) → 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
-
class
displayio.
EPaperDisplay
(display_bus: _DisplayBus, start_sequence: ReadableBuffer, stop_sequence: ReadableBuffer, *, 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: Optional[int] = None, set_row_window_command: Optional[int] = None, single_byte_bounds: bool = False, write_black_ram_command: int = None, 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 = None, 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.
Create a EPaperDisplay object on the given display bus (
displayio.FourWire
ordisplayio.ParallelBus
).The
start_sequence
andstop_sequence
are 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.- Parameters
display_bus – The bus that the display is connected to
start_sequence (ReadableBuffer) – Byte-packed initialization sequence.
stop_sequence (ReadableBuffer) – Byte-packed initialization sequence.
width (int) – Width in pixels
height (int) – Height in pixels
ram_width (int) – RAM width in pixels
ram_height (int) – RAM 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)
set_column_window_command (int) – Command used to set the start and end columns to update
set_row_window_command (int) – Command used so set the start and end rows to update
set_current_column_command (int) – Command used to set the current column location
set_current_row_command (int) – Command used to set the current row location
write_black_ram_command (int) – Command used to write pixels values into the update region
black_bits_inverted (bool) – True if 0 bits are used to show black pixels. Otherwise, 1 means to show black.
write_color_ram_command (int) – Command used to write pixels values into the update region
color_bits_inverted (bool) – True if 0 bits are used to show the color. Otherwise, 1 means to show color.
highlight_color (int) – RGB888 of source color to highlight with third ePaper color.
refresh_display_command (int) – Command used to start a display refresh
refresh_time (float) – Time it takes to refresh the display before the stop_sequence should be sent. Ignored when busy_pin is provided.
busy_pin (microcontroller.Pin) – Pin used to signify the display is busy
busy_state (bool) – State of the busy pin when the display is busy
seconds_per_frame (float) – Minimum number of seconds between screen refreshes
always_toggle_chip_select (bool) – When True, chip select is toggled every byte
-
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¶ Gets the height of the display in pixels
-
bus
:_DisplayBus¶ The bus being used by the display
-
class
displayio.
FourWire
(spi_bus: busio.SPI, *, command: microcontroller.Pin = None, chip_select: microcontroller.Pin = None, 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.
Create a FourWire object associated with the given pins.
The SPI bus and pins are then in use by the display until
displayio.release_displays()
is called even after a reload. (It does this so CircuitPython can use the display after your code is done.) So, the first time you initialize a display bus in code.py you should call :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run.- Parameters
spi_bus (busio.SPI) – The SPI bus that make up the clock and data lines
command (microcontroller.Pin) – Data or command pin
chip_select (microcontroller.Pin) – Chip select pin
reset (microcontroller.Pin) – Reset pin. When None only software reset can be used
baudrate (int) – Maximum baudrate in Hz for the display on the bus
polarity (int) – the base state of the clock line (0 or 1)
phase (int) – the edge of the clock that data is captured. First (0) or second (1). Rising or falling depends on clock polarity.
-
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.
Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 leads to a layer’s pixel being 2x2 pixels when in the group.
- Parameters
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.VectorShape, Group, TileGrid]) → None¶ Append a layer to the group. It will be drawn above other layers.
-
insert
(self, index: int, layer: Union[vectorio.VectorShape, Group, TileGrid]) → None¶ Insert a layer into the group.
-
index
(self, layer: Union[vectorio.VectorShape, Group, TileGrid]) → int¶ Returns the index of the first copy of layer. Raises ValueError if not found.
-
pop
(self, i: int = - 1) → Union[vectorio.VectorShape, Group, TileGrid]¶ Remove the ith item and return it.
-
remove
(self, layer: Union[vectorio.VectorShape, Group, TileGrid]) → None¶ Remove the first copy of layer. Raises ValueError if it is not present.
-
__getitem__
(self, index: int) → Union[vectorio.VectorShape, Group, TileGrid]¶ Returns the value at the given index.
This allows you to:
print(group[0])
-
__setitem__
(self, index: int, value: Union[vectorio.VectorShape, Group, TileGrid]) → None¶ Sets the value at the given index.
This allows you to:
group[0] = sprite
-
class
displayio.
I2CDisplay
(i2c_bus: busio.I2C, *, device_address: int = None, reset: Optional[microcontroller.Pin] = None)¶ Manage updating a display over I2C in the background while Python code runs. It doesn’t handle display initialization.
Create a I2CDisplay object associated with the given I2C bus and reset pin.
The I2C bus and pins are then in use by the display until
displayio.release_displays()
is called even after a reload. (It does this so CircuitPython can use the display after your code is done.) So, the first time you initialize a display bus in code.py you should call :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run.- Parameters
i2c_bus (busio.I2C) – The I2C bus that make up the clock and data lines
device_address (int) – The I2C address of the device
reset (microcontroller.Pin) – Reset pin. When None only software reset can be used
-
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
Create an OnDiskBitmap object with the given file.
- Parameters
file (file) – The open bitmap file
-
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.
Create a Palette object to store a set number of colors.
- Parameters
color_count (int) – The number of colors in the Palette
-
__getitem__
(self, index: int) → Optional[int]¶ Return the pixel color at the given index as an integer.
-
__setitem__
(self, index: int, value: Union[int, ReadableBuffer, Tuple[int, int, int]]) → None¶ 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
-
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.
Create a ParallelBus object associated with the given pins. The bus is inferred from data0 by implying the next 7 additional pins on a given GPIO port.
The parallel bus and pins are then in use by the display until
displayio.release_displays()
is called even after a reload. (It does this so CircuitPython can use the display after your code is done.) So, the first time you initialize a display bus in code.py you should call :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run.- Parameters
data0 (microcontroller.Pin) – The first data pin. The rest are implied
command (microcontroller.Pin) – Data or command pin
chip_select (microcontroller.Pin) – Chip select pin
write (microcontroller.Pin) – Write pin
read (microcontroller.Pin) – Read pin
reset (microcontroller.Pin) – Reset pin
-
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.
Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the column boundaries of the shape on each row. Each row’s boundary defaults to the full row.
- Parameters
-
class
displayio.
TileGrid
(bitmap: Bitmap, *, pixel_shader: Union[ColorConverter, Palette] = None, 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.
Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to convert the value and its location to a display native pixel color. This may be a simple color palette lookup, a gradient, a pattern or a color transformer.
tile_width and tile_height match the height of the bitmap by default.
- Parameters
bitmap (Bitmap) – The bitmap storing one or more tiles.
or Palette pixel_shader (ColorConverter) – The pixel shader that produces colors from values
width (int) – Width of the grid in tiles.
height (int) – Height of the grid in tiles.
tile_width (int) – Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap’s dimensions.
tile_height (int) – Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap’s dimensions.
default_tile (int) – Default tile index to show.
x (int) – Initial x position of the left edge within the parent.
y (int) – Initial y position of the top edge within the parent.
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.