displayio – Native helpers for driving displays

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

Available on these boards
  • ARAMCON Badge 2019
  • ARAMCON2 Badge
  • ATMegaZero ESP32-S2
  • Adafruit CLUE nRF52840 Express
  • Adafruit Circuit Playground Bluefruit
  • Adafruit CircuitPlayground Express with displayio
  • Adafruit EdgeBadge
  • Adafruit Feather Bluefruit Sense
  • Adafruit Feather M0 Express
  • Adafruit Feather M4 CAN
  • Adafruit Feather M4 Express
  • Adafruit Feather MIMXRT1011
  • Adafruit Feather RP2040
  • Adafruit Feather STM32F405 Express
  • Adafruit Feather nRF52840 Express
  • Adafruit FunHouse
  • Adafruit Grand Central M4 Express
  • Adafruit Hallowing M4 Express
  • Adafruit ItsyBitsy M0 Express
  • Adafruit ItsyBitsy M4 Express
  • Adafruit ItsyBitsy RP2040
  • Adafruit ItsyBitsy nRF52840 Express
  • Adafruit LED Glasses Driver nRF52840
  • Adafruit Macropad RP2040
  • Adafruit MagTag
  • Adafruit Matrix Portal M4
  • Adafruit Metro ESP32S2
  • Adafruit Metro M0 Express
  • Adafruit Metro M4 Airlift Lite
  • Adafruit Metro M4 Express
  • Adafruit Metro nRF52840 Express
  • Adafruit Monster M4SK
  • Adafruit PyGamer
  • Adafruit PyPortal
  • Adafruit PyPortal Pynt
  • Adafruit PyPortal Titano
  • Adafruit Pybadge
  • Adafruit QT Py M0 Haxpress
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Adafruit Trellis M4 Express
  • AloriumTech Evo M51
  • Arduino Nano 33 BLE
  • Arduino Nano RP2040 Connect
  • Artisense Reference Design RD00
  • AtelierDuMaker nRF52840 Breakout
  • BDMICRO VINA-D21
  • BDMICRO VINA-D51
  • BLE-SS dev board Multi Sensor
  • BastBLE
  • BastWiFi
  • BlueMicro840
  • CP Sapling M0 w/ SPI Flash
  • CP32-M4
  • Capable Robot Programmable USB Hub
  • Cedar Grove StringCar M0 Express
  • Challenger RP2040 WiFi
  • CircuitBrains Basic
  • CircuitBrains Deluxe
  • CrumpS2
  • Cytron Maker Pi RP2040
  • DynOSSAT-EDU-EPS
  • DynOSSAT-EDU-OBC
  • ESP 12k NodeMCU
  • Electronic Cats Hunter Cat NFC
  • Electronut Labs Blip
  • Electronut Labs Papyr
  • EncoderPad RP2040
  • Espruino Pico
  • Espruino Wifi
  • Feather ESP32S2 without PSRAM
  • Feather MIMXRT1011
  • Feather MIMXRT1062
  • FeatherS2
  • FeatherS2 Neo
  • FeatherS2 PreRelease
  • Franzininho WIFI w/Wroom
  • Franzininho WIFI w/Wrover
  • Gravitech Cucumber M
  • Gravitech Cucumber MS
  • Gravitech Cucumber R
  • Gravitech Cucumber RS
  • HMI-DevKit-1.1
  • Hacked Feather M0 Express with 8Mbyte SPI flash
  • HalloWing M0 Express
  • HiiBot BlueFi
  • IMXRT1010-EVK
  • IkigaiSense Vita nRF52840
  • Kaluga 1
  • LILYGO TTGO T8 ESP32-S2 w/Display
  • MDBT50Q-DB-40
  • MDBT50Q-RX Dongle
  • MEOWBIT
  • MORPHEANS MorphESP-240
  • MakerDiary nRF52840 MDK
  • MakerDiary nRF52840 MDK USB Dongle
  • Makerdiary M60 Keyboard
  • Makerdiary Pitaya Go
  • Makerdiary nRF52840 M.2 Developer Kit
  • Metro MIMXRT1011
  • Mini SAM M4
  • NUCLEO STM32F746
  • NUCLEO STM32F767
  • NUCLEO STM32H743
  • OPENMV-H7 R1
  • Oak Dev Tech PixelWing ESP32S2
  • Open Hardware Summit 2020 Badge
  • PCA10056 nRF52840-DK
  • PCA10059 nRF52840 Dongle
  • PYB LR Nano V2
  • Particle Argon
  • Particle Boron
  • Particle Xenon
  • PewPew M4
  • Pimoroni Interstate 75
  • Pimoroni Keybow 2040
  • Pimoroni PGA2040
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni PicoSystem
  • Pimoroni Plasma 2040
  • Pimoroni Tiny 2040
  • PyboardV1_1
  • Raspberry Pi Pico
  • S2Mini
  • SAM E54 Xplained Pro
  • SAM32v26
  • ST STM32F746G Discovery
  • STM32F411E_DISCO
  • STM32F412G_DISCO
  • STM32F4_DISCO
  • Saola 1 w/Wroom
  • Saola 1 w/Wrover
  • Seeeduino Wio Terminal
  • Serpente
  • Silicognition LLC M4-Shim
  • SparkFun LUMIDrive
  • SparkFun MicroMod RP2040 Processor
  • SparkFun MicroMod SAMD51 Processor
  • SparkFun MicroMod nRF52840 Processor
  • SparkFun Pro Micro RP2040
  • SparkFun Pro nRF52840 Mini
  • SparkFun RedBoard Turbo
  • SparkFun STM32 MicroMod Processor
  • SparkFun Thing Plus - RP2040
  • SparkFun Thing Plus - SAMD51
  • StackRduino M0 PRO
  • TG-Boards' Datalore IP M4
  • TG-Watch
  • THUNDERPACK_v11
  • THUNDERPACK_v12
  • Targett Module Clip w/Wroom
  • Targett Module Clip w/Wrover
  • Teensy 4.0
  • Teensy 4.1
  • Teknikio Bluebird
  • The Open Book Feather
  • TinkeringTech ScoutMakes Azul
  • TinyS2
  • Trinket M0 Haxpress
  • UARTLogger II
  • WarmBit BluePixel nRF52840
  • iMX RT 1020 EVK
  • iMX RT 1060 EVK
  • keithp.com snekboard
  • microS2
  • nanoESP32-S2 w/Wrover
  • nanoESP32-S2 w/Wroom
  • nice!nano
  • stm32f411ce-blackpill
  • stm32f411ce-blackpill-with-flash
  • uGame10

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.Colorspace

The colorspace for a ColorConverter to operate in

RGB888 :Colorspace

The standard 24-bit colorspace. Bits 0-7 are blue, 8-15 are green, and 16-24 are red. (0xRRGGBB)

RGB565 :Colorspace

The standard 16-bit colorspace. Bits 0-4 are blue, bits 5-10 are green, and 11-15 are red (0bRRRRRGGGGGGBBBBB)

RGB565_SWAPPED :Colorspace

The swapped 16-bit colorspace. First, the high and low 8 bits of the number are swapped, then they are interpreted as for RGB565

RGB555 :Colorspace

The standard 15-bit colorspace. Bits 0-4 are blue, bits 5-9 are green, and 11-14 are red. The top bit is ignored. (0bxRRRRRGGGGGBBBBB)

RGB555_SWAPPED :Colorspace

The swapped 15-bit colorspace. First, the high and low 8 bits of the number are swapped, then they are interpreted as for RGB555

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

Stores values of a certain size in a 2D array

Bitmaps can be treated as read-only buffers. If the number of bits in a pixel is 8, 16, or 32; and the number of bytes per row is a multiple of 4, then the resulting memoryview will correspond directly with the bitmap’s contents. Otherwise, the bitmap data is packed into the memoryview with unspecified padding.

A Bitmap can be treated as a buffer, allowing its content to be viewed and modified using e.g., with ulab.numpy.frombuffer, but the displayio.Bitmap.dirty method must be used to inform displayio when a bitmap was modified through the buffer interface.

bitmaptools.arrayblit can also be useful to move data efficiently into a Bitmap.

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) – The number of values wide

  • height (int) – The number of values high

  • value_count (int) – The number of possible pixel values.

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])
__setitem__(self, index: Union[Tuple[int, int], int], value: int)None

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
blit(self, x: int, y: int, source_bitmap: Bitmap, *, x1: int, y1: int, x2: int, y2: int, skip_index: int)None
Inserts the source_bitmap region defined by rectangular boundaries

(x1,y1) and (x2,y2) into the bitmap at the specified (x,y) location.

Parameters
  • x (int) – Horizontal pixel location in bitmap where source_bitmap upper-left corner will be placed

  • y (int) – Vertical pixel location in bitmap where source_bitmap upper-left corner will be placed

  • source_bitmap (bitmap) – Source bitmap that contains the graphical region to be copied

  • x1 (int) – Minimum x-value for rectangular bounding box to be copied from the source bitmap

  • y1 (int) – Minimum y-value for rectangular bounding box to be copied from the source bitmap

  • x2 (int) – Maximum x-value (exclusive) for rectangular bounding box to be copied from the source bitmap

  • y2 (int) – Maximum y-value (exclusive) for rectangular bounding box to be copied from the source bitmap

  • skip_index (int) – bitmap palette index in the source that will not be copied, set to None to copy all pixels

fill(self, value: int)None

Fills the bitmap with the supplied palette index value.

dirty(self, x1: int = 0, y1: int = 0, x2: int = - 1, y2: int = - 1)None

Inform displayio of bitmap updates done via the buffer protocol.

Parameters
  • x1 (int) – Minimum x-value for rectangular bounding box to be considered as modified

  • y1 (int) – Minimum y-value for rectangular bounding box to be considered as modified

  • x2 (int) – Maximum x-value (exclusive) for rectangular bounding box to be considered as modified

  • y2 (int) – Maximum y-value (exclusive) for rectangular bounding box to be considered as modified

If x1 or y1 are not specified, they are taken as 0. If x2 or y2 are not specified, or are given as -1, they are taken as the width and height of the image. Thus, calling dirty() with the default arguments treats the whole bitmap as modified.

When a bitmap is modified through the buffer protocol, the display will not be properly updated unless the bitmap is notified of the “dirty rectangle” that encloses all modified pixels.

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

Converts one color format to another.

Create a ColorConverter object to convert color formats.

Parameters
  • colorspace (Colorspace) – The source colorspace, one of the Colorspace constants

  • dither (bool) – Adds random noise to dither the output image

dither :bool

When True the ColorConverter dithers the output by adding random noise when truncating to display bitdepth

convert(self, color: int)int

Converts the given color to RGB565 according to the Colorspace

make_transparent(self, color: int)None

Set the transparent color or index for the ColorConverter. This will raise an Exception if there is already a selected transparent index.

Parameters

color (int) – The color to be transparent

make_opaque(self, color: int)None

Make the ColorConverter be opaque and have no transparent pixels.

Parameters

color (int) – [IGNORED] Use any value

displayio._DisplayBus

FourWire, paralleldisplay.ParallelBus or I2CDisplay

class displayio.Display(display_bus: _DisplayBus, init_sequence: _typing.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, 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, backlight_on_high: bool = True, SH1107_addressing: bool = False)

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 or I2CDisplay).

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 delay. When the top bit of the second byte is 1 (0x80), a delay will occur after the command parameters are sent. The remaining 7 bits are the parameter count excluding any delay byte. The bytes following are the parameters. When the delay bit is set, a single byte after the parameters specifies the delay duration in milliseconds. The value 0xff will lead to an extra long 500 ms delay instead of 255 ms. The next byte will begin a new command definition. Here is an example:

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\x81\xaa\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 is 0x11 with 0 parameters and a 120ms (0x78) delay. The third command is 0x29 with one parameter 0xaa and a 120ms delay (0x78). 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.

  • 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.

  • SH1107_addressing (bool) – Special quirk for SH1107, use upper/lower column set and page set

  • set_vertical_scroll (int) – This parameter is accepted but ignored for backwards compatibility. It will be removed in a future release.

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

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: Optional[int] = None, minimum_frames_per_second: int = 0)bool

When auto_refresh is off, and target_frames_per_second is not None this 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. The default minimum_frames_per_second of 0 disables this behavior.

When auto_refresh is off, and target_frames_per_second is None this will update the display immediately.

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

Parameters
  • target_frames_per_second (Optional[int]) – The target frame rate that refresh() should try to achieve. Set to None for immediate refresh.

  • minimum_frames_per_second (int) – The minimum number of times the screen should be updated per second.

fill_row(self, y: int, buffer: _typing.WriteableBuffer)_typing.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: _typing.ReadableBuffer, stop_sequence: _typing.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, set_current_column_command: Optional[int] = None, set_current_row_command: Optional[int] = None, 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, grayscale: 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 or paralleldisplay.ParallelBus).

The start_sequence and stop_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 delay. When the top bit of the second byte is 1 (0x80), a delay will occur after the command parameters are sent. The remaining 7 bits are the parameter count excluding any delay byte. The bytes following are the parameters. When the delay bit is set, a single byte after the parameters specifies the delay duration in milliseconds. The value 0xff will lead to an extra long 500 ms delay instead of 255 ms. 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

  • grayscale (bool) – When true, the color ram is the low bit of 2-bit grayscale

time_to_refresh :float

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

busy :bool

True when the display is refreshing. This uses the busy_pin when available or the refresh_time otherwise.

width :int

Gets the width of the display in pixels

height :int

Gets the height of the display in pixels

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.

update_refresh_mode(self, start_sequence: _typing.ReadableBuffer, seconds_per_frame: float = 180)None

Updates the start_sequence and seconds_per_frame parameters to enable varying the refresh mode of the display.

refresh(self)None

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.

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

reset(self)None

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

send(self, command: int, data: _typing.ReadableBuffer, *, toggle_every_byte: bool = False)None

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(*, 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
  • scale (int) – Scale of layer pixels in one dimension.

  • x (int) – Initial x position within the parent.

  • y (int) – Initial y position within the parent.

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.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid])None

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

insert(self, index: int, layer: Union[vectorio.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid])None

Insert a layer into the group.

index(self, layer: Union[vectorio.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid])int

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

pop(self, i: int = - 1)Union[vectorio.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid]

Remove the ith item and return it.

remove(self, layer: Union[vectorio.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid])None

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

__bool__(self)bool
__len__(self)int

Returns the number of layers in a Group

__getitem__(self, index: int)Union[vectorio.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid]

Returns the value at the given index.

This allows you to:

print(group[0])
__setitem__(self, index: int, value: Union[vectorio.Circle, vectorio.Rectangle, vectorio.Polygon, Group, TileGrid])None

Sets the value at the given index.

This allows you to:

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

Deletes the value at the given index.

This allows you to:

del group[0]
sort(self, key: function, reverse: bool)None

Sort the members of the group.

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.

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

reset(self)None

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

send(self, command: int, data: _typing.ReadableBuffer)None

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: Union[str, 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)

odb = displayio.OnDiskBitmap('/sample.bmp')
face = displayio.TileGrid(odb, pixel_shader=odb.pixel_shader)
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 name of the bitmap file. For backwards compatibility, a file opened in binary mode may also be passed.

Older versions of CircuitPython required a file opened in binary mode. CircuitPython 7.0 modified OnDiskBitmap so that it takes a filename instead, and opens the file internally. A future version of CircuitPython will remove the ability to pass in an opened file.

width :int

Width of the bitmap. (read only)

height :int

Height of the bitmap. (read only)

pixel_shader :Union[ColorConverter, Palette]

The image’s pixel_shader. The type depends on the underlying bitmap’s structure. The pixel shadder can be modified (e.g., to set the transparent pixel or, for paletted images, to update the palette

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

__bool__(self)bool
__len__(self)int

Returns the number of colors in a 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, _typing.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
make_transparent(self, palette_index: int)None
make_opaque(self, palette_index: int)None
is_transparent(self, palette_index: int)bool

Returns True if the palette index is transparent. Returns False if opaque.

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
  • width (int) – The number of pixels wide

  • height (int) – The number of pixels high

  • mirror_x (bool) – When true the left boundary is mirrored to the right.

  • mirror_y (bool) – When true the top boundary is mirrored to the bottom.

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

Loads pre-packed data into the given row.

class displayio.TileGrid(bitmap: Union[Bitmap, OnDiskBitmap, Shape], *, 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.

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,OnDiskBitmap,Shape) – The bitmap storing one or more tiles.

  • pixel_shader (ColorConverter,Palette) – 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.

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])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)None

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