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