Merge pull request #99 from RoaCode/comparator_settings

Added functions for controlling additional comparator settings

Author: tannewt

adafruit_ads1x15/ads1015.py

@@ -20,7 +20,7 @@
     pass
 
 # pylint: disable=unused-import
-from .ads1x15 import ADS1x15, Mode
+from .ads1x15 import ADS1x15
 
 # Data sample rates
 _ADS1015_CONFIG_DR = {

adafruit_ads1x15/ads1115.py

@@ -20,7 +20,7 @@
     pass
 
 # pylint: disable=unused-import
-from .ads1x15 import ADS1x15, Mode
+from .ads1x15 import ADS1x15
 
 # Data sample rates
 _ADS1115_CONFIG_DR = {

adafruit_ads1x15/ads1x15.py

@@ -66,6 +66,42 @@ class Mode:
     """Single-Shot Mode"""
 
 
+class Comp_Mode:
+    """An enum-like class representing possible ADC Comparator operating modes."""
+
+    # See datasheet "Operating Modes" section
+    # values here are masks for setting COMP_MODE bit in Config Register
+    # pylint: disable=too-few-public-methods
+    TRADITIONAL = 0x0000
+    """Traditional Compartor Mode activates above high threshold, de-activates below low"""
+    WINDOW = 0x0010
+    """Window Comparator Mode activates when reading is outside of high and low thresholds"""
+
+
+class Comp_Polarity:
+    """An enum-like class representing possible ADC Comparator polarity modes."""
+
+    # See datasheet "Operating Modes" section
+    # values here are masks for setting COMP_POL bit in Config Register
+    # pylint: disable=too-few-public-methods
+    ACTIVE_LOW = 0x0000
+    """ALERT_RDY pin is LOW when comparator is active"""
+    ACTIVE_HIGH = 0x0008
+    """ALERT_RDY pin is HIGH when comparator is active"""
+
+
+class Comp_Latch:
+    """An enum-like class representing possible ADC Comparator latching modes."""
+
+    # See datasheet "Operating Modes" section
+    # values here are masks for setting COMP_LAT bit in Config Register
+    # pylint: disable=too-few-public-methods
+    NONLATCHING = 0x0000
+    """ALERT_RDY pin does not latch when asserted"""
+    LATCHING = 0x0004
+    """ALERT_RDY pin remains asserted until data is read by controller"""
+
+
 class ADS1x15:
     """Base functionality for ADS1x15 analog to digital converters.
 
@@ -79,10 +115,17 @@ class ADS1x15:
                           Defaults to 0 (comparator function disabled).
     :param int comparator_low_threshold: Voltage limit under which comparator de-asserts
                           ALERT/RDY pin. Must be lower than high threshold to use comparator
-                          function. See subclass for value range and default.
+                          function. Range of -32768 to 32767, default -32768
     :param int comparator_high_threshold: Voltage limit over which comparator asserts
                           ALERT/RDY pin. Must be higher than low threshold to use comparator
-                          function. See subclass for value range and default.
+                          function. Range of -32768 to 32767, default 32767
+    :param Comp_Mode comparator_mode: Configures the comparator as either traditional or window.
+                          Defaults to 'Comp_Mode.TRADITIONAL'
+    :param Comp_Polarity comparator_polarity: Configures the comparator output as either active
+                          low or active high. Defaults to 'Comp_Polarity.ACTIVE_LOW'
+    :param Comp_Latch comparator_latch: Configures the comparator output to only stay asserted while
+                          readings exceed threshold or latch on assertion until data is read.
+                          Defaults to 'Comp_Latch.NONLATCHING'
     :param int address: The I2C address of the device.
     """
 
@@ -96,18 +139,29 @@ def __init__(
         comparator_queue_length: int = 0,
         comparator_low_threshold: int = -32768,
         comparator_high_threshold: int = 32767,
+        comparator_mode: int = Comp_Mode.TRADITIONAL,
+        comparator_polarity: int = Comp_Polarity.ACTIVE_LOW,
+        comparator_latch: int = Comp_Latch.NONLATCHING,
         address: int = _ADS1X15_DEFAULT_ADDRESS,
     ):
         # pylint: disable=too-many-arguments
         self._last_pin_read = None
         self.buf = bytearray(3)
+        self.initialized = (
+            False  # Prevents writing to ADC until all values are initialized
+        )
+        self.i2c_device = I2CDevice(i2c, address)
         self.gain = gain
         self.data_rate = self._data_rate_default() if data_rate is None else data_rate
         self.mode = mode
         self.comparator_queue_length = comparator_queue_length
-        self.i2c_device = I2CDevice(i2c, address)
         self.comparator_low_threshold = comparator_low_threshold
         self.comparator_high_threshold = comparator_high_threshold
+        self.comparator_mode = comparator_mode
+        self.comparator_polarity = comparator_polarity
+        self.comparator_latch = comparator_latch
+        self.initialized = True
+        self._write_config()
 
     @property
     def bits(self) -> int:
@@ -125,6 +179,8 @@ def data_rate(self, rate: int) -> None:
         if rate not in possible_rates:
             raise ValueError("Data rate must be one of: {}".format(possible_rates))
         self._data_rate = rate
+        if self.initialized:
+            self._write_config()
 
     @property
     def rates(self) -> List[int]:
@@ -147,6 +203,8 @@ def gain(self, gain: float) -> None:
         if gain not in possible_gains:
             raise ValueError("Gain must be one of: {}".format(possible_gains))
         self._gain = gain
+        if self.initialized:
+            self._write_config()
 
     @property
     def gains(self) -> List[float]:
@@ -170,6 +228,8 @@ def comparator_queue_length(self, comparator_queue_length: int) -> None:
                 )
             )
         self._comparator_queue_length = comparator_queue_length
+        if self.initialized:
+            self._write_config()
 
     @property
     def comparator_queue_lengths(self) -> List[int]:
@@ -226,14 +286,54 @@ def mode(self, mode: int) -> None:
         if mode not in (Mode.CONTINUOUS, Mode.SINGLE):
             raise ValueError("Unsupported mode.")
         self._mode = mode
+        if self.initialized:
+            self._write_config()
+
+    @property
+    def comparator_mode(self) -> int:
+        """The ADC comparator mode."""
+        return self._comparator_mode
+
+    @comparator_mode.setter
+    def comparator_mode(self, comp_mode: int) -> None:
+        if comp_mode not in (Comp_Mode.TRADITIONAL, Comp_Mode.WINDOW):
+            raise ValueError("Unsupported mode.")
+        self._comparator_mode = comp_mode
+        if self.initialized:
+            self._write_config()
+
+    @property
+    def comparator_polarity(self) -> int:
+        """The ADC comparator polarity mode."""
+        return self._comparator_polarity
+
+    @comparator_polarity.setter
+    def comparator_polarity(self, comp_pol: int) -> None:
+        if comp_pol not in (Comp_Polarity.ACTIVE_LOW, Comp_Polarity.ACTIVE_HIGH):
+            raise ValueError("Unsupported mode.")
+        self._comparator_polarity = comp_pol
+        if self.initialized:
+            self._write_config()
+
+    @property
+    def comparator_latch(self) -> int:
+        """The ADC comparator latching mode."""
+        return self._comparator_latch
 
-    def read(self, pin: Pin, is_differential: bool = False) -> int:
+    @comparator_latch.setter
+    def comparator_latch(self, comp_latch: int) -> None:
+        if comp_latch not in (Comp_Latch.NONLATCHING, Comp_Latch.LATCHING):
+            raise ValueError("Unsupported mode.")
+        self._comparator_latch = comp_latch
+        if self.initialized:
+            self._write_config()
+
+    def read(self, pin: Pin) -> int:
         """I2C Interface for ADS1x15-based ADCs reads.
 
         :param ~microcontroller.Pin pin: individual or differential pin.
         :param bool is_differential: single-ended or differential read.
         """
-        pin = pin if is_differential else pin + 0x04
         return self._read(pin)
 
     def _data_rate_default(self) -> int:
@@ -260,16 +360,7 @@ def _read(self, pin: Pin) -> int:
 
         # Configure ADC every time before a conversion in SINGLE mode
         # or changing channels in CONTINUOUS mode
-        if self.mode == Mode.SINGLE:
-            config = _ADS1X15_CONFIG_OS_SINGLE
-        else:
-            config = 0
-        config |= (pin & 0x07) << _ADS1X15_CONFIG_MUX_OFFSET
-        config |= _ADS1X15_CONFIG_GAIN[self.gain]
-        config |= self.mode
-        config |= self.rate_config[self.data_rate]
-        config |= _ADS1X15_CONFIG_COMP_QUEUE[self.comparator_queue_length]
-        self._write_register(_ADS1X15_POINTER_CONFIG, config)
+        self._write_config(pin)
 
         # Wait for conversion to complete
         # ADS1x1x devices settle within a single conversion cycle
@@ -317,3 +408,60 @@ def _read_register(self, reg: int, fast: bool = False) -> int:
             else:
                 i2c.write_then_readinto(bytearray([reg]), self.buf, in_end=2)
         return self.buf[0] << 8 | self.buf[1]
+
+    def _write_config(self, pin_config: Optional[int] = None) -> None:
+        """Write to configuration register of ADC
+
+        :param int pin_config: setting for MUX value in config register
+        """
+        if pin_config is None:
+            pin_config = (
+                self._read_register(_ADS1X15_POINTER_CONFIG) & 0x7000
+            ) >> _ADS1X15_CONFIG_MUX_OFFSET
+
+        if self.mode == Mode.SINGLE:
+            config = _ADS1X15_CONFIG_OS_SINGLE
+        else:
+            config = 0
+
+        config |= (pin_config & 0x07) << _ADS1X15_CONFIG_MUX_OFFSET
+        config |= _ADS1X15_CONFIG_GAIN[self.gain]
+        config |= self.mode
+        config |= self.rate_config[self.data_rate]
+        config |= self.comparator_mode
+        config |= self.comparator_polarity
+        config |= self.comparator_latch
+        config |= _ADS1X15_CONFIG_COMP_QUEUE[self.comparator_queue_length]
+        self._write_register(_ADS1X15_POINTER_CONFIG, config)
+
+    def _read_config(self) -> None:
+        """Reads Config Register and sets all properties accordingly"""
+        config_value = self._read_register(_ADS1X15_POINTER_CONFIG)
+
+        self.gain = next(
+            key
+            for key, value in _ADS1X15_CONFIG_GAIN.items()
+            if value == (config_value & 0x0E00)
+        )
+        self.data_rate = next(
+            key
+            for key, value in self.rate_config.items()
+            if value == (config_value & 0x00E0)
+        )
+        self.comparator_queue_length = next(
+            key
+            for key, value in _ADS1X15_CONFIG_COMP_QUEUE.items()
+            if value == (config_value & 0x0003)
+        )
+        self.mode = Mode.SINGLE if config_value & 0x0100 else Mode.CONTINUOUS
+        self.comparator_mode = (
+            Comp_Mode.WINDOW if config_value & 0x0010 else Comp_Mode.TRADITIONAL
+        )
+        self.comparator_polarity = (
+            Comp_Polarity.ACTIVE_HIGH
+            if config_value & 0x0008
+            else Comp_Polarity.ACTIVE_LOW
+        )
+        self.comparator_latch = (
+            Comp_Latch.LATCHING if config_value & 0x0004 else Comp_Latch.NONLATCHING
+        )

adafruit_ads1x15/analog_in.py

@@ -55,7 +55,8 @@ def value(self) -> int:
         Even if the underlying analog to digital converter (ADC) is
         lower resolution, the value is 16-bit.
         """
-        return self._ads.read(self._pin_setting, is_differential=self.is_differential)
+        pin = self._pin_setting if self.is_differential else self._pin_setting + 0x04
+        return self._ads.read(pin)
 
     @property
     def voltage(self) -> float:

examples/ads1x15_comparator_example.py

@@ -9,6 +9,7 @@
 import adafruit_ads1x15.ads1015 as ADS
 
 # import adafruit_ads1x15.ads1115 as ADS
+from adafruit_ads1x15.ads1x15 import Mode, Comp_Mode, Comp_Polarity, Comp_Latch
 from adafruit_ads1x15.analog_in import AnalogIn
 
 # Create the I2C bus
@@ -26,9 +27,18 @@
 # Create Interrupt-driven input to track comparator changes
 int_pin = countio.Counter(board.GP9, edge=countio.Edge.RISE)
 
+# Set ADC to continuously read new data
+ads.mode = Mode.CONTINUOUS
 # Set comparator to assert after 1 ADC conversion
 ads.comparator_queue_length = 1
-
+# Set comparator to use traditional threshold instead of window
+ads.comparator_mode = Comp_Mode.TRADITIONAL
+# Set comparator output to de-assert if readings no longer above threshold
+ads.comparator_latch = Comp_Latch.NONLATCHING
+# Set comparator output to logic LOW when asserted
+ads.comparator_polarity = Comp_Polarity.ACTIVE_LOW
+# Gain should be explicitly set to ensure threshold values are calculated correctly
+ads.gain = 1
 # Set comparator low threshold to 2V
 ads.comparator_low_threshold = chan.convert_to_value(2.000)
 # Set comparator high threshold to 2.002V. High threshold must be above low threshold