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 import time
  21 from typing import Optional, Union
  22 import microcontroller
  23 from digitalio import DigitalInOut
  24 from circuitpython_typing import ReadableBuffer
  25 from ._displaycore import _DisplayCore
  26 from ._group import Group, circuitpython_splash
  27 from ._colorconverter import ColorConverter
  28 from ._displaybus import _DisplayBus
  29 from ._area import Area
  30 from ._constants import (
  31     CHIP_SELECT_TOGGLE_EVERY_BYTE,
  32     CHIP_SELECT_UNTOUCHED,
  33     DISPLAY_COMMAND,
  34     DISPLAY_DATA,
  35     NO_COMMAND,
  36     DELAY,
  37 )
  38
  39 __version__ = "0.0.0+auto.0"
  40 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  41
  42
  43 class EPaperDisplay:
  44     # pylint: disable=too-many-instance-attributes
  45     """Manage updating an epaper display over a display bus
  46
  47     This initializes an epaper display and connects it into CircuitPython. Unlike other
  48     objects in CircuitPython, EPaperDisplay objects live until
  49     displayio.release_displays() is called. This is done so that CircuitPython can use
  50     the display itself.
  51
  52     Most people should not use this class directly. Use a specific display driver instead
  53     that will contain the startup and shutdown sequences at minimum.
  54     """
  55
  56     def __init__(
  57         self,
  58         display_bus: _DisplayBus,
  59         start_sequence: ReadableBuffer,
  60         stop_sequence: ReadableBuffer,
  61         *,
  62         width: int,
  63         height: int,
  64         ram_width: int,
  65         ram_height: int,
  66         colstart: int = 0,
  67         rowstart: int = 0,
  68         rotation: int = 0,
  69         set_column_window_command: Optional[int] = None,
  70         set_row_window_command: Optional[int] = None,
  71         set_current_column_command: Optional[int] = None,
  72         set_current_row_command: Optional[int] = None,
  73         write_black_ram_command: int,
  74         black_bits_inverted: bool = False,
  75         write_color_ram_command: Optional[int] = None,
  76         color_bits_inverted: bool = False,
  77         highlight_color: int = 0x000000,
  78         refresh_display_command: Union[int, ReadableBuffer],
  79         refresh_time: float = 40.0,
  80         busy_pin: Optional[microcontroller.Pin] = None,
  81         busy_state: bool = True,
  82         seconds_per_frame: float = 180,
  83         always_toggle_chip_select: bool = False,
  84         grayscale: bool = False,
  85         advanced_color_epaper: bool = False,
  86         two_byte_sequence_length: bool = False,
  87         start_up_time: float = 0,
  88         address_little_endian: bool = False,
  89     ) -> None:
  90         # pylint: disable=too-many-locals
  91         """Create a EPaperDisplay object on the given display bus (`displayio.FourWire` or
  92         `paralleldisplay.ParallelBus`).
  93
  94         The ``start_sequence`` and ``stop_sequence`` are bitpacked to minimize the ram impact. Every
  95         command begins with a command byte followed by a byte to determine the parameter count and
  96         delay. When the top bit of the second byte is 1 (0x80), a delay will occur after the command
  97         parameters are sent. The remaining 7 bits are the parameter count excluding any delay
  98         byte. The bytes following are the parameters. When the delay bit is set, a single byte after
  99         the parameters specifies the delay duration in milliseconds. The value 0xff will lead to an
 100         extra long 500 ms delay instead of 255 ms. The next byte will begin a new command
 101         definition.
 102
 103         :param display_bus: The bus that the display is connected to
 104         :type _DisplayBus: displayio.FourWire or paralleldisplay.ParallelBus
 105         :param ~circuitpython_typing.ReadableBuffer start_sequence: Byte-packed command sequence.
 106         :param ~circuitpython_typing.ReadableBuffer stop_sequence: Byte-packed command sequence.
 107         :param int width: Width in pixels
 108         :param int height: Height in pixels
 109         :param int ram_width: RAM width in pixels
 110         :param int ram_height: RAM height in pixels
 111         :param int colstart: The index if the first visible column
 112         :param int rowstart: The index if the first visible row
 113         :param int rotation: The rotation of the display in degrees clockwise. Must be in
 114             90 degree increments (0, 90, 180, 270)
 115         :param int set_column_window_command: Command used to set the start and end columns
 116             to update
 117         :param int set_row_window_command: Command used so set the start and end rows to update
 118         :param int set_current_column_command: Command used to set the current column location
 119         :param int set_current_row_command: Command used to set the current row location
 120         :param int write_black_ram_command: Command used to write pixels values into the update
 121             region
 122         :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise,
 123             1 means to show black.
 124         :param int write_color_ram_command: Command used to write pixels values into the update
 125             region
 126         :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1
 127             means to show color.
 128         :param int highlight_color: RGB888 of source color to highlight with third ePaper color.
 129         :param int refresh_display_command: Command used to start a display refresh. Single int
 130             or byte-packed command sequence
 131         :param float refresh_time: Time it takes to refresh the display before the stop_sequence
 132             should be sent. Ignored when busy_pin is provided.
 133         :param microcontroller.Pin busy_pin: Pin used to signify the display is busy
 134         :param bool busy_state: State of the busy pin when the display is busy
 135         :param float seconds_per_frame: Minimum number of seconds between screen refreshes
 136         :param bool always_toggle_chip_select: When True, chip select is toggled every byte
 137         :param bool grayscale: When true, the color ram is the low bit of 2-bit grayscale
 138         :param bool advanced_color_epaper: When true, the display is a 7-color advanced color
 139             epaper (ACeP)
 140         :param bool two_byte_sequence_length: When true, use two bytes to define sequence length
 141         :param float start_up_time: Time to wait after reset before sending commands
 142         :param bool address_little_endian: Send the least significant byte (not bit) of
 143             multi-byte addresses first. Ignored when ram is addressed with one byte
 144         """
 145
 146         if isinstance(refresh_display_command, int):
 147             refresh_sequence = bytearray([refresh_display_command, 0])
 148             if two_byte_sequence_length:
 149                 refresh_sequence += bytes([0])
 150         elif isinstance(refresh_display_command, ReadableBuffer):
 151             refresh_sequence = bytearray(refresh_display_command)
 152         else:
 153             raise ValueError("Invalid refresh_display_command")
 154
 155         if write_color_ram_command is None:
 156             write_color_ram_command = NO_COMMAND
 157
 158         if rotation % 90 != 0:
 159             raise ValueError("Display rotation must be in 90 degree increments")
 160
 161         color_depth = 1
 162         core_grayscale = True
 163
 164         if advanced_color_epaper:
 165             color_depth = 4
 166             grayscale = False
 167             core_grayscale = False
 168
 169         self._core = _DisplayCore(
 170             bus=display_bus,
 171             width=width,
 172             height=height,
 173             ram_width=ram_width,
 174             ram_height=ram_height,
 175             colstart=colstart,
 176             rowstart=rowstart,
 177             rotation=rotation,
 178             color_depth=color_depth,
 179             grayscale=core_grayscale,
 180             pixels_in_byte_share_row=True,
 181             bytes_per_cell=1,
 182             reverse_pixels_in_byte=True,
 183             reverse_bytes_in_word=True,
 184             column_command=set_column_window_command,
 185             row_command=set_row_window_command,
 186             set_current_column_command=set_current_column_command,
 187             set_current_row_command=set_current_row_command,
 188             data_as_commands=False,
 189             always_toggle_chip_select=always_toggle_chip_select,
 190             sh1107_addressing=False,
 191             address_little_endian=address_little_endian,
 192         )
 193
 194         if highlight_color != 0x000000:
 195             self._core.colorspace.tricolor = True
 196             self._core.colorspace.tricolor_hue = ColorConverter._compute_hue(
 197                 highlight_color
 198             )
 199             self._core.colorspace.tricolor_luma = ColorConverter._compute_luma(
 200                 highlight_color
 201             )
 202         else:
 203             self._core.colorspace.tricolor = False
 204
 205         self._acep = advanced_color_epaper
 206         self._core.colorspace.sevencolor = advanced_color_epaper
 207         self._write_black_ram_command = write_black_ram_command
 208         self._black_bits_inverted = black_bits_inverted
 209         self._write_color_ram_command = write_color_ram_command
 210         self._color_bits_inverted = color_bits_inverted
 211         self._refresh_time_ms = refresh_time * 1000
 212         self._busy_state = busy_state
 213         self._refreshing = False
 214         self._milliseconds_per_frame = seconds_per_frame * 1000
 215         self._chip_select = (
 216             CHIP_SELECT_TOGGLE_EVERY_BYTE
 217             if always_toggle_chip_select
 218             else CHIP_SELECT_UNTOUCHED
 219         )
 220         self._grayscale = grayscale
 221
 222         self._start_sequence = start_sequence
 223         self._start_up_time = start_up_time
 224         self._stop_sequence = stop_sequence
 225         self._refesh_sequence = refresh_sequence
 226         self._busy = None
 227         self._two_byte_sequence_length = two_byte_sequence_length
 228         if busy_pin is not None:
 229             self._busy = DigitalInOut(busy_pin)
 230             self._busy.switch_to_input()
 231
 232         # Clear the color memory if it isn't in use
 233         if highlight_color == 0x00 and write_color_ram_command != NO_COMMAND:
 234             """TODO: Clear"""
 235
 236         self.show(circuitpython_splash)
 237
 238     def __new__(cls, *args, **kwargs):
 239         from . import (  # pylint: disable=import-outside-toplevel, cyclic-import
 240             allocate_display,
 241         )
 242
 243         display_instance = super().__new__(cls)
 244         allocate_display(display_instance)
 245         return display_instance
 246
 247     def show(self, group: Group) -> None:
 248         # pylint: disable=unnecessary-pass
 249         """Switches to displaying the given group of layers. When group is None, the default
 250         CircuitPython terminal will be shown (eventually).
 251         """
 252         if group is None:
 253             group = circuitpython_splash
 254         self._core.set_root_group(group)
 255
 256     def update_refresh_mode(
 257         self, start_sequence: ReadableBuffer, seconds_per_frame: float
 258     ) -> None:
 259         """Updates the ``start_sequence`` and ``seconds_per_frame`` parameters to enable
 260         varying the refresh mode of the display."""
 261         self._start_sequence = bytearray(start_sequence)
 262         self._milliseconds_per_frame = seconds_per_frame * 1000
 263
 264     def refresh(self) -> None:
 265         """Refreshes the display immediately or raises an exception if too soon. Use
 266         ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur.
 267         """
 268         if not self._refresh():
 269             raise RuntimeError("Refresh too soon")
 270
 271     def _refresh(self) -> bool:
 272         if self._refreshing and self._busy is not None:
 273             if self._busy.value != self._busy_state:
 274                 self._refreshing = False
 275                 self._send_command_sequence(False, self._stop_sequence)
 276             else:
 277                 return False
 278         if self._core.current_group is None:
 279             return True
 280         # Refresh at seconds per frame rate
 281         if self.time_to_refresh > 0:
 282             return False
 283
 284         # TODO: Finish Implementing
 285         return True
 286
 287     def _release(self) -> None:
 288         """Release the display and free its resources"""
 289         if self._refreshing:
 290             self._wait_for_busy()
 291             self._refreshing = False
 292             # Run stop sequence but don't wait for busy because busy is set when sleeping
 293             self._send_command_sequence(False, self._stop_sequence)
 294         self._core.release_display_core()
 295         if self._busy is not None:
 296             self._busy.deinit()
 297
 298     def _background(self):
 299         """Run background refresh tasks."""
 300         if self._refreshing:
 301             refresh_done = False
 302             if self._busy is not None:
 303                 busy = self._busy.value
 304                 refresh_done = busy == self._busy_state
 305             else:
 306                 refresh_done = (
 307                     time.monotonic() * 1000 - self._core.last_refresh
 308                     > self._refresh_time
 309                 )
 310             if refresh_done:
 311                 self._refreshing = False
 312                 self._finish_refresh()
 313                 # Run stop sequence but don't wait for busy because busy is set when sleeping
 314                 self._send_command_sequence(False, self._stop_sequence)
 315
 316     def _get_refresh_areas(self) -> list[Area]:
 317         """Get a list of areas to be refreshed"""
 318         areas = []
 319         if self._core.full_refresh:
 320             areas.append(self._core.area)
 321             return areas
 322         first_area = None
 323         if self._core.current_group is not None:
 324             self._core.current_group._get_refresh_areas(  # pylint: disable=protected-access
 325                 areas
 326             )
 327             first_area = areas[0]
 328         if first_area is not None and self._core.row_command == NO_COMMAND:
 329             # Do a full refresh if the display doesn't support partial updates
 330             areas = [self._core.area]
 331         return areas
 332
 333     def _refresh_areas(self, areas: list[Area]) -> None:
 334         """Loop through dirty areas and redraw that area."""
 335         # TODO: Implement
 336
 337     def _send_command_sequence(
 338         self, should_wait_for_busy: bool, sequence: ReadableBuffer
 339     ) -> None:
 340         i = 0
 341         while i < len(sequence):
 342             command = sequence[i]
 343             data_size = sequence[i + 1]
 344             delay = (data_size & DELAY) != 0
 345             data_size &= ~DELAY
 346             data = sequence[i + 2 : i + 2 + data_size]
 347             if self._two_byte_sequence_length:
 348                 data_size = ((data_size & ~DELAY) << 8) + sequence[i + 2]
 349                 data = sequence[i + 3 : i + 3 + data_size]
 350
 351             self._core.begin_transaction()
 352             self._core.send(
 353                 DISPLAY_COMMAND, CHIP_SELECT_TOGGLE_EVERY_BYTE, bytes([command])
 354             )
 355             self._core.send(
 356                 DISPLAY_DATA,
 357                 CHIP_SELECT_UNTOUCHED,
 358                 data,
 359             )
 360             self._core.end_transaction()
 361             delay_time_ms = 0
 362             if delay:
 363                 data_size += 1
 364                 delay_time_ms = sequence[i + 1 + data_size]
 365                 if delay_time_ms == 255:
 366                     delay_time_ms = 500
 367             time.sleep(delay_time_ms / 1000)
 368             if should_wait_for_busy:
 369                 self._wait_for_busy()
 370             i += 2 + data_size
 371             if self._two_byte_sequence_length:
 372                 i += 1
 373
 374     def _start_refresh(self) -> None:
 375         # Run start sequence
 376         self._core._bus_reset()  # pylint: disable=protected-access
 377         time.sleep(self._start_up_time)
 378         self._send_command_sequence(True, self._start_sequence)
 379         self._core.start_refresh()
 380
 381     def _finish_refresh(self) -> None:
 382         self._send_command_sequence(False, self._refesh_sequence)
 383         self._refreshing = True
 384         self._core.finish_refresh()
 385
 386     def _wait_for_busy(self) -> None:
 387         if self._busy is not None:
 388             while self._busy.value != self._busy_state:
 389                 time.sleep(0.001)
 390
 391     @property
 392     def rotation(self) -> int:
 393         """The rotation of the display as an int in degrees"""
 394         return self._core.rotation
 395
 396     @rotation.setter
 397     def rotation(self, value: int) -> None:
 398         if value % 90 != 0:
 399             raise ValueError("Display rotation must be in 90 degree increments")
 400         transposed = self._core.rotation in (90, 270)
 401         will_transposed = value in (90, 270)
 402         if transposed != will_transposed:
 403             self._core.width, self._core.height = self._core.height, self._core.width
 404         self._core.set_rotation(value)
 405
 406     @property
 407     def time_to_refresh(self) -> float:
 408         """Time, in fractional seconds, until the ePaper display can be refreshed."""
 409         if self._core.last_refresh == 0:
 410             return 0
 411
 412         # Refresh at seconds per frame rate
 413         elapsed_time = time.monotonic() * 1000 - self._core.last_refresh
 414         if elapsed_time > self._milliseconds_per_frame:
 415             return 0
 416         return self._milliseconds_per_frame - elapsed_time
 417
 418     @property
 419     def busy(self) -> bool:
 420         """True when the display is refreshing. This uses the ``busy_pin`` when available or the
 421         ``refresh_time`` otherwise."""
 422         return self._refreshing
 423
 424     @property
 425     def width(self) -> int:
 426         """Display Width"""
 427         return self._core.width
 428
 429     @property
 430     def height(self) -> int:
 431         """Display Height"""
 432         return self._core.height
 433
 434     @property
 435     def bus(self) -> _DisplayBus:
 436         """Current Display Bus"""
 437         return self._core._bus  # pylint: disable=protected-access
 438
 439     @property
 440     def root_group(self) -> Group:
 441         """The root group on the epaper display.
 442         If the root group is set to ``None``, no output will be shown.
 443         """
 444         return self._core.root_group
 445
 446     @root_group.setter
 447     def root_group(self, new_group: Group) -> None:
 448         self._core.root_group = new_group