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 circuitpython_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: circuitpython_typing.ReadableBuffer,
  46         stop_sequence: circuitpython_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.0,
  66         busy_pin: Optional[microcontroller.Pin] = None,
  67         busy_state: bool = True,
  68         seconds_per_frame: float = 180.0,
  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 ~circuitpython_typing.ReadableBuffer start_sequence: Byte-packed
  88             initialization sequence.
  89         :param ~circuitpython_typing.ReadableBuffer stop_sequence: Byte-packed
  90             initialization sequence.
  91         :param int width: Width in pixels
  92         :param int height: Height in pixels
  93         :param int ram_width: RAM width in pixels
  94         :param int ram_height: RAM height in pixels
  95         :param int colstart: The index if the first visible column
  96         :param int rowstart: The index if the first visible row
  97         :param int rotation: The rotation of the display in degrees clockwise. Must be in
  98             90 degree increments (0, 90, 180, 270)
  99         :param int set_column_window_command: Command used to set the start and end columns
 100             to update
 101         :param int set_row_window_command: Command used so set the start and end rows to update
 102         :param int set_current_column_command: Command used to set the current column location
 103         :param int set_current_row_command: Command used to set the current row location
 104         :param int write_black_ram_command: Command used to write pixels values into the update
 105             region
 106         :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise,
 107             1 means to show black.
 108         :param int write_color_ram_command: Command used to write pixels values into the update
 109             region
 110         :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1
 111             means to show color.
 112         :param int highlight_color: RGB888 of source color to highlight with third ePaper color.
 113         :param int refresh_display_command: Command used to start a display refresh
 114         :param float refresh_time: Time it takes to refresh the display before the stop_sequence
 115             should be sent. Ignored when busy_pin is provided.
 116         :param microcontroller.Pin busy_pin: Pin used to signify the display is busy
 117         :param bool busy_state: State of the busy pin when the display is busy
 118         :param float seconds_per_frame: Minimum number of seconds between screen refreshes
 119         :param bool always_toggle_chip_select: When True, chip select is toggled every byte
 120         :param bool grayscale: When true, the color ram is the low bit of 2-bit grayscale
 121         """
 122         self._bus = display_bus
 123         self._width = width
 124         self._height = height
 125
 126     def show(self, group: Group) -> None:
 127         # pylint: disable=unnecessary-pass
 128         """Switches to displaying the given group of layers. When group is None, the default
 129         CircuitPython terminal will be shown (eventually).
 130         """
 131         pass
 132
 133     def refresh(self) -> None:
 134         # pylint: disable=unnecessary-pass
 135         """Refreshes the display immediately or raises an exception if too soon. Use
 136         ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur.
 137         """
 138         pass
 139
 140     @property
 141     def time_to_refresh(self) -> float:
 142         """Time, in fractional seconds, until the ePaper display can be refreshed."""
 143         return 0.0
 144
 145     @property
 146     def width(self) -> int:
 147         """Display Width"""
 148         return self._width
 149
 150     @property
 151     def height(self) -> int:
 152         """Display Height"""
 153         return self._height
 154
 155     @property
 156     def bus(self) -> _DisplayBus:
 157         """Current Display Bus"""
 158         return self._bus