src/busio.py

   1 # SPDX-FileCopyrightText: 2021 Melissa LeBlanc-Williams for Adafruit Industries
   2 #
   3 # SPDX-License-Identifier: MIT
   4 """
   5 `busio` - Bus protocol support like I2C and SPI
   6 =================================================
   7
   8 See `CircuitPython:busio` in CircuitPython for more details.
   9
  10 * Author(s): cefn
  11 """
  12
  13 try:
  14     import threading
  15 except ImportError:
  16     threading = None
  17
  18 # pylint: disable=unused-import
  19 import adafruit_platformdetect.constants.boards as ap_board
  20 import adafruit_platformdetect.constants.chips as ap_chip
  21 from adafruit_blinka import Enum, Lockable, agnostic
  22 from adafruit_blinka.agnostic import board_id, detector
  23
  24 # pylint: disable=import-outside-toplevel,too-many-branches,too-many-statements
  25 # pylint: disable=too-many-arguments,too-many-function-args,too-many-return-statements
  26
  27
  28 class I2C(Lockable):
  29     """
  30     Busio I2C Class for CircuitPython Compatibility. Used
  31     for both MicroPython and Linux.
  32     """
  33
  34     def __init__(self, scl, sda, frequency=100000):
  35         self.init(scl, sda, frequency)
  36
  37     def init(self, scl, sda, frequency):
  38         """Initialization"""
  39         self.deinit()
  40         if detector.board.ftdi_ft232h:
  41             from adafruit_blinka.microcontroller.ftdi_mpsse.mpsse.i2c import I2C as _I2C
  42
  43             self._i2c = _I2C(frequency=frequency)
  44             return
  45         if detector.board.binho_nova:
  46             from adafruit_blinka.microcontroller.nova.i2c import I2C as _I2C
  47
  48             self._i2c = _I2C(frequency=frequency)
  49             return
  50         if detector.board.microchip_mcp2221:
  51             from adafruit_blinka.microcontroller.mcp2221.i2c import I2C as _I2C
  52
  53             self._i2c = _I2C(frequency=frequency)
  54             return
  55         if detector.board.greatfet_one:
  56             from adafruit_blinka.microcontroller.nxp_lpc4330.i2c import I2C as _I2C
  57
  58             self._i2c = _I2C(frequency=frequency)
  59             return
  60         if detector.board.pico_u2if:
  61             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import I2C_Pico as _I2C
  62
  63             self._i2c = _I2C(scl, sda, frequency=frequency)
  64             return
  65         if detector.board.feather_u2if:
  66             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import (
  67                 I2C_Feather as _I2C,
  68             )
  69
  70             self._i2c = _I2C(scl, sda, frequency=frequency)
  71             return
  72         if detector.board.feather_epd_u2if:
  73             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import (
  74                 I2C_Feather_EPD as _I2C,
  75             )
  76
  77             self._i2c = _I2C(scl, sda, frequency=frequency)
  78             return
  79         if detector.board.qtpy_u2if:
  80             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import I2C_QTPY as _I2C
  81
  82             self._i2c = _I2C(scl, sda, frequency=frequency)
  83             return
  84         if detector.board.itsybitsy_u2if:
  85             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import (
  86                 I2C_ItsyBitsy as _I2C,
  87             )
  88
  89             self._i2c = _I2C(scl, sda, frequency=frequency)
  90             return
  91         if detector.board.macropad_u2if:
  92             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import (
  93                 I2C_MacroPad as _I2C,
  94             )
  95
  96             self._i2c = _I2C(scl, sda, frequency=frequency)
  97             return
  98         if detector.board.qt2040_trinkey_u2if:
  99             from adafruit_blinka.microcontroller.rp2040_u2if.i2c import (
 100                 I2C_QT2040_Trinkey as _I2C,
 101             )
 102
 103             self._i2c = _I2C(scl, sda, frequency=frequency)
 104             return
 105         if detector.chip.id == ap_chip.RP2040:
 106             from adafruit_blinka.microcontroller.rp2040.i2c import I2C as _I2C
 107
 108             self._i2c = _I2C(scl, sda, frequency=frequency)
 109             return
 110         if detector.board.any_siemens_iot2000:
 111             from adafruit_blinka.microcontroller.am65xx.i2c import I2C as _I2C
 112
 113             self._i2c = _I2C(frequency=frequency)
 114             return
 115
 116         if detector.board.any_embedded_linux:
 117             from adafruit_blinka.microcontroller.generic_linux.i2c import I2C as _I2C
 118         elif detector.board.ftdi_ft2232h:
 119             from adafruit_blinka.microcontroller.ftdi_mpsse.mpsse.i2c import I2C as _I2C
 120         else:
 121             from adafruit_blinka.microcontroller.generic_micropython.i2c import (
 122                 I2C as _I2C,
 123             )
 124         from microcontroller.pin import i2cPorts
 125
 126         for portId, portScl, portSda in i2cPorts:
 127             try:
 128                 # pylint: disable=unexpected-keyword-arg
 129                 if scl == portScl and sda == portSda:
 130                     self._i2c = _I2C(portId, mode=_I2C.MASTER, baudrate=frequency)
 131                     break
 132                 # pylint: enable=unexpected-keyword-arg
 133             except RuntimeError:
 134                 pass
 135         else:
 136             raise ValueError(
 137                 "No Hardware I2C on (scl,sda)={}\nValid I2C ports: {}".format(
 138                     (scl, sda), i2cPorts
 139                 )
 140             )
 141         if threading is not None:
 142             self._lock = threading.RLock()
 143
 144     def deinit(self):
 145         """Deinitialization"""
 146         try:
 147             del self._i2c
 148         except AttributeError:
 149             pass
 150
 151     def __enter__(self):
 152         if threading is not None:
 153             self._lock.acquire()
 154         return self
 155
 156     def __exit__(self, exc_type, exc_value, traceback):
 157         if threading is not None:
 158             self._lock.release()
 159         self.deinit()
 160
 161     def scan(self):
 162         """Scan for attached devices"""
 163         return self._i2c.scan()
 164
 165     def readfrom_into(self, address, buffer, *, start=0, end=None):
 166         """Read from a device at specified address into a buffer"""
 167         if start != 0 or end is not None:
 168             if end is None:
 169                 end = len(buffer)
 170             buffer = memoryview(buffer)[start:end]
 171         stop = True  # remove for efficiency later
 172         return self._i2c.readfrom_into(address, buffer, stop=stop)
 173
 174     def writeto(self, address, buffer, *, start=0, end=None, stop=True):
 175         """Write to a device at specified address from a buffer"""
 176         if isinstance(buffer, str):
 177             buffer = bytes([ord(x) for x in buffer])
 178         if start != 0 or end is not None:
 179             if end is None:
 180                 return self._i2c.writeto(address, memoryview(buffer)[start:], stop=stop)
 181             return self._i2c.writeto(address, memoryview(buffer)[start:end], stop=stop)
 182         return self._i2c.writeto(address, buffer, stop=stop)
 183
 184     def writeto_then_readfrom(
 185         self,
 186         address,
 187         buffer_out,
 188         buffer_in,
 189         *,
 190         out_start=0,
 191         out_end=None,
 192         in_start=0,
 193         in_end=None,
 194         stop=False,
 195     ):
 196         """ "Write to a device at specified address from a buffer then read
 197         from a device at specified address into a buffer
 198         """
 199         return self._i2c.writeto_then_readfrom(
 200             address,
 201             buffer_out,
 202             buffer_in,
 203             out_start=out_start,
 204             out_end=out_end,
 205             in_start=in_start,
 206             in_end=in_end,
 207             stop=stop,
 208         )
 209
 210
 211 class SPI(Lockable):
 212     """
 213     Busio SPI Class for CircuitPython Compatibility. Used
 214     for both MicroPython and Linux.
 215     """
 216
 217     def __init__(self, clock, MOSI=None, MISO=None):
 218         self.deinit()
 219         if detector.board.ftdi_ft232h:
 220             from adafruit_blinka.microcontroller.ftdi_mpsse.mpsse.spi import SPI as _SPI
 221             from adafruit_blinka.microcontroller.ftdi_mpsse.ft232h.pin import (
 222                 SCK,
 223                 MOSI,
 224                 MISO,
 225             )
 226
 227             self._spi = _SPI()
 228             self._pins = (SCK, MOSI, MISO)
 229             return
 230         if detector.board.binho_nova:
 231             from adafruit_blinka.microcontroller.nova.spi import SPI as _SPI
 232             from adafruit_blinka.microcontroller.nova.pin import SCK, MOSI, MISO
 233
 234             self._spi = _SPI(clock)
 235             self._pins = (SCK, MOSI, MISO)
 236             return
 237         if detector.board.greatfet_one:
 238             from adafruit_blinka.microcontroller.nxp_lpc4330.spi import SPI as _SPI
 239             from adafruit_blinka.microcontroller.nxp_lpc4330.pin import SCK, MOSI, MISO
 240
 241             self._spi = _SPI()
 242             self._pins = (SCK, MOSI, MISO)
 243             return
 244         if detector.board.pico_u2if:
 245             from adafruit_blinka.microcontroller.rp2040_u2if.spi import SPI_Pico as _SPI
 246
 247             self._spi = _SPI(clock)  # this is really all that's needed
 248             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 249             return
 250         if detector.board.feather_u2if:
 251             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 252                 SPI_Feather as _SPI,
 253             )
 254
 255             self._spi = _SPI(clock)  # this is really all that's needed
 256             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 257             return
 258         if detector.board.feather_epd_u2if:
 259             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 260                 SPI_Feather_EPD as _SPI,
 261             )
 262
 263             self._spi = _SPI(clock)  # this is really all that's needed
 264             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 265             return
 266         if detector.board.itsybitsy_u2if:
 267             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 268                 SPI_ItsyBitsy as _SPI,
 269             )
 270
 271             self._spi = _SPI(clock)  # this is really all that's needed
 272             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 273             return
 274         if detector.board.macropad_u2if:
 275             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 276                 SPI_MacroPad as _SPI,
 277             )
 278
 279             self._spi = _SPI(clock)  # this is really all that's needed
 280             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 281             return
 282         if detector.board.qtpy_u2if:
 283             from adafruit_blinka.microcontroller.rp2040_u2if.spi import SPI_QTPY as _SPI
 284
 285             self._spi = _SPI(clock)  # this is really all that's needed
 286             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 287             return
 288         if detector.chip.id == ap_chip.RP2040:
 289             from adafruit_blinka.microcontroller.rp2040.spi import SPI as _SPI
 290
 291             self._spi = _SPI(clock, MOSI, MISO)  # Pins configured on instantiation
 292             self._pins = (clock, clock, clock)  # These don't matter, they're discarded
 293             return
 294         if detector.board.any_siemens_iot2000:
 295             from adafruit_blinka.microcontroller.am65xx.spi import SPI as _SPI
 296
 297             self._spi = _SPI(clock)  # this is really all that's needed
 298             self._pins = (clock, clock, clock)  # will determine MOSI/MISO from clock
 299             return
 300         if detector.board.any_embedded_linux:
 301             from adafruit_blinka.microcontroller.generic_linux.spi import SPI as _SPI
 302         elif detector.board.ftdi_ft2232h:
 303             from adafruit_blinka.microcontroller.ftdi_mpsse.mpsse.spi import SPI as _SPI
 304         else:
 305             from adafruit_blinka.microcontroller.generic_micropython.spi import (
 306                 SPI as _SPI,
 307             )
 308         from microcontroller.pin import spiPorts
 309
 310         for portId, portSck, portMosi, portMiso in spiPorts:
 311             if (
 312                 (clock == portSck)
 313                 and MOSI in (portMosi, None)  # Clock is required!
 314                 and MISO in (portMiso, None)  # But can do with just output
 315             ):  # Or just input
 316                 self._spi = _SPI(portId)
 317                 self._pins = (portSck, portMosi, portMiso)
 318                 break
 319         else:
 320             raise ValueError(
 321                 "No Hardware SPI on (SCLK, MOSI, MISO)={}\nValid SPI ports:{}".format(
 322                     (clock, MOSI, MISO), spiPorts
 323                 )
 324             )
 325
 326     def configure(self, baudrate=100000, polarity=0, phase=0, bits=8):
 327         """Update the configuration"""
 328         if detector.board.any_nanopi and detector.chip.id == ap_chip.SUN8I:
 329             from adafruit_blinka.microcontroller.generic_linux.spi import SPI as _SPI
 330         elif detector.board.ftdi_ft232h:
 331             from adafruit_blinka.microcontroller.ftdi_mpsse.mpsse.spi import (
 332                 SPI as _SPI,
 333             )
 334         elif detector.board.ftdi_ft2232h:
 335             from adafruit_blinka.microcontroller.ftdi_mpsse.mpsse.spi import (
 336                 SPI as _SPI,
 337             )
 338         elif detector.board.binho_nova:
 339             from adafruit_blinka.microcontroller.nova.spi import SPI as _SPI
 340         elif detector.board.greatfet_one:
 341             from adafruit_blinka.microcontroller.nxp_lpc4330.spi import SPI as _SPI
 342         elif detector.board.any_lubancat and detector.chip.id == ap_chip.IMX6ULL:
 343             from adafruit_blinka.microcontroller.generic_linux.spi import SPI as _SPI
 344         elif detector.board.pico_u2if:
 345             from adafruit_blinka.microcontroller.rp2040_u2if.spi import SPI_Pico as _SPI
 346         elif detector.board.feather_u2if:
 347             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 348                 SPI_Feather as _SPI,
 349             )
 350         elif detector.board.feather_epd_u2if:
 351             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 352                 SPI_Feather_EPD as _SPI,
 353             )
 354         elif detector.board.itsybitsy_u2if:
 355             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 356                 SPI_ItsyBitsy as _SPI,
 357             )
 358         elif detector.board.macropad_u2if:
 359             from adafruit_blinka.microcontroller.rp2040_u2if.spi import (
 360                 SPI_MacroPad as _SPI,
 361             )
 362         elif detector.board.qtpy_u2if:
 363             from adafruit_blinka.microcontroller.rp2040_u2if.spi import SPI_QTPY as _SPI
 364         elif detector.chip.id == ap_chip.RP2040:
 365             from adafruit_blinka.microcontroller.rp2040.spi import SPI as _SPI
 366         elif detector.board.any_siemens_iot2000:
 367             from adafruit_blinka.microcontroller.am65xx.spi import SPI as _SPI
 368             from adafruit_blinka.microcontroller.am65xx.pin import Pin
 369         elif detector.board.any_embedded_linux:
 370             from adafruit_blinka.microcontroller.generic_linux.spi import SPI as _SPI
 371         else:
 372             from adafruit_blinka.microcontroller.generic_micropython.spi import (
 373                 SPI as _SPI,
 374             )
 375
 376         if self._locked:
 377             # TODO check if #init ignores MOSI=None rather than unsetting, to save _pinIds attribute
 378             self._spi.init(
 379                 baudrate=baudrate,
 380                 polarity=polarity,
 381                 phase=phase,
 382                 bits=bits,
 383                 firstbit=_SPI.MSB,
 384             )
 385         else:
 386             raise RuntimeError("First call try_lock()")
 387
 388     def deinit(self):
 389         """Deinitialization"""
 390         self._spi = None
 391         self._pinIds = None
 392
 393     @property
 394     def frequency(self):
 395         """Return the baud rate if implemented"""
 396         try:
 397             return self._spi.frequency
 398         except AttributeError as error:
 399             raise NotImplementedError(
 400                 "Frequency attribute not implemented for this platform"
 401             ) from error
 402
 403     def write(self, buf, start=0, end=None):
 404         """Write to the SPI device"""
 405         return self._spi.write(buf, start, end)
 406
 407     def readinto(self, buf, start=0, end=None, write_value=0):
 408         """Read from the SPI device into a buffer"""
 409         return self._spi.readinto(buf, start, end, write_value=write_value)
 410
 411     def write_readinto(
 412         self, buffer_out, buffer_in, out_start=0, out_end=None, in_start=0, in_end=None
 413     ):
 414         """Write to the SPI device and read from the SPI device into a buffer"""
 415         return self._spi.write_readinto(
 416             buffer_out, buffer_in, out_start, out_end, in_start, in_end
 417         )
 418
 419
 420 class UART(Lockable):
 421     """
 422     Busio UART Class for CircuitPython Compatibility. Used
 423     for MicroPython and a few other non-Linux boards.
 424     """
 425
 426     class Parity(Enum):
 427         """Parity Enumeration"""
 428
 429         pass  # pylint: disable=unnecessary-pass
 430
 431     Parity.ODD = Parity()
 432     Parity.EVEN = Parity()
 433
 434     def __init__(
 435         self,
 436         tx,
 437         rx,
 438         baudrate=9600,
 439         bits=8,
 440         parity=None,
 441         stop=1,
 442         timeout=1000,
 443         receiver_buffer_size=64,
 444         flow=None,
 445     ):
 446         if detector.board.any_embedded_linux:
 447             raise RuntimeError(
 448                 "busio.UART not supported on this platform. Please use pyserial instead."
 449             )
 450         if detector.board.binho_nova:
 451             from adafruit_blinka.microcontroller.nova.uart import UART as _UART
 452         elif detector.board.greatfet_one:
 453             from adafruit_blinka.microcontroller.nxp_lpc4330.uart import UART as _UART
 454         elif detector.chip.id == ap_chip.RP2040:
 455             from adafruit_blinka.microcontroller.rp2040.uart import UART as _UART
 456         else:
 457             from machine import UART as _UART
 458
 459         from microcontroller.pin import uartPorts
 460
 461         self.baudrate = baudrate
 462
 463         if flow is not None:  # default 0
 464             raise NotImplementedError(
 465                 "Parameter '{}' unsupported on {}".format("flow", agnostic.board_id)
 466             )
 467
 468         # translate parity flag for Micropython
 469         if parity is UART.Parity.ODD:
 470             parity = 1
 471         elif parity is UART.Parity.EVEN:
 472             parity = 0
 473         elif parity is None:
 474             pass
 475         else:
 476             raise ValueError("Invalid parity")
 477
 478         if detector.chip.id == ap_chip.RP2040:
 479             self._uart = _UART(
 480                 tx,
 481                 rx,
 482                 baudrate=baudrate,
 483                 bits=bits,
 484                 parity=parity,
 485                 stop=stop,
 486             )
 487         else:
 488             # check tx and rx have hardware support
 489             for portId, portTx, portRx in uartPorts:  #
 490                 if portTx == tx and portRx == rx:
 491                     self._uart = _UART(
 492                         portId,
 493                         baudrate,
 494                         bits=bits,
 495                         parity=parity,
 496                         stop=stop,
 497                         timeout=timeout,
 498                         read_buf_len=receiver_buffer_size,
 499                     )
 500                     break
 501             else:
 502                 raise ValueError(
 503                     "No Hardware UART on (tx,rx)={}\nValid UART ports: {}".format(
 504                         (tx, rx), uartPorts
 505                     )
 506                 )
 507
 508     def deinit(self):
 509         """Deinitialization"""
 510         if detector.board.binho_nova:
 511             self._uart.deinit()
 512         self._uart = None
 513
 514     def read(self, nbytes=None):
 515         """Read from the UART"""
 516         return self._uart.read(nbytes)
 517
 518     def readinto(self, buf, nbytes=None):
 519         """Read from the UART into a buffer"""
 520         return self._uart.readinto(buf, nbytes)
 521
 522     def readline(self):
 523         """Read a line of characters up to a newline character from the UART"""
 524         return self._uart.readline()
 525
 526     def write(self, buf):
 527         """Write to the UART from a buffer"""
 528         return self._uart.write(buf)