displayio/epaperdisplay.py

   1 # SPDX-FileCopyrightText: 2020 Melissa LeBlanc-Williams for Adafruit Industries
   2 #
   3 # SPDX-License-Identifier: MIT
   4
   5 """
   6 `displayio.epaperdisplay`
   7 ================================================================================
   8
   9 displayio for Blinka
  10
  11 **Software and Dependencies:**
  12
  13 * Adafruit Blinka:
  14   https://github.com/adafruit/Adafruit_Blinka/releases
  15
  16 * Author(s): Melissa LeBlanc-Williams
  17
  18 """
  19
  20
  21 __version__ = "0.0.0-auto.0"
  22 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  23
  24
  25 class EPaperDisplay:
  26     """Manage updating an epaper display over a display bus
  27
  28     This initializes an epaper display and connects it into CircuitPython. Unlike other
  29     objects in CircuitPython, EPaperDisplay objects live until
  30     displayio.release_displays() is called. This is done so that CircuitPython can use
  31     the display itself.
  32
  33     Most people should not use this class directly. Use a specific display driver instead
  34     that will contain the startup and shutdown sequences at minimum.
  35     """
  36
  37     def __init__(
  38         self,
  39         display_bus,
  40         start_sequence,
  41         stop_sequence,
  42         *,
  43         width,
  44         height,
  45         ram_width,
  46         ram_height,
  47         colstart=0,
  48         rowstart=0,
  49         rotation=0,
  50         set_column_window_command=None,
  51         set_row_window_command=None,
  52         set_current_column_command=None,
  53         set_current_row_command=None,
  54         write_black_ram_command,
  55         black_bits_inverted=False,
  56         write_color_ram_command=None,
  57         color_bits_inverted=False,
  58         highlight_color=0x000000,
  59         refresh_display_command,
  60         refresh_time=40,
  61         busy_pin=None,
  62         busy_state=True,
  63         seconds_per_frame=180,
  64         always_toggle_chip_select=False,
  65         grayscale=False,
  66     ):
  67         # pylint: disable=too-many-locals,unnecessary-pass
  68         """
  69         Create a EPaperDisplay object on the given display bus (displayio.FourWire or
  70         displayio.ParallelBus).
  71
  72         The start_sequence and stop_sequence are bitpacked to minimize the ram impact. Every
  73         command begins with a command byte followed by a byte to determine the parameter
  74         count and if a delay is need after. When the top bit of the second byte is 1, the
  75         next byte will be the delay time in milliseconds. The remaining 7 bits are the
  76         parameter count excluding any delay byte. The third through final bytes are the
  77         remaining command parameters. The next byte will begin a new command definition.
  78
  79
  80         :param display_bus: The bus that the display is connected to
  81         :type _DisplayBus: displayio.FourWire or displayio.ParallelBus
  82         :param ~_typing.ReadableBuffer start_sequence: Byte-packed initialization sequence.
  83         :param ~_typing.ReadableBuffer stop_sequence: Byte-packed initialization sequence.
  84         :param int width: Width in pixels
  85         :param int height: Height in pixels
  86         :param int ram_width: RAM width in pixels
  87         :param int ram_height: RAM height in pixels
  88         :param int colstart: The index if the first visible column
  89         :param int rowstart: The index if the first visible row
  90         :param int rotation: The rotation of the display in degrees clockwise. Must be in
  91             90 degree increments (0, 90, 180, 270)
  92         :param int set_column_window_command: Command used to set the start and end columns
  93             to update
  94         :param int set_row_window_command: Command used so set the start and end rows to update
  95         :param int set_current_column_command: Command used to set the current column location
  96         :param int set_current_row_command: Command used to set the current row location
  97         :param int write_black_ram_command: Command used to write pixels values into the update
  98             region
  99         :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise,
 100             1 means to show black.
 101         :param int write_color_ram_command: Command used to write pixels values into the update
 102             region
 103         :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1
 104             means to show color.
 105         :param int highlight_color: RGB888 of source color to highlight with third ePaper color.
 106         :param int refresh_display_command: Command used to start a display refresh
 107         :param float refresh_time: Time it takes to refresh the display before the stop_sequence
 108             should be sent. Ignored when busy_pin is provided.
 109         :param microcontroller.Pin busy_pin: Pin used to signify the display is busy
 110         :param bool busy_state: State of the busy pin when the display is busy
 111         :param float seconds_per_frame: Minimum number of seconds between screen refreshes
 112         :param bool always_toggle_chip_select: When True, chip select is toggled every byte
 113         :param bool grayscale: When true, the color ram is the low bit of 2-bit grayscale
 114         """
 115         pass
 116
 117     def show(self, group):
 118         # pylint: disable=unnecessary-pass
 119         """Switches to displaying the given group of layers. When group is None, the default
 120         CircuitPython terminal will be shown (eventually).
 121         """
 122         pass
 123
 124     def refresh(self):
 125         # pylint: disable=unnecessary-pass
 126         """Refreshes the display immediately or raises an exception if too soon. Use
 127         ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur.
 128         """
 129         pass
 130
 131     @property
 132     def time_to_refresh(self):
 133         """Time, in fractional seconds, until the ePaper display can be refreshed."""
 134         return 0
 135
 136     @property
 137     def width(self):
 138         # pylint: disable=unnecessary-pass
 139         """Display Width"""
 140         pass
 141
 142     @property
 143     def height(self):
 144         # pylint: disable=unnecessary-pass
 145         """Display Height"""
 146         pass
 147
 148     @property
 149     def bus(self):
 150         # pylint: disable=unnecessary-pass
 151         """Current Display Bus"""
 152         pass