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