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