Cleanup and clarification in doc strings.

Author: ilikecake

examples/i2c_expanders_simpletest.py

@@ -3,9 +3,13 @@
 #
 # SPDX-License-Identifier: Unlicense
 
+# Make sure to change the code based on the expander type you are using.
+
 import time
 import board
 import digitalio
+
+# Change this if you are not using a PCAL9555
 from i2c_expanders.PCAL9555 import PCAL9555
 
 # To use default I2C bus (most boards)
@@ -15,6 +19,7 @@
 PCAL9555_Address = 0x20
 
 # Initialize the device and get pins
+# Change this if you are not using a PCAL9555
 IOEXP1_dev = PCAL9555.PCAL9555(i2c, address=PCAL9555_Address)
 pin0 = IOEXP1_dev.get_pin(0)
 pin1 = IOEXP1_dev.get_pin(1)

i2c_expanders/PCA9554.py

@@ -26,19 +26,21 @@
 Use this class if you are using a PCA9554 or compatible expander. This class is also used
 as the base class for the PCAL9554 expander.
 
-There are likely other devices that use this same command set and can be used with this class.
-Where I find them, I will probably make a separate class name to make it obvious what devices are
-supported. A list of other devices that should be compatible is below.
+Required library files (.py or their .mpy equivalent):
+
+* PCA9554.py
+* i2c_expander.py
+* digital_inout.py
+* helpers.py
 
 Compatible Devices
 
 * PCA9554
 * PCA9538
-* TODO
 
-Note: Some devices have the same command set and register, but different i2c addresses and register
-defaults. These devices should work fine with this class, but make sure the addresses are set right
-when initializing them.
+These are devices I have specifically tested and know work. There appear to be a lot more devices
+with similar naming schemes that use the same register map. These should also be compatible, but
+make sure you check the i2c address and default register state.
 
 Heavily based on the code written by Tony DiCola for the MCP230xx library.
 
@@ -63,8 +65,8 @@
 
 
 class PCA9554(I2c_Expander):
-    """Supports PCA9554 instance on specified I2C bus and optionally
-    at the specified I2C address.
+    """The class for the PCA9554 expander. Instantiate one of these for each expander on the bus.
+    Make sure you get the address right.
     """
 
     def __init__(self, i2c, address=_PCA9554_DEFAULT_ADDRESS, reset=True):

i2c_expanders/PCA9555.py

@@ -25,40 +25,37 @@
 Use this class if you are using a PCA9555 or compatible expander. This class is also used
 as the base class for the PCAL9555 expander.
 
-There are likely other devices that use this same command set and can be used with this class.
-Where I find them, I will probably make a separate class name to make it obvious what devices are
-supported. A list of other devices that should be compatible is below.
+Required library files (.py or their .mpy equivalent):
+
+* PCA9555.py
+* i2c_expander.py
+* digital_inout.py
+* helpers.py
 
 Compatible Devices
 
 * PCA9555
-* TODO
+
+These are devices I have specifically tested and know work. There appear to be a lot more devices
+with similar naming schemes that use the same register map. These should also be compatible, but
+make sure you check the i2c address and default register state.
 
 Heavily based on the code written by Tony DiCola for the MCP230xx library.
 
 * Author(s): Pat Satyshur
 """
 
-# DriveMode: PUSH_PULL vs OPEN_DRAIN
-# Pull: Pull.Up vs Pull.DOWN vs None
-# TODO: Handle interrupts in here somewhere
+from micropython import const
 
-from micropython import (
-    const,
-)  # TODO: What does const get me in this situation? Can I remove it?
 from i2c_expanders.i2c_expander import I2c_Expander
 from i2c_expanders.helpers import _enable_bit, Capability
 
-# from i2c_expanders.digital_inout import _enable_bit
-
 __version__ = "0.0.0+auto.0"
 __repo__ = "https://github.com/ilikecake/CircuitPython_I2C_Expanders.git"
 
-# TODO: this will probably change based on the device used.
-# Not sure how to deal with this. Maybe remove the default and
-# force the user to specify the address?
+# This is the default address for the PCA9555 with all addr pins grounded.
+_PCA9555_DEFAULT_ADDRESS = const(0x20)
 
-_PCA9555_ADDRESS = const(0x20)
 _PCA9555_INPUT0 = const(0x00)  # Input register 0
 _PCA9555_INPUT1 = const(0x01)  # Input register 1
 _PCA9555_OUTPUT0 = const(0x02)  # Output register 0
@@ -70,11 +67,11 @@
 
 
 class PCA9555(I2c_Expander):
-    """Supports PCA9555 instance on specified I2C bus and optionally
-    at the specified I2C address.
+    """The class for the PCA9555 expander. Instantiate one of these for each expander on the bus.
+    Make sure you get the address right.
     """
 
-    def __init__(self, i2c, address=_PCA9555_ADDRESS, reset=True):
+    def __init__(self, i2c, address=_PCA9555_DEFAULT_ADDRESS, reset=True):
         super().__init__(i2c, address)
         self._maxpins = 15
         self._capability = _enable_bit(0x00, Capability.INVERT_POL)

i2c_expanders/PCAL9554.py

@@ -26,19 +26,22 @@
 * Latching interrupt option
 * Per bank push-pull/open drain pin setup.
 
-There are likely other devices that use this same command set and can be used with this class.
-Where I find them, I will probably make a separate class name to make it obvious what devices are
-supported. A list of other devices that should be compatible is below.
+Required library files (.py or their .mpy equivalent):
+
+* PCAL9554.py
+* PCA9554.py
+* i2c_expander.py
+* digital_inout.py
+* helpers.py
 
 Compatible Devices
 
 * PCAL9554
 * PCAL9538
-* TODO
 
-Note: Some devices have the same command set and register, but different i2c addresses and register
-defaults. These devices should work fine with this class, but make sure the addresses are set right
-when initializing them.
+These are devices I have specifically tested and know work. There appear to be a lot more devices
+with similar naming schemes that use the same register map. These should also be compatible, but
+make sure you check the i2c address and default register state.
 
 :Note: By default if an (non-latched) interrupt enabled pin changes state, but changes back before
        the GPIO state register is read, the interrupt state will be cleared. Setting the interrupt
@@ -61,21 +64,17 @@
 # are still unused.
 # pylint: disable=unused-import
 from micropython import const
-import digitalio  # import DigitalInOut	#TODO: Do i need this??
+import digitalio
 
 from i2c_expanders.PCA9554 import PCA9554
-from i2c_expanders.helpers import (
-    Capability,
-    _get_bit,
-    _enable_bit,
-    _clear_bit,
-)
+from i2c_expanders.helpers import Capability, _get_bit, _enable_bit, _clear_bit
+
 
 __version__ = "0.0.0+auto.0"
 __repo__ = "https://github.com/ilikecake/CircuitPython_I2C_Expanders.git"
 
-# TODO: Probably don't want this here.
-_PCAL9554_ADDRESS = const(0x27)
+# This is the default address for the PCA9554 with all addr pins grounded.
+_PCAL9554_DEFAULT_ADDRESS = const(0x20)
 
 _PCAL9554_OUTPUT_DRIVE_1 = const(0x40)
 _PCAL9554_OUTPUT_DRIVE_2 = const(0x41)
@@ -88,11 +87,11 @@
 
 
 class PCAL9554(PCA9554):
-    """Supports PCAL9554 instance on specified I2C bus and optionally
-    at the specified I2C address.
+    """The class for the PCAL9554 expander. Instantiate one of these for each expander on the bus.
+    Make sure you get the address right.
     """
 
-    def __init__(self, i2c, address=_PCAL9554_ADDRESS, reset=True):
+    def __init__(self, i2c, address=_PCAL9554_DEFAULT_ADDRESS, reset=True):
         super().__init__(
             i2c, address, False
         )  # This initializes the PCA9554 compatible registers.

i2c_expanders/PCAL9555.py

@@ -28,9 +28,21 @@
 * Latching interrupt option
 * Per bank push-pull/open drain pin setup.
 
-There are likely other devices that use this same command set and can be used with this class.
-Where I find them, I will probably make a separate class name to make it obvious what devices are
-supported. A list of other devices that should be compatible is below.
+Required library files (.py or their .mpy equivalent):
+
+* PCAL9555.py
+* PCA9555.py
+* i2c_expander.py
+* digital_inout.py
+* helpers.py
+
+Compatible Devices
+
+* PCAL9555
+
+These are devices I have specifically tested and know work. There appear to be a lot more devices
+with similar naming schemes that use the same register map. These should also be compatible, but
+make sure you check the i2c address and default register state.
 
 :Note: By default if an (non-latched) interrupt enabled pin changes state, but changes back before
        the GPIO state register is read, the interrupt state will be cleared. Setting the interrupt
@@ -44,18 +56,6 @@
        the input register is read before the pin state changes back to the original value, both
        state changes will cause an interrupt.
 
-Required library files:
-* PCAL9555.py
-* PCA9555.py
-* i2c_expander.py
-* digital_inout.py
-* helpers.py
-
-Compatible Devices
-
-* PCAL9555
-* TODO
-
 Heavily based on the code written by Tony DiCola for the MCP230xx library.
 
 * Author(s): Pat Satyshur
@@ -70,7 +70,7 @@
 __version__ = "0.0.0+auto.0"
 __repo__ = "https://github.com/ilikecake/CircuitPython_I2C_Expanders.git"
 
-# This is the default address for the PCA9554 with all addr pins grounded.
+# This is the default address for the PCAL9555 with all addr pins grounded.
 _PCAL9555_DEFAULT_ADDRESS = const(0x20)
 
 # Registers specific to the PCAL9555 devices. This device also inherits the registers
@@ -112,8 +112,8 @@ class DriveStrength:  # pylint: disable=too-few-public-methods
 
 
 class PCAL9555(PCA9555):
-    """PACL9555 is a compatible with all PCA9555 functions and definitions. All functions
-    from the PCA9555 work without updates. The PCAL device added capability is defined below.
+    """The class for the PCAL9555 expander. Instantiate one of these for each expander on the bus.
+    Make sure you get the address right.
     """
 
     def __init__(self, i2c, address=_PCAL9555_DEFAULT_ADDRESS, reset=True):

i2c_expanders/digital_inout.py

@@ -24,19 +24,25 @@
 
 class DigitalInOut:
     """The interface is exactly the same as the digitalio.DigitalInOut
-       class. However Some devices do not support pull up/down resistors
-       or setting the pin to open drain.
+    class. However Some devices do not support pull up/down resistors
+    or setting the pin to open drain.
+
+    :param pin_number: The pin number. Starts at zero.
+    :type pin_number: int
+
+    :param ioexpander_class: The I2c expander class object.
+    :type ioexpander_class: gpio class object
 
     Exceptions will be thrown when attempting to set unsupported configurations.
     """
 
     def __init__(self, pin_number, ioexpander_class):
-        """Specify the pin number of the expander and pass the class object.
-        Pin numbers start a 0.
-        """
         self._pin = pin_number
         self._ioexp = ioexpander_class
 
+    # TODO: Not sure if this is still true. Can't we just use the same arguments as the 'real'
+    # DigitalInout class expects, and then not use the ones we don't need? Leaving it along for now.
+    #
     # kwargs in switch functions below are _necessary_ for compatibility
     # with DigitalInout class (which allows specifying pull, etc. which
     # is unused by this class).  Do not remove them, instead turn off pylint

i2c_expanders/helpers.py

@@ -13,6 +13,7 @@
 """
 
 
+# TODO: Look at this later, it does not look right.
 class Capability:  # pylint: disable=too-few-public-methods
     """IO Expander Capability
     A one in the corresponding bit position below indicates

i2c_expanders/i2c_expander.py

@@ -26,11 +26,7 @@
 # pylint: disable=too-few-public-methods
 class I2c_Expander:
     """Base class for I2C GPIO expander devices. This class has basic read and write functions that
-    are common to all i2c expanders. This class should never be used directly
-
-    :param maxpins: Number of pins in the expander. Starts at 0.
-    :type maxpins: interger
-
+    are common to all i2c expanders. This class should never be used directly.
     """
 
     def __init__(self, bus_device, address):