displayio/_fourwire.py

   1 # SPDX-FileCopyrightText: 2020 Melissa LeBlanc-Williams for Adafruit Industries
   2 #
   3 # SPDX-License-Identifier: MIT
   4
   5 """
   6 `displayio.fourwire`
   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
  22 import digitalio
  23 import busio
  24 import microcontroller
  25 from circuitpython_typing import ReadableBuffer
  26 from ._constants import (
  27     CHIP_SELECT_TOGGLE_EVERY_BYTE,
  28     CHIP_SELECT_UNTOUCHED,
  29     DISPLAY_COMMAND,
  30     DISPLAY_DATA,
  31 )
  32
  33 __version__ = "0.0.0+auto.0"
  34 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  35
  36
  37 class FourWire:
  38     """Manage updating a display over SPI four wire protocol in the background while
  39     Python code runs. It doesn’t handle display initialization.
  40     """
  41
  42     def __init__(
  43         self,
  44         spi_bus: busio.SPI,
  45         *,
  46         command: microcontroller.Pin,
  47         chip_select: microcontroller.Pin,
  48         reset: Optional[microcontroller.Pin] = None,
  49         baudrate: int = 24000000,
  50         polarity: int = 0,
  51         phase: int = 0,
  52     ):
  53         """Create a FourWire object associated with the given pins.
  54
  55         The SPI bus and pins are then in use by the display until
  56         displayio.release_displays() is called even after a reload. (It does this so
  57         CircuitPython can use the display after your code is done.)
  58         So, the first time you initialize a display bus in code.py you should call
  59         :py:func`displayio.release_displays` first, otherwise it will error after the
  60         first code.py run.
  61         """
  62         self._dc = digitalio.DigitalInOut(command)
  63         self._dc.switch_to_output(value=False)
  64         self._chip_select = digitalio.DigitalInOut(chip_select)
  65         self._chip_select.switch_to_output(value=True)
  66         self._frequency = baudrate
  67         self._polarity = polarity
  68         self._phase = phase
  69
  70         if reset is not None:
  71             self._reset = digitalio.DigitalInOut(reset)
  72             self._reset.switch_to_output(value=True)
  73         else:
  74             self._reset = None
  75         self._spi = spi_bus
  76
  77     def _release(self):
  78         self.reset()
  79         self._spi.deinit()
  80         self._dc.deinit()
  81         self._chip_select.deinit()
  82         if self._reset is not None:
  83             self._reset.deinit()
  84
  85     def reset(self) -> None:
  86         """Performs a hardware reset via the reset pin.
  87         Raises an exception if called when no reset pin is available.
  88         """
  89         if self._reset is not None:
  90             self._reset.value = False
  91             time.sleep(0.001)
  92             self._reset.value = True
  93             time.sleep(0.001)
  94
  95     def send(
  96         self,
  97         command,
  98         data: ReadableBuffer,
  99         *,
 100         toggle_every_byte: bool = False,
 101     ) -> None:
 102         """
 103         Sends the given command value followed by the full set of data. Display state,
 104         such as vertical scroll, set via ``send`` may or may not be reset once the code is
 105         done.
 106         """
 107         if not 0 <= command <= 255:
 108             raise ValueError("Command must be an int between 0 and 255")
 109         chip_select = (
 110             CHIP_SELECT_TOGGLE_EVERY_BYTE
 111             if toggle_every_byte
 112             else CHIP_SELECT_UNTOUCHED
 113         )
 114         self._begin_transaction()
 115         self._send(DISPLAY_COMMAND, chip_select, bytes([command]))
 116         self._send(DISPLAY_DATA, chip_select, data)
 117         self._end_transaction()
 118
 119     def _send(
 120         self,
 121         data_type: int,
 122         chip_select: int,
 123         data: ReadableBuffer,
 124     ):
 125         self._dc.value = data_type == DISPLAY_DATA
 126         if chip_select == CHIP_SELECT_TOGGLE_EVERY_BYTE:
 127             for byte in data:
 128                 self._spi.write(bytes([byte]))
 129                 self._chip_select.value = True
 130                 time.sleep(0.000001)
 131                 self._chip_select.value = False
 132         else:
 133             self._spi.write(data)
 134
 135     def _begin_transaction(self) -> bool:
 136         """Begin the SPI transaction by locking, configuring, and setting Chip Select"""
 137         if not self._spi.try_lock():
 138             return False
 139         self._spi.configure(
 140             baudrate=self._frequency, polarity=self._polarity, phase=self._phase
 141         )
 142         self._chip_select.value = False
 143         return True
 144
 145     def _end_transaction(self) -> None:
 146         """End the SPI transaction by unlocking and setting Chip Select"""
 147         self._chip_select.value = True
 148         self._spi.unlock()