fourwire/__init__.py

   1 # SPDX-FileCopyrightText: 2020 Melissa LeBlanc-Williams for Adafruit Industries
   2 #
   3 # SPDX-License-Identifier: MIT
   4
   5 """
   6 `fourwire`
   7 ================================================================================
   8
   9 fourwire 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 displayio._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: Optional[microcontroller.Pin] = None,
  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
  65         if chip_select is not None:
  66             self._chip_select = digitalio.DigitalInOut(chip_select)
  67             self._chip_select.switch_to_output(value=True)
  68         else:
  69             self._chip_select = None
  70
  71         self._frequency = baudrate
  72         self._polarity = polarity
  73         self._phase = phase
  74
  75         if reset is not None:
  76             self._reset = digitalio.DigitalInOut(reset)
  77             self._reset.switch_to_output(value=True)
  78             self.reset()
  79         else:
  80             self._reset = None
  81         self._spi = spi_bus
  82
  83     def _release(self):
  84         self.reset()
  85         self._spi.deinit()
  86         self._dc.deinit()
  87
  88         if self._chip_select is not None:
  89             self._chip_select.deinit()
  90
  91         if self._reset is not None:
  92             self._reset.deinit()
  93
  94     def reset(self) -> None:
  95         """Performs a hardware reset via the reset pin.
  96         Raises an exception if called when no reset pin is available.
  97         """
  98         if self._reset is not None:
  99             self._reset.value = False
 100             time.sleep(0.001)
 101             self._reset.value = True
 102             time.sleep(0.001)
 103
 104     def send(
 105         self,
 106         command,
 107         data: ReadableBuffer,
 108         *,
 109         toggle_every_byte: bool = False,
 110     ) -> None:
 111         """
 112         Sends the given command value followed by the full set of data. Display state,
 113         such as vertical scroll, set via ``send`` may or may not be reset once the code is
 114         done.
 115         """
 116         if not 0 <= command <= 255:
 117             raise ValueError("Command must be an int between 0 and 255")
 118         chip_select = (
 119             CHIP_SELECT_TOGGLE_EVERY_BYTE
 120             if toggle_every_byte
 121             else CHIP_SELECT_UNTOUCHED
 122         )
 123         self._begin_transaction()
 124         self._send(DISPLAY_COMMAND, chip_select, bytes([command]))
 125         self._send(DISPLAY_DATA, chip_select, data)
 126         self._end_transaction()
 127
 128     def _send(
 129         self,
 130         data_type: int,
 131         chip_select: int,
 132         data: ReadableBuffer,
 133     ):
 134         self._dc.value = data_type == DISPLAY_DATA
 135
 136         if (
 137             self._chip_select is not None
 138             and chip_select == CHIP_SELECT_TOGGLE_EVERY_BYTE
 139         ):
 140             for byte in data:
 141                 self._spi.write(bytes([byte]))
 142                 self._chip_select.value = True
 143                 time.sleep(0.000001)
 144                 self._chip_select.value = False
 145         else:
 146             self._spi.write(data)
 147
 148     def _free(self) -> bool:
 149         """Attempt to free the bus and return False if busy"""
 150         if not self._spi.try_lock():
 151             return False
 152         self._spi.unlock()
 153         return True
 154
 155     def _begin_transaction(self) -> bool:
 156         """Begin the SPI transaction by locking, configuring, and setting Chip Select"""
 157         if not self._spi.try_lock():
 158             return False
 159         self._spi.configure(
 160             baudrate=self._frequency, polarity=self._polarity, phase=self._phase
 161         )
 162
 163         if self._chip_select is not None:
 164             self._chip_select.value = False
 165
 166         return True
 167
 168     def _end_transaction(self) -> None:
 169         """End the SPI transaction by unlocking and setting Chip Select"""
 170         if self._chip_select is not None:
 171             self._chip_select.value = True
 172
 173         self._spi.unlock()