adding_example_improving_docs

README.rst

@@ -13,6 +13,11 @@ Introduction
     :target: https://github.com/adafruit/Adafruit_CircuitPython_TCA9548A/actions/
     :alt: Build Status
 
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+    :alt: Code Style: Black
+
+
 CircuitPython driver for the TCA9548A I2C Multiplexer.
 
 Dependencies
@@ -56,28 +61,22 @@ Usage Example
 
 .. code-block :: python
 
-    # This example shows using two TSL2491 light sensors attached to TCA9548A channels 0 and 1.
-    # Use with other I2C sensors would be similar.
-    import time
+    # This example shows using TCA9548A to perform a simple scan for connected devices
     import board
-    import busio
-    import adafruit_tsl2591
     import adafruit_tca9548a
 
     # Create I2C bus as normal
-    i2c = busio.I2C(board.SCL, board.SDA)
+    i2c = board.I2C()  # uses board.SCL and board.SDA
 
     # Create the TCA9548A object and give it the I2C bus
     tca = adafruit_tca9548a.TCA9548A(i2c)
 
-    # For each sensor, create it using the TCA9548A channel instead of the I2C object
-    tsl1 = adafruit_tsl2591.TSL2591(tca[0])
-    tsl2 = adafruit_tsl2591.TSL2591(tca[1])
-
-    # Loop and profit!
-    while True:
-        print(tsl1.lux, tsl2.lux)
-        time.sleep(0.1)
+    for channel in range(8):
+        if tca[channel].try_lock():
+            print("Channel {}:".format(channel), end="")
+            addresses = tca[channel].scan()
+            print([hex(address) for address in addresses if address != 0x70])
+            tca[channel].unlock()
 
 
 Contributing

adafruit_tca9548a.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 """
-``Adafruit_TCA9548A``
+`adafruit_tca9548a`
 ====================================================
 
 CircuitPython driver for the TCA9548A I2C Multiplexer.
@@ -15,16 +15,20 @@
 
 **Hardware:**
 
-* TCA9548A I2C Multiplexer: https://www.adafruit.com/product/2717
+* `TCA9548A I2C Multiplexer
+  <https://www.adafruit.com/product/2717>`_ (Product ID: 2717)
+
 
 **Software and Dependencies:**
 
 * Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+  https://circuitpython.org/downloads
+
+* Adafruit's Bus Device library:
+  https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+
 """
 
-# imports
 from micropython import const
 
 _DEFAULT_ADDRESS = const(0x70)
@@ -43,31 +47,31 @@ def __init__(self, tca, channel):
         self.channel_switch = bytearray([1 << channel])
 
     def try_lock(self):
-        """Pass thru for try_lock."""
+        """Pass through for try_lock."""
         while not self.tca.i2c.try_lock():
             pass
         self.tca.i2c.writeto(self.tca.address, self.channel_switch)
         return True
 
     def unlock(self):
-        """Pass thru for unlock."""
+        """Pass through for unlock."""
         self.tca.i2c.writeto(self.tca.address, b"\x00")
         return self.tca.i2c.unlock()
 
     def readfrom_into(self, address, buffer, **kwargs):
-        """Pass thru for readfrom_into."""
+        """Pass through for readfrom_into."""
         if address == self.tca.address:
             raise ValueError("Device address must be different than TCA9548A address.")
         return self.tca.i2c.readfrom_into(address, buffer, **kwargs)
 
     def writeto(self, address, buffer, **kwargs):
-        """Pass thru for writeto."""
+        """Pass through for writeto."""
         if address == self.tca.address:
             raise ValueError("Device address must be different than TCA9548A address.")
         return self.tca.i2c.writeto(address, buffer, **kwargs)
 
     def writeto_then_readfrom(self, address, buffer_out, buffer_in, **kwargs):
-        """Pass thru for writeto_then_readfrom."""
+        """Pass through for writeto_then_readfrom."""
         # In linux, at least, this is a special kernel function call
         if address == self.tca.address:
             raise ValueError("Device address must be different than TCA9548A address.")
@@ -93,7 +97,7 @@ def __len__(self):
 
     def __getitem__(self, key):
         if not 0 <= key <= 7:
-            raise IndexError("Channel must be an integer in the range: 0-7")
+            raise IndexError("Channel must be an integer in the range: 0-7.")
         if self.channels[key] is None:
             self.channels[key] = TCA9548A_Channel(self, key)
         return self.channels[key]

docs/api.rst

@@ -6,3 +6,4 @@
 
 .. automodule:: adafruit_tca9548a
    :members:
+   :member-order: bysource

docs/conf.py

@@ -34,10 +34,6 @@
         "https://circuitpython.readthedocs.io/projects/busdevice/en/latest/",
         None,
     ),
-    "Register": (
-        "https://circuitpython.readthedocs.io/projects/register/en/latest/",
-        None,
-    ),
     "CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None),
 }
 

docs/examples.rst

@@ -6,3 +6,12 @@ Ensure your device works with this simple test.
 .. literalinclude:: ../examples/tca9548a_simpletest.py
     :caption: examples/tca9548a_simpletest.py
     :linenos:
+
+Multisensor test
+----------------
+
+Shows how to use the I2C Multiplexer with two sensors
+
+.. literalinclude:: ../examples/tca9548a_multisensor.py
+    :caption: examples/tca9548a_multisensor.py
+    :linenos:

docs/index.rst

@@ -23,6 +23,8 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    TCA9548A I2C Multiplexer Learning Guide <https://learn.adafruit.com/adafruit-tca9548a-1-to-8-i2c-multiplexer-breakout/overview>
+
 .. toctree::
     :caption: Related Products
 

examples/tca9548a_multisensor.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
+# SPDX-License-Identifier: MIT
+
+# This example shows using two TSL2491 light sensors attached to TCA9548A channels 0 and 1.
+# Use with other I2C sensors would be similar.
+import time
+import board
+import adafruit_tsl2591
+import adafruit_tca9548a
+
+# Create I2C bus as normal
+i2c = board.I2C()  # uses board.SCL and board.SDA
+
+# Create the TCA9548A object and give it the I2C bus
+tca = adafruit_tca9548a.TCA9548A(i2c)
+
+# For each sensor, create it using the TCA9548A channel instead of the I2C object
+tsl1 = adafruit_tsl2591.TSL2591(tca[0])
+tsl2 = adafruit_tsl2591.TSL2591(tca[1])
+
+# After initial setup, can just use sensors as normal.
+while True:
+    print(tsl1.lux, tsl2.lux)
+    time.sleep(0.1)

examples/tca9548a_simpletest.py

@@ -1,25 +1,19 @@
-# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
+# SPDX-FileCopyrightText: 2021 Carter Nelson for Adafruit Industries
 # SPDX-License-Identifier: MIT
 
-# This example shows using two TSL2491 light sensors attached to TCA9548A channels 0 and 1.
-# Use with other I2C sensors would be similar.
-import time
+# This example shows using TCA9548A to perform a simple scan for connected devices
 import board
-import busio
-import adafruit_tsl2591
 import adafruit_tca9548a
 
 # Create I2C bus as normal
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 
 # Create the TCA9548A object and give it the I2C bus
 tca = adafruit_tca9548a.TCA9548A(i2c)
 
-# For each sensor, create it using the TCA9548A channel instead of the I2C object
-tsl1 = adafruit_tsl2591.TSL2591(tca[0])
-tsl2 = adafruit_tsl2591.TSL2591(tca[1])
-
-# After initial setup, can just use sensors as normal.
-while True:
-    print(tsl1.lux, tsl2.lux)
-    time.sleep(0.1)
+for channel in range(8):
+    if tca[channel].try_lock():
+        print("Channel {}:".format(channel), end="")
+        addresses = tca[channel].scan()
+        print([hex(address) for address in addresses if address != 0x70])
+        tca[channel].unlock()

requirements.txt

@@ -3,3 +3,4 @@
 # SPDX-License-Identifier: Unlicense
 
 Adafruit-Blinka
+adafruit-circuitpython-busdevice

setup.py

@@ -34,7 +34,10 @@
     # Author details
     author="Adafruit Industries",
     author_email="[email protected]",
-    install_requires=["Adafruit-Blinka"],
+    install_requires=[
+        "Adafruit-Blinka",
+        "adafruit-circuitpython-busdevice",
+    ],
     # Choose your license
     license="MIT",
     # See https://pypi.python.org/pypi?%3Aaction=list_classifiers