Merge pull request #985 from tekktrik/doc/fix-configuration

[Adafruit_Blinka-hackapet.git] / src / bitbangio.py

diff --git a/src/bitbangio.py b/src/bitbangio.py
old mode 100644 (file)
new mode 100755 (executable)
index 0dbeb82..fd0c844
--- a/src/bitbangio.py
+++ b/src/bitbangio.py
@@ -1,18 +1,49 @@
-from adafruit_blinka import Lockable
-from machine import I2C as _I2C
-from machine import Pin
+# SPDX-FileCopyrightText: 2021 Melissa LeBlanc-Williams for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`bitbangio` - Bitbanged bus protocols
+==============================================================
+
+See `CircuitPython:bitbangio` in CircuitPython for more details.
+
+* Author(s): cefn
+"""
+
+import adafruit_platformdetect.constants.boards as ap_board
+from adafruit_blinka import Lockable, agnostic
+
+# pylint: disable=import-outside-toplevel,too-many-arguments

 
 
 class I2C(Lockable):
 
 
 class I2C(Lockable):

+    """Bitbang/Software I2C implementation"""
+

     def __init__(self, scl, sda, frequency=400000):
     def __init__(self, scl, sda, frequency=400000):

+        # TODO: This one is a bit questionable:
+        if agnostic.board_id == ap_board.PYBOARD:
+            raise NotImplementedError("No software I2C on {}".format(agnostic.board_id))
+        if agnostic.detector.board.any_embedded_linux:
+            # TODO: Attempt to load this library automatically
+            raise NotImplementedError(
+                "For bitbangio on Linux, please use Adafruit_CircuitPython_BitbangIO"
+            )

         self.init(scl, sda, frequency)
 
     def init(self, scl, sda, frequency):
         self.init(scl, sda, frequency)
 
     def init(self, scl, sda, frequency):

+        """Initialization"""
+        from machine import Pin
+        from machine import I2C as _I2C
+

         self.deinit()
         self.deinit()

-        id = -1 # force bitbanging implementation - in future introspect platform if SDA/SCL matches hardware I2C
+        id = (  # pylint: disable=redefined-builtin
+            -1
+        )  # force bitbanging implementation - in future
+        # introspect platform if SDA/SCL matches hardware I2C

         self._i2c = _I2C(id, Pin(scl.id), Pin(sda.id), freq=frequency)
 
     def deinit(self):
         self._i2c = _I2C(id, Pin(scl.id), Pin(sda.id), freq=frequency)
 
     def deinit(self):

+        """Deinitialization"""

         try:
             del self._i2c
         except AttributeError:
         try:
             del self._i2c
         except AttributeError:


@@ -25,42 +56,73 @@ class I2C(Lockable):
         self.deinit()
 
     def scan(self):
         self.deinit()
 
     def scan(self):

+        """Scan for attached devices"""

         return self._i2c.scan()
 
     def readfrom_into(self, address, buffer, start=0, end=None):
         return self._i2c.scan()
 
     def readfrom_into(self, address, buffer, start=0, end=None):

-        if start is not 0 or end is not None:
+        """Read from a device at specified address into a buffer"""
+        if start != 0 or end is not None:

             if end is None:
                 end = len(buffer)
             buffer = memoryview(buffer)[start:end]
             if end is None:
                 end = len(buffer)
             buffer = memoryview(buffer)[start:end]

-        stop = True # remove for efficiency later
+        stop = True  # remove for efficiency later

         return self._i2c.readfrom_into(address, buffer, stop)
 
         return self._i2c.readfrom_into(address, buffer, stop)
 

-    def writeto(self, address, buffer, start=0, end=None, stop=True, *a, **k):
-        if start is not 0 or end is not None:
+    def writeto(self, address, buffer, start=0, end=None, stop=True):
+        """Write to a device at specified address from a buffer"""
+        if start != 0 or end is not None:

             if end is None:
             if end is None:

-                end = len(buffer)
-            buffer = memoryview(buffer)[start:end]
+                return self._i2c.writeto(address, memoryview(buffer)[start:], stop)
+            return self._i2c.writeto(address, memoryview(buffer)[start:end], stop)

         return self._i2c.writeto(address, buffer, stop)
 
         return self._i2c.writeto(address, buffer, stop)
 

-# TODO untested, as actually busio.SPI was on tasklist https://github.com/adafruit/Adafruit_Micropython_Blinka/issues/2 :(
+
+# TODO untested, as actually busio.SPI was on
+# tasklist https://github.com/adafruit/Adafruit_Micropython_Blinka/issues/2 :(

 class SPI(Lockable):
 class SPI(Lockable):

+    """Bitbang/Software SPI implementation"""
+

     def __init__(self, clock, MOSI=None, MISO=None):
     def __init__(self, clock, MOSI=None, MISO=None):

-        self._spi = SPI(-1)
-        self._pins = (clock.id, MOSI.id, MISO.id)
+        if agnostic.detector.board.any_embedded_linux:
+            # TODO: Attempt to load this library automatically
+            raise NotImplementedError(
+                "For bitbangio on Linux, please use Adafruit_CircuitPython_BitbangIO"
+            )
+        from machine import SPI as _SPI
+
+        self._spi = _SPI(-1)
+        self._pins = (clock, MOSI, MISO)

 
     def configure(self, baudrate=100000, polarity=0, phase=0, bits=8):
 
     def configure(self, baudrate=100000, polarity=0, phase=0, bits=8):

+        """Update the configuration"""
+        from machine import Pin
+        from machine import SPI as _SPI
+

         if self._locked:
         if self._locked:

-            # TODO verify if _spi obj 'caches' sck, mosi, miso to avoid storing in _attributeIds (duplicated in busio)
+            # TODO verify if _spi obj 'caches' sck, mosi, miso to
+            # avoid storing in _attributeIds (duplicated in busio)

             # i.e. #init ignores MOSI=None rather than unsetting
             # i.e. #init ignores MOSI=None rather than unsetting

-            self._spi.init(baudrate=baudrate, polarity=polarity, phase=phase, bits = bits, firstbit = SPI.MSB, sck = Pin(self._pins[0]), mosi=Pin(self._pins[1]), miso=Pin(self._pins[2]))
+            self._spi.init(
+                baudrate=baudrate,
+                polarity=polarity,
+                phase=phase,
+                bits=bits,
+                firstbit=_SPI.MSB,
+                sck=Pin(self._pins[0].id),
+                mosi=Pin(self._pins[1].id),
+                miso=Pin(self._pins[2].id),
+            )

         else:
             raise RuntimeError("First call try_lock()")
 
     def write(self, buf):
         else:
             raise RuntimeError("First call try_lock()")
 
     def write(self, buf):

+        """Write to the SPI device"""

         return self._spi.write(buf)
 
     def readinto(self, buf):
         return self._spi.write(buf)
 
     def readinto(self, buf):

+        """Read from the SPI device into a buffer"""

         return self.readinto(buf)
 
     def write_readinto(self, buffer_out, buffer_in):
         return self.readinto(buf)
 
     def write_readinto(self, buffer_out, buffer_in):

+        """Write to the SPI device and read from the SPI device into a buffer"""

         return self.write_readinto(buffer_out, buffer_in)
         return self.write_readinto(buffer_out, buffer_in)