Fix comments for better documentation

Author: ilikecake

i2c_expanders/PCA9554.py

@@ -36,23 +36,25 @@
 * 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.
+
 Heavily based on the code written by Tony DiCola for the MCP230xx library.
 
 * Author(s): Pat Satyshur
 """
 
 # TODO: Fix these imports.
-from micropython import (
-    const,
-)  # TODO: What does const get me in this situation? Can I remove it?
+from micropython import const
 from i2c_expanders.i2c_expander import I2c_Expander
 from i2c_expanders.helpers import _enable_bit, Capability
 
 __version__ = "0.0.0+auto.0"
 __repo__ = "https://github.com/ilikecake/CircuitPython_I2C_Expanders.git"
 
-# TODO: probably don't want this here.
-_PCA9554_ADDRESS = const(0x27)
+# This is the default address for the PCA9554 with all addr pins grounded.
+_PCA9554_DEFAULT_ADDRESS = const(0x20)
 
 _PCA9554_INPUT = const(0x00)  # Input register
 _PCA9554_OUTPUT = const(0x01)  # Output register
@@ -65,10 +67,10 @@ class PCA9554(I2c_Expander):
     at the specified I2C address.
     """
 
-    def __init__(self, i2c, address=_PCA9554_ADDRESS, reset=True):
+    def __init__(self, i2c, address=_PCA9554_DEFAULT_ADDRESS, reset=True):
         super().__init__(i2c, address)
-        self.maxpins = 7
-        self.capability = _enable_bit(0x00, Capability.INVERT_POL)
+        self._maxpins = 7
+        self._capability = _enable_bit(0x00, Capability.INVERT_POL)
         if reset:
             self.reset_to_defaults()
 
@@ -78,44 +80,51 @@ def reset_to_defaults(self):
 
         :return:        Nothing.
         """
-        # TODO: Should I make some sort of 'register' class to
-        # handle memory addresses and default states?
         # Input port register is read only.
         self.gpio = 0xFF
         self.ipol = 0x00
         self.iodir = 0xFF
 
     @property
     def gpio(self):
-        """The raw GPIO output register.  Each bit represents the
-        output value of the associated pin (0 = low, 1 = high), assuming that
-        pin has been configured as an output previously.
+        """The raw GPIO port registers.  Each bit represents the value of the associated pin
+        (0 = low, 1 = high). Read this register to get the value of all pins. Write to this
+        register to set the value of any pins configured as outputs.
+        Read and written as a 8 bit number.
+
+        Register address (read):  0x00
+
+        Register address (write): 0x01
         """
         return self._read_u8(_PCA9554_INPUT)
 
     @gpio.setter
     def gpio(self, val):
         self._write_u8(_PCA9554_OUTPUT, val)
 
-    @property
-    def iodir(self):
-        """The raw IODIR direction register.  Each bit represents
-        direction of a pin, either 1 for an input or 0 for an output mode.
-        """
-        return self._read_u8(_PCA9554_IODIR)
-
-    @iodir.setter
-    def iodir(self, val):
-        self._write_u8(_PCA9554_IODIR, val)
-
     @property
     def ipol(self):
-        """The raw IPOL output register.  Each bit represents the
-        polarity value of the associated pin (0 = normal, 1 = inverted), assuming that
-        pin has been configured as an input previously.
+        """The raw 'polarity inversion' register. Each bit represents the polarity value of the
+        associated pin (0 = normal, 1 = inverted). This only applies to pins configured as inputs.
+        Read and written as a 8 bit number.
+
+        Register address: 0x02
         """
         return self._read_u8(_PCA9554_IPOL)
 
     @ipol.setter
     def ipol(self, val):
         self._write_u8(_PCA9554_IPOL, val)
+
+    @property
+    def iodir(self):
+        """The raw pin configuration register. Each bit represents direction of a pin, either 1
+        for an input or 0 for an output. Read and written as a 8 bit number.
+
+        Register address: 0x03
+        """
+        return self._read_u8(_PCA9554_IODIR)
+
+    @iodir.setter
+    def iodir(self, val):
+        self._write_u8(_PCA9554_IODIR, val)

i2c_expanders/PCA9555.py

@@ -76,55 +76,61 @@ class PCA9555(I2c_Expander):
 
     def __init__(self, i2c, address=_PCA9555_ADDRESS, reset=True):
         super().__init__(i2c, address)
-        self.maxpins = 15
-        self.capability = _enable_bit(0x00, Capability.INVERT_POL)
+        self._maxpins = 15
+        self._capability = _enable_bit(0x00, Capability.INVERT_POL)
         if reset:
             self.reset_to_defaults()
 
-    @property
-    def gpio(self):
-        """The raw GPIO output register.  Each bit represents the
-        output value of the associated pin (0 = low, 1 = high), assuming that
-        pin has been configured as an output previously.
-        """
-        return self._read_u16le(_PCA9555_INPUT0)
-
-    @gpio.setter
-    def gpio(self, val):
-        self._write_u16le(_PCA9555_OUTPUT0, val)
-
-    @property
-    def iodir(self):
-        """The raw IODIR direction register.  Each bit represents
-        direction of a pin, either 1 for an input or 0 for an output mode.
-        """
-        return self._read_u16le(_PCA9555_IODIR0)
-
-    @iodir.setter
-    def iodir(self, val):
-        self._write_u16le(_PCA9555_IODIR0, val)
-
     def reset_to_defaults(self):
         """Reset all registers to their default state. This is also
         done with a power cycle, but it can be called by software here.
 
         :return:        Nothing.
         """
-        # TODO: Should I make some sort of 'register' class to
-        # handle memory addresses and default states?
-        # Input port register is read only.
         self.gpio = 0xFFFF
         self.ipol = 0x0000
         self.iodir = 0xFFFF
 
+    @property
+    def gpio(self):
+        """The raw GPIO port registers.  Each bit represents the value of the associated pin
+        (0 = low, 1 = high). Read this register to get the value of all pins. Write to this
+        register to set the value of any pins configured as outputs.
+        Read and written as a 16 bit number.
+
+        Register address (read):  0x00, 0x01
+
+        Register address (write): 0x02, 0x03
+        """
+        return self._read_u16le(_PCA9555_INPUT0)
+
+    @gpio.setter
+    def gpio(self, val):
+        self._write_u16le(_PCA9555_OUTPUT0, val)
+
     @property
     def ipol(self):
-        """The raw IPOL output register.  Each bit represents the
-        polarity value of the associated pin (0 = normal, 1 = inverted), assuming that
-        pin has been configured as an input previously.
+        """The raw 'polarity inversion' register. Each bit represents the polarity value of the
+        associated pin (0 = normal, 1 = inverted). This only applies to pins configured as inputs.
+        Read and written as a 16 bit number.
+
+        Register address: 0x04, 0x05
         """
         return self._read_u16le(_PCA9555_IPOL0)
 
     @ipol.setter
     def ipol(self, val):
         self._write_u16le(_PCA9555_IPOL0, val)
+
+    @property
+    def iodir(self):
+        """The raw pin configuration register. Each bit represents direction of a pin, either 1
+        for an input or 0 for an output. Read and written as a 16 bit number.
+
+        Register address: 0x06, 0x07
+        """
+        return self._read_u16le(_PCA9555_IODIR0)
+
+    @iodir.setter
+    def iodir(self, val):
+        self._write_u16le(_PCA9555_IODIR0, val)

i2c_expanders/PCAL9554.py

@@ -36,6 +36,22 @@
 * 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.
+
+: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
+       latch will cause the device to latch on a state change of the input pin. With latching
+       enabled, on a state change to the pin, the interrupt pin will be asserted and will not
+       deassert until the input register is read. The value read from the input register will be
+       the value that caused the interrupt, not nessecarially the current value of the pin. If the
+       pin changed state, but changed back before the input register was read, the changed state
+       will be what is returned in the register. The state change back to the original state will
+       not trigger another interrupt as long as it happens before the input register is read. If
+       the input register is read before the pin state changes back to the original value, both
+       state changes will cause an interrupt.
+
 Heavily based on the code written by Tony DiCola for the MCP230xx library.
 
 * Author(s): Pat Satyshur
@@ -80,12 +96,12 @@ def __init__(self, i2c, address=_PCAL9554_ADDRESS, reset=True):
         super().__init__(
             i2c, address, False
         )  # This initializes the PCA9554 compatible registers.
-        self.capability = (
+        self._capability = (
             _enable_bit(0x00, Capability.PULL_UP)
             | _enable_bit(0x00, Capability.PULL_DOWN)
             | _enable_bit(0x00, Capability.INVERT_POL)
-        )  # TODO: This device does not really have a capability to set drive mode the way
-        # digitalio is expecting. I should probably not set this here.
+        )
+
         if reset:
             self.reset_to_defaults()
 
@@ -118,6 +134,26 @@ def clear_int_pin(self, pin):
         self._validate_pin(pin)
         self.irq_mask = _enable_bit(self.irq_mask, pin)
 
+    def get_interrupts(self):
+        """Returns a list of pins causing an interruptn along with the value of those pins.
+        It is possible for multiple pins to be causing an interrupt. Calling this function
+        clears the interrupt state.
+
+        :return:        Returns a list of dicts containing items "pin" and "value". If no
+                        interrupts are triggered, this function returns none.
+        """
+        output = []
+        int_status = self.irq_status
+        pin_values = self.gpio
+
+        for i in range(self.maxpins):
+            if bool((int_status >> i) & 1):
+                pin_val = bool(((pin_values >> i) & 1))
+                output.append({"pin": i, "value": pin_val})
+        if not output:
+            return None
+        return output
+
     def get_int_pins(self):
         """Returns a list of pins causing an interrupt. It is possible for multiple pins
         to be causing an interrupt. Calling this function will not clear the interrupt state.
@@ -151,16 +187,6 @@ def clear_int_latch(self, pin):
         self._validate_pin(pin)
         self.input_latch = _clear_bit(self.input_latch, pin)
 
-    """Interrupt latch behavior
-        By default (non-latched) if an interrupt enabled pin changes state, but changes back before the GPIO state register is read, the interrupt state
-        will be cleared. Setting the interrupt latch will cause the device to latch on a state change of the input pin. With latching enabled, on a state
-        change to the pin, the interrupt pin will be asserted and will not deassert until the input register is read. The value read from the input register
-        will be the value that caused the interrupt, not nessecarially the current value of the pin. If the pin changed state, but changed back before the
-        input register was read, the changed state will be what is returned in the register. The state change back to the original state will not trigger
-        another interrupt as long as it happens before the input register is read. If the input register is read before the pin state changes back to the
-        original value, both state changes will cause an interrupt.
-    """
-
     def get_pupd(self, pin):
         """Checks the state of a pin to see if pull up/down is enabled.
 
@@ -292,7 +318,11 @@ def reset_to_defaults(self):
 
     @property
     def out_drive(self):
-        """Output drive strength of pins 0-7."""
+        """The raw 'output drive strength' register. Controls the drive strength of the pins.
+        Read and written as a 16 bit number.
+
+        Register address: 0x40, 0x41.
+        """
         return self._read_u16le(_PCAL9554_OUTPUT_DRIVE_1)
 
     @out_drive.setter
@@ -301,7 +331,12 @@ def out_drive(self, val):
 
     @property
     def input_latch(self):
-        """Sets latching or non-latching interrupts per pin."""
+        """The raw 'input latch' register. Each bit represents the latch configuration for the
+        matching pin. A zero indicates that the corresponding input pin is not latched. Read and
+        written as a 8 bit number.
+
+        Register address: 0x42.
+        """
         return self._read_u8(_PCAL9554_INPUT_LATCH)
 
     @input_latch.setter
@@ -310,7 +345,14 @@ def input_latch(self, val):
 
     @property
     def pupd_en(self):
-        """reads the pull up/down status"""
+        """The raw 'pull-up/pull-down enable' register. Each bit represents the enabled state of
+        the pull up/down resistors for that pin. A one indicates that the pull up/down resistors
+        are enabled. The selection of pull-up vs pull-down is done with the 'pull-up/pull-down
+        selection register'. A zero indicates that the pull up/down resistors are disconnected.
+        Read and written as a 8 bit number.
+
+        Register address: 0x43.
+        """
         return self._read_u8(_PCAL9554_PUPD_EN)
 
     @pupd_en.setter
@@ -319,7 +361,13 @@ def pupd_en(self, val):
 
     @property
     def pupd_sel(self):
-        """reads the pull up/down status"""
+        """The raw 'pull-up/pull-down selection' register. Each bit enables either a pull-up or
+        pull-down resistor on that corresponding pin. A one selects a pull-up and a zero selects a
+        pull-down. Internal pull up/down resistors are ~100 KOhm  (+/-50 KOhm). Read and written as
+        a 8 bit number.
+
+        Register address: 0x44.
+        """
         return self._read_u8(_PCAL9554_PUPD_SEL)
 
     @pupd_sel.setter
@@ -328,7 +376,12 @@ def pupd_sel(self, val):
 
     @property
     def irq_mask(self):
-        """Masks or unmasks pins for generating interrupts."""
+        """The raw 'interrupt mask' register. Setting a bit to one will mask interrupts on that
+        corresponding pin. All interrupts are masked by default. Read and written as a 8 bit
+        number.
+
+        Register address: 0x45.
+        """
         return self._read_u8(_PCAL9554_IRQ_MASK)
 
     @irq_mask.setter
@@ -337,7 +390,13 @@ def irq_mask(self, val):
 
     @property
     def irq_status(self):
-        """Indicates which pin caused an interrupt."""
+        """The raw 'interrupt status' register. Reading this register will tell the source of an
+        interrupt. A one read from a bit in this register indicates that the corresponding pin
+        caused the interrupt. This register is read only. Reading from this register does not clear
+        the interrupt state. Read and written as a 8 bit number.
+
+        Register address: 0x46.
+        """
         return self._read_u8(_PCAL9554_IRQ_STATUS)
 
     @irq_status.setter
@@ -347,9 +406,15 @@ def irq_status(self, val):
 
     @property
     def out_port_config(self):
-        """Sets output banks to open drain or push-pull operation."""
+        """The raw 'output port configuration' register. Use bit zero of this register to set the
+        output pins to either open-drain or push-pull operation. Set the bit to zero to configure
+        the pins as push-pull. Set to one to configure the pins as open-drain. All other bits are
+        reserved. Read and written as a 8 bit number.
+
+        Register address: 0x4F.
+        """
         return self._read_u8(_PCAL9554_OUTPUT_PORT_CONFIG)
 
     @out_port_config.setter
     def out_port_config(self, val):
-        self._write_u8(_PCAL9554_OUTPUT_PORT_CONFIG, val)
+        self._write_u8((_PCAL9554_OUTPUT_PORT_CONFIG & 0x01), val)