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

class displayio.EPaperDisplay(display_bus, start_sequence, stop_sequence, *, width, height, ram_width, ram_height, colstart=0, rowstart=0, rotation=0, set_column_window_command=None, set_row_window_command=None, single_byte_bounds=False, write_black_ram_command, black_bits_inverted=False, write_color_ram_command=None, color_bits_inverted=False, highlight_color=0x000000, refresh_display_command, refresh_time=40, busy_pin=None, busy_state=True, seconds_per_frame=180, always_toggle_chip_select=False)

Create a EPaperDisplay object on the given display bus (displayio.FourWire or displayio.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 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.

  • display_bus (displayio.FourWire or displayio.ParallelBus) – The bus that the display is connected to
  • start_sequence (buffer) – Byte-packed initialization sequence.
  • stop_sequence (buffer) – 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

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.

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.


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