feat: implement continuous conversion mode (#9)

* feat: add support for the ADS101x family of chips

Author: feeph

examples/01_singleshot.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+perform a single-shot measurement
+
+In single-shot mode, the ADC performs one conversion of the input signal
+upon request, stores the conversion value to an internal conversion
+register, and then enters a power-down state. This mode is intended to
+provide significant power savings in systems that only require periodic
+conversions or when there are long idle periods between conversions.
+
+This example works with all variations:
+ - ADS1013, ADS1014, ADS1015
+ - ADS1113, ADS1114, ADS1115
+
+usage:
+  pdm run examples/01_singleshot.py
+"""
+
+import time
+
+import board  # type: ignore
+
+# module busio and board provide no type hints
+import busio  # type: ignore
+
+from feeph.ads1xxx import DRS, UNIT, Ads1113, Ads1113Config
+
+if __name__ == '__main__':
+    i2c_bus = busio.I2C(scl=board.SCL, sda=board.SDA)
+    ads1x13 = Ads1113(i2c_bus=i2c_bus)
+
+    # create a configuration
+    #   Without any parameters provided this will match the default
+    #   configuration for this device.
+    my_config = Ads1113Config()
+
+    # take our first measurement
+    #   It is recommended to provide a configuration at least once in order
+    #   to ensure the device uses the expected configuration.
+    value1 = ads1x13.get_ssc_measurement(config=my_config)
+    print("value1: {value1}µV")
+
+    # take a second measurement
+    #   if no configuration is provided we continue to use the previous one
+    value2 = ads1x13.get_ssc_measurement()
+    print("value2: {value1}µV")
+
+    # convert from MicroVolt to Volt
+    #   This might skew the value due to conversion to float!
+    value3 = float(value1) / (1000 * 1000)
+    print("value3: {value2:0.6f}V")
+
+    # show the raw value
+    # range:
+    #   -32768 ≤ x ≤ 32767
+    # granularity:
+    #   ADS101x: 15 steps (..., 15, 30, 45, ...)
+    #   ADS111x:  1 step  (..., 1, 2, 3, 4, ...)
+    value4 = ads1x13.get_ssc_measurement(unit=UNIT.STEPS)
+    print("value4: {value1}")
+
+    print('-' * 80)
+
+    # take multiple measurements and alternate between 2 configurations
+    config1 = Ads1113Config(drs=DRS.MODE4)
+    config2 = Ads1113Config(drs=DRS.MODE5)
+    while True:
+        value4 = ads1x13.get_ssc_measurement(config=config1)
+        print("value4: {value1}µV")
+        value5 = ads1x13.get_ssc_measurement(config=config2)
+        print("value5: {value1}µV")
+        time.sleep(1)

examples/02_continuous.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+monitor a channel (continuous-conversion mode)
+
+In continuous-conversion mode, the ADC automatically begins a conversion of
+the input signal as soon as the previous conversion is completed. The rate
+of continuous conversion is equal to the programmed data rate. Data can be
+read at any time and always reflect the most recent completed conversion.
+
+The ADS1014 and ADS1014 feature a programmable digital comparator that can
+issue an alert on the ALERT/RDY pin if the low or high threshold values are
+exceeded. Together with continuous-conversion mode this feature can be used
+to trigger a hardware interrupt and alert on abnormal conditions.
+
+This example works with all variations:
+ - ADS1013, ADS1014, ADS1015
+ - ADS1113, ADS1114, ADS1115
+(Please note that the samping rates on ADS101x and 111x are different.)
+
+usage:
+  pdm run examples/02_continuous.py
+"""
+
+import time
+
+import board  # type: ignore
+
+# module busio and board provide no type hints
+import busio  # type: ignore
+
+from feeph.ads1xxx import DOM, DRS, Ads1113, Ads1113Config
+
+if __name__ == '__main__':
+    i2c_bus = busio.I2C(scl=board.SCL, sda=board.SDA)
+    ads1x13 = Ads1113(i2c_bus=i2c_bus)
+
+    # create a configuration
+    #  - enable continuous conversion mode
+    #  - set desired data rate
+    # on ADS1x14/ADS1x15: configure comparator (clat, cmod, cpol & cque)
+    my_config = Ads1113Config(dom=DOM.CCM, drs=DRS.MODE2)
+
+    if ads1x13.configure(config=my_config):
+        while True:
+            # on an ADS111x in MODE2 there should be a new sample
+            # every 0.5 seconds (ADS101x is much faster)
+            value = ads1x13.get_ccm_measurement()
+            print("value: {value1}µV")
+            time.sleep(0.5)
+    else:
+        print("Unable to configure ADC.")

examples/03_comparator.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""
+configure the comparator
+
+The ADS1014 and ADS1014 feature a programmable digital comparator that can
+issue an alert on the ALERT/RDY pin if the low or high threshold values are
+exceeded. Together with continuous-conversion mode this feature can be used
+to trigger a hardware interrupt and alert on abnormal conditions.
+
+This example works with all variations:
+ - ADS1013, ADS1014, ADS1015
+ - ADS1113, ADS1114, ADS1115
+(Please note that the samping rates on ADS101x and 111x are different.)
+
+usage:
+  pdm run examples/03_comparator.py
+"""
+
+import time
+
+import board  # type: ignore
+
+# module busio and board provide no type hints
+import busio  # type: ignore
+
+from feeph.ads1xxx import DOM, DRS, Ads1114, Ads1114Config
+
+if __name__ == '__main__':
+    i2c_bus = busio.I2C(scl=board.SCL, sda=board.SDA)
+    ads1x14 = Ads1114(i2c_bus=i2c_bus)
+
+    # create a configuration
+    #  - enable continuous conversion mode
+    #  - set desired data rate
+    # on ADS1x14/ADS1x15: configure comparator (clat, cmod, cpol & cque)
+    my_config = Ads1114Config(dom=DOM.CCM, drs=DRS.MODE2)
+
+    if ads1x14.configure(config=my_config):
+        while True:
+            # on an ADS111x in MODE2 there should be a new sample
+            # every 0.5 seconds (ADS101x is much faster)
+            value = ads1x14.get_ccm_measurement()
+            print("value: {value1}µV")
+            time.sleep(0.5)
+    else:
+        print("Unable to configure ADC.")

examples/04_amplifier.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""
+configure the programmable gain amplifier
+
+This example requires a PGA:
+ - ADS1014, ADS1015
+ - ADS1114, ADS1115
+
+usage:
+  pdm run examples/04_amplifier.py
+"""
+
+import board  # type: ignore
+
+# module busio and board provide no type hints
+import busio  # type: ignore
+
+from feeph.ads1xxx import PGA, Ads1114, Ads1114Config
+
+if __name__ == '__main__':
+    i2c_bus = busio.I2C(scl=board.SCL, sda=board.SDA)
+    ads1x14 = Ads1114(i2c_bus=i2c_bus)
+
+    # make sure the voltage between AIN0 and GND does not exceed 0.5V
+    # (e.g. use a resistive divider)
+    #
+    # check feeph/ads1xxx/settings.py for an explanation of this setting
+    # or hover on 'PGA' and let your IDE show the docstring
+    config1 = Ads1114Config(pga=PGA.MODE2)  # FSR = ±2.048V
+    config2 = Ads1114Config(pga=PGA.MODE4)  # FSR = ±0.512V
+
+    value1 = ads1x14.get_ssc_measurement(config=config1)
+    print("value1: {value1}µV")  # 63µV resolution
+    value2 = ads1x14.get_ssc_measurement(config=config2)
+    print("value2: {value2}µV")  # 16µV resolution

examples/05_multiplexer.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""
+configure the input multiplexer
+
+This example requires a MUX:
+ - ADS1015
+ - ADS1115
+
+usage:
+  pdm run examples/05_multiplexer.py
+"""
+
+import time
+
+import board  # type: ignore
+
+# module busio and board provide no type hints
+import busio  # type: ignore
+
+from feeph.ads1xxx import MUX, PGA, Ads1115, Ads1115Config
+
+if __name__ == '__main__':
+    i2c_bus = busio.I2C(scl=board.SCL, sda=board.SDA)
+    ads1x15 = Ads1115(i2c_bus=i2c_bus)
+
+    # configure 2 channels
+    #  - config_abs: measure against ground (±2.0V)
+    #  - config_dif: measure delta, using a higher precision (±0.5V)
+    #
+    # check feeph/ads1xxx/settings.py for an explanation of this setting
+    # or hover on 'MUX' and let your IDE show the docstring
+    config_abs = Ads1115Config(mux=MUX.MODE4, pga=PGA.MODE1)  # AIN0»GND
+    config_dif = Ads1115Config(mux=MUX.MODE0, pga=PGA.MODE4)  # AIN0»AIN1
+
+    # switch between both configurations and take measurements
+    while True:
+        value1 = ads1x15.get_ssc_measurement(config=config_abs)
+        print("value1: {value1}µV")
+        value2 = ads1x15.get_ssc_measurement(config=config_dif)
+        print("value2: {value1}µV")
+        time.sleep(1)

examples/demonstrator.py

@@ -35,4 +35,4 @@
     ads1115.reset_device_registers()
 
     # take a single-shot measurement
-    LH.info("measurement: %0.6fV", ads1115.get_singleshot_measurement() / (1000 * 1000))
+    LH.info("measurement: %0.6fV", ads1115.get_ssc_measurement() / (1000 * 1000))

feeph/ads1xxx/__init__.py

@@ -5,7 +5,16 @@
 
 # the following imports are provided for user convenience
 # flake8: noqa: F401
+# 12bit / 3300 samples per second
+from feeph.ads1xxx.ads1013 import Ads1013, Ads1013Config
+from feeph.ads1xxx.ads1014 import Ads1014, Ads1014Config
+from feeph.ads1xxx.ads1015 import Ads1015, Ads1015Config
+
+# 16bit / 860 samples per second
 from feeph.ads1xxx.ads1113 import Ads1113, Ads1113Config
 from feeph.ads1xxx.ads1114 import Ads1114, Ads1114Config
 from feeph.ads1xxx.ads1115 import Ads1115, Ads1115Config
-from feeph.ads1xxx.settings import *
+
+# config settings
+from feeph.ads1xxx.conversions import UNIT
+from feeph.ads1xxx.settings import CLAT, CMOD, CPOL, CQUE, DOM, DRS, MUX, PGA, SSC

feeph/ads1xxx/ads1013.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+ADS1013 - Ultra-Small, Low-Power, I2C-Compatible, 3.3-kSPS, 12-Bit ADCs
+          With Internal Reference, Oscillator
+
+datasheet: https://www.ti.com/lit/ds/symlink/ads1013.pdf
+"""
+
+import logging
+
+from attrs import define
+
+from feeph.ads1xxx.ads1x1x import Ads1x1x, Ads1x1xConfig
+from feeph.ads1xxx.conversions import UNIT, convert_step_to_value
+from feeph.ads1xxx.settings import CLAT, CMOD, CPOL, CQUE, DOM, DRS, MUX, PGA, SSC
+
+LH = logging.getLogger('feeph.ads1xxx')
+
+
+@define
+class Ads1013Config(Ads1x1xConfig):
+    # fmt: off
+    ssc: SSC = SSC.NO_OP  # single-shot conversion trigger
+    dom: DOM = DOM.SSM    # device operation mode
+    drs: DRS = DRS.MODE4  # data rate setting
+    # fmt: on
+
+    def as_uint16(self) -> int:
+        # non-configurable values are set to their default
+        value = 0b0000_0000_0000_0000
+        value |= self.ssc.value
+        value |= MUX.MODE0.value  # no input multiplexer
+        value |= PGA.MODE2.value  # no programmable gain amplifier
+        value |= self.dom.value
+        value |= self.drs.value
+        value |= CMOD.TRD.value   # no comparator mode
+        value |= CPOL.ALO.value   # no comparator polarity
+        value |= CLAT.NLC.value   # no comparator latch
+        value |= CQUE.DIS.value   # no comparator queue
+        return value
+
+    # technically it's possible to set the alert threshold registers but it
+    # doesn't have any effect since there is no comparator which uses them
+
+    def get_atlo(self, unit: UNIT = UNIT.MICRO) -> int:
+        return convert_step_to_value(step=0x8000, unit=unit, pga=PGA.MODE2)
+
+    def get_athi(self, unit: UNIT = UNIT.MICRO) -> int:
+        return convert_step_to_value(step=0x7FFF, unit=unit, pga=PGA.MODE2)
+
+
+class Ads1013(Ads1x1x):
+    _has_pga = False

feeph/ads1xxx/ads1014.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+ADS1014 - Ultra-Small, Low-Power, I2C-Compatible, 3.3-kSPS, 12-Bit ADCs
+          With Internal Reference, Oscillator, and Programmable Comparator
+
+datasheet: https://www.ti.com/lit/ds/symlink/ads1014.pdf
+"""
+
+import logging
+
+from attrs import define
+
+from feeph.ads1xxx.ads1x1x import Ads1x1x, Ads1x1xConfig
+from feeph.ads1xxx.conversions import UNIT, convert_step_to_value, convert_value_to_step
+from feeph.ads1xxx.settings import CLAT, CMOD, CPOL, CQUE, DOM, DRS, MUX, PGA, SSC
+
+LH = logging.getLogger('feeph.ads1xxx')
+
+
+@define
+class Ads1014Config(Ads1x1xConfig):
+    # fmt: off
+    ssc:  SSC = SSC.NO_OP   # single-shot conversion trigger
+    pga:  PGA  = PGA.MODE2  # programmable gain amplifier
+    dom:  DOM = DOM.SSM     # device operation mode
+    drs:  DRS = DRS.MODE4   # data rate setting
+    cmod: CMOD = CMOD.TRD   # comparator mode
+    cpol: CPOL = CPOL.ALO   # comparator polarity
+    clat: CLAT = CLAT.NLC   # comparator latch
+    cque: CQUE = CQUE.DIS   # comparator queue
+    atlo: int = 0x8000      # alert threshold low (-32768)
+    athi: int = 0x7FFF      # alert threshold high (32767)
+    # fmt: on
+
+    def as_uint16(self) -> int:
+        value = 0b0000_0000_0000_0000
+        value |= self.ssc.value
+        value |= MUX.MODE0.value  # no input multiplexer
+        value |= self.pga.value
+        value |= self.dom.value
+        value |= self.drs.value
+        value |= self.cmod.value
+        value |= self.cpol.value
+        value |= self.clat.value
+        value |= self.cque.value
+        return value
+
+    def get_atlo(self, unit: UNIT = UNIT.MICRO) -> int:
+        return convert_step_to_value(step=self.atlo, unit=unit, pga=self.pga)
+
+    def set_atlo(self, value: int, unit: UNIT = UNIT.MICRO) -> bool:
+        try:
+            self.atlo = convert_value_to_step(value=value, unit=unit, pga=self.pga)
+            return True
+        except ValueError:
+            return False
+
+    def get_athi(self, unit: UNIT = UNIT.MICRO) -> int:
+        return convert_step_to_value(step=self.athi, unit=unit, pga=self.pga)
+
+    def set_athi(self, value: int, unit: UNIT = UNIT.MICRO) -> bool:
+        try:
+            self.athi = convert_value_to_step(value=value, unit=unit, pga=self.pga)
+            return True
+        except ValueError:
+            return False
+
+
+class Ads1014(Ads1x1x):
+    _has_pga = True