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 import _typing
  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, command, data: _typing.ReadableBuffer, *, toggle_every_byte: bool = False
  97     ) -> None:
  98         """
  99         Sends the given command value followed by the full set of data. Display state,
 100         such as vertical scroll, set via ``send`` may or may not be reset once the code is
 101         done.
 102         """
 103         if not 0 <= command <= 255:
 104             raise ValueError("Command must be an int between 0 and 255")
 105         chip_select = (
 106             CHIP_SELECT_TOGGLE_EVERY_BYTE
 107             if toggle_every_byte
 108             else CHIP_SELECT_UNTOUCHED
 109         )
 110         self._begin_transaction()
 111         self._send(DISPLAY_COMMAND, chip_select, command)
 112         self._send(DISPLAY_DATA, chip_select, data)
 113         self._end_transaction()
 114
 115     def _send(self, data_type: int, chip_select: int, data: _typing.ReadableBuffer):
 116         self._dc.value = data_type == DISPLAY_DATA
 117         if chip_select == CHIP_SELECT_TOGGLE_EVERY_BYTE:
 118             for byte in data:
 119                 self._spi.write(bytes([byte]))
 120                 self._chip_select.value = True
 121                 time.sleep(0.000001)
 122                 self._chip_select.value = False
 123         else:
 124             self._spi.write(data)
 125
 126     def _begin_transaction(self):
 127         """Begin the SPI transaction by locking, configuring, and setting Chip Select"""
 128         while not self._spi.try_lock():
 129             pass
 130         self._spi.configure(
 131             baudrate=self._frequency, polarity=self._polarity, phase=self._phase
 132         )
 133         self._chip_select.value = False
 134
 135     def _end_transaction(self):
 136         """End the SPI transaction by unlocking and setting Chip Select"""
 137         self._chip_select.value = True
 138         self._spi.unlock()