displayio/_i2cdisplay.py

   1 # SPDX-FileCopyrightText: 2020 Melissa LeBlanc-Williams for Adafruit Industries
   2 # SPDX-FileCopyrightText: 2020 Erik Tollerud
   3 # SPDX-FileCopyrightText: 2021 Jim Morris
   4 # SPDX-FileCopyrightText: 2021 James Carr
   5 #
   6 # SPDX-License-Identifier: MIT
   7
   8 """
   9 `displayio.i2cdisplay`
  10 ================================================================================
  11
  12 displayio for Blinka
  13
  14 **Software and Dependencies:**
  15
  16 * Adafruit Blinka:
  17   https://github.com/adafruit/Adafruit_Blinka/releases
  18
  19 * Author(s): Melissa LeBlanc-Williams, Erik Tollerud, James Carr
  20
  21 """
  22
  23 import time
  24 import busio
  25 import digitalio
  26 from circuitpython_typing import ReadableBuffer
  27 from ._constants import CHIP_SELECT_UNTOUCHED, DISPLAY_COMMAND
  28
  29 __version__ = "0.0.0+auto.0"
  30 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  31
  32
  33 class I2CDisplay:
  34     """Manage updating a display over I2C in the background while Python code runs.
  35     It doesn’t handle display initialization.
  36     """
  37
  38     def __init__(self, i2c_bus: busio.I2C, *, device_address: int, reset=None):
  39         """Create a I2CDisplay object associated with the given I2C bus and reset pin.
  40
  41         The I2C bus and pins are then in use by the display until displayio.release_displays() is
  42         called even after a reload. (It does this so CircuitPython can use the display after your
  43         code is done.) So, the first time you initialize a display bus in code.py you should call
  44         :py:func`displayio.release_displays` first, otherwise it will error after the first
  45         code.py run.
  46         """
  47
  48         if reset is not None:
  49             self._reset = digitalio.DigitalInOut(reset)
  50             self._reset.switch_to_output(value=True)
  51         else:
  52             self._reset = None
  53         self._i2c = i2c_bus
  54         self._dev_addr = device_address
  55
  56     def __new__(cls, *args, **kwargs):
  57         from . import (  # pylint: disable=import-outside-toplevel, cyclic-import
  58             allocate_display_bus,
  59         )
  60
  61         display_bus_instance = super().__new__(cls)
  62         allocate_display_bus(display_bus_instance)
  63         return display_bus_instance
  64
  65     def _release(self):
  66         self.reset()
  67         self._i2c.deinit()
  68         if self._reset is not None:
  69             self._reset.deinit()
  70
  71     def reset(self) -> None:
  72         """
  73         Performs a hardware reset via the reset pin if one is present.
  74         """
  75
  76         if self._reset is None:
  77             return
  78
  79         self._reset.value = False
  80         time.sleep(0.0001)
  81         self._reset.value = True
  82
  83     def _begin_transaction(self) -> bool:
  84         """Lock the bus before sending data."""
  85         return self._i2c.try_lock()
  86
  87     def send(self, command: int, data: ReadableBuffer) -> None:
  88         """
  89         Sends the given command value followed by the full set of data. Display state,
  90         such as vertical scroll, set via ``send`` may or may not be reset once the code is
  91         done.
  92         """
  93         self._begin_transaction()
  94         self._send(DISPLAY_COMMAND, CHIP_SELECT_UNTOUCHED, bytes([command] + data))
  95         self._end_transaction()
  96
  97     def _send(
  98         self,
  99         data_type: int,
 100         _chip_select: int,  # Chip select behavior
 101         data: ReadableBuffer,
 102     ):
 103         if data_type == DISPLAY_COMMAND:
 104             n = len(data)
 105             if n > 0:
 106                 command_bytes = bytearray(n * 2)
 107                 for i in range(n):
 108                     command_bytes[2 * i] = 0x80
 109                     command_bytes[2 * i + 1] = data[i]
 110
 111             try:
 112                 self._i2c.writeto(self._dev_addr, buffer=command_bytes)
 113             except OSError as error:
 114                 if error.errno == 121:
 115                     raise RuntimeError(
 116                         f"I2C write error to 0x{self._dev_addr:02x}"
 117                     ) from error
 118                 raise error
 119         else:
 120             data_bytes = bytearray(len(data) + 1)
 121             data_bytes[0] = 0x40
 122             data_bytes[1:] = data
 123             try:
 124                 self._i2c.writeto(self._dev_addr, buffer=data_bytes)
 125             except OSError as error:
 126                 if error.errno == 121:
 127                     raise RuntimeError(
 128                         f"I2C write error to 0x{self._dev_addr:02x}"
 129                     ) from error
 130                 raise error
 131
 132     def _end_transaction(self) -> None:
 133         """Release the bus after sending data."""
 134         self._i2c.unlock()