Fix #74, update readme.md (#75)

- Fix #74, ALERT/RDY pin documentation - update readme.md - minor edits examples
RobTillaart · Jun 26, 2024 · 50dbd26 · 50dbd26
1 parent 95dcd65
commit 50dbd26
Show file tree

Hide file tree

Showing 11 changed files with 179 additions and 102 deletions.
diff --git a/ADS1X15.cpp b/ADS1X15.cpp
@@ -1,7 +1,7 @@
 //
 //    FILE: ADS1X15.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.2
+// VERSION: 0.4.3
 //    DATE: 2013-03-24
 // PURPOSE: Arduino library for ADS1015 and ADS1115
 //     URL: https://github.com/RobTillaart/ADS1X15

diff --git a/ADS1X15.h b/ADS1X15.h
@@ -2,7 +2,7 @@
 //
 //    FILE: ADS1X15.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.2
+// VERSION: 0.4.3
 //    DATE: 2013-03-24
 // PURPOSE: Arduino library for ADS1015 and ADS1115
 //     URL: https://github.com/RobTillaart/ADS1X15
@@ -12,7 +12,7 @@
 #include "Arduino.h"
 #include "Wire.h"
 
-#define ADS1X15_LIB_VERSION               (F("0.4.2"))
+#define ADS1X15_LIB_VERSION               (F("0.4.3"))
 
 //  allow compile time default address
 //  address in { 0x48, 0x49, 0x4A, 0x4B }, no test...
@@ -123,6 +123,7 @@ class ADS1X15
 
   int8_t   getError();
 
+
   //  EXPERIMENTAL
   //  see https://github.com/RobTillaart/ADS1X15/issues/22
   void     setWireClock(uint32_t clockSpeed = 100000);

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,18 +1,22 @@
-# Change Log
+# Change Log ADS1x15
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.3] - 2024-06-25
+- Fix #74, ALERT/RDY pin documentation
+- update readme.md
+- minor edits examples
+
 ## [0.4.2] - 2024-03-04
 - fix #68, gain bugs ADS1x13
 - add unit test for ADS1x13
 - update GitHub/actions to v4
 - removed depreciated **getLastValue()**
 - add multiplexer section to readme.md
 
-
 ## [0.4.1] - 2024-01-02
 - fix some typos
 - minor edits

diff --git a/README.md b/README.md
@@ -22,40 +22,62 @@ you can check similar library [here](https://github.com/chandrawi/ADS1x15-ADC).
 This library should work for the devices mentioned below,
 although not all sensors support all functionality.
 
-|  Device   |  Channels  |  Resolution  |  Max sps  |  Comparator  |  ProgGainAMP  |  Notes   |
-|:---------:|:----------:|:------------:|:---------:|:------------:|:-------------:|:---------|
-|  ADS1013  |      1     |       12     |    3300   |       N      |        N      |          |
-|  ADS1014  |      1     |       12     |    3300   |       Y      |        Y      |          |
-|  ADS1015  |      4     |       12     |    3300   |       Y      |        Y      |          |
-|  ADS1113  |      1     |       16     |    860    |       N      |        N      |          |
-|  ADS1114  |      1     |       16     |    860    |       Y      |        Y      |          |
-|  ADS1115  |      4     |       16     |    860    |       Y      |        Y      |  Tested  |
+|  Device   |  Channels  |  Resolution  |  Max sps  |  Comparator  |  Interrupts  |  ProgGainAMP  |  Notes   |
+|:---------:|:----------:|:------------:|:---------:|:------------:|:------------:|:-------------:|:---------|
+|  ADS1013  |      1     |       12     |    3300   |       N      |       N      |        N      |          |
+|  ADS1014  |      1     |       12     |    3300   |       Y      |       Y      |        Y      |          |
+|  ADS1015  |      4     |       12     |    3300   |       Y      |       Y      |        Y      |          |
+|  ADS1113  |      1     |       16     |    860    |       N      |       N      |        N      |          |
+|  ADS1114  |      1     |       16     |    860    |       Y      |       Y      |        Y      |          |
+|  ADS1115  |      4     |       16     |    860    |       Y      |       Y      |        Y      |  Tested  |
 
 
 As the ADS1015 and the ADS1115 are both 4 channels these are the most
-interesting from functionality point of view as these can also do
+interesting from functionality point of view as these can do
 differential measurements.
 
 
+#### Interrupts
+
+Besides polling the ADS1x14 and ADS1x15 support interrupts to maximize throughput 
+with minimal latency. For this these device has an ALERT/RDY pin. 
+This pin can be used both for interrupts or polling, see table of examples below.
+
+|   example                         |  Interrupts  |  notes  |
+|:---------------------------------:|:------------:|:-------:|
+|  ADS_1114_two_continuous.ino      |      Y       |
+|  ADS_continuous_3_channel.ino     |      Y       |
+|  ADS_continuous_4_channel.ino     |      Y       |
+|  ADS_continuous_8_channel.ino     |      Y       |
+|  ADS_continuous_differential.ino  |      Y       |
+|  ADS_high_speed_differential.ino  |      Y       |
+|  ADS_read_async_rdy.ino           |   polling    |
+|  ADS_read_RDY.ino                 |   polling    |
+
+
 #### 0.4.0 Breaking change
 
 Version 0.4.0 introduced a breaking change.
 You cannot set the pins in **begin()** any more.
-This reduces the dependency of processor dependent Wire implementations.
-The user has to call **Wire.begin()** and can optionally set the Wire pins 
+This reduces the dependency of processor dependent Wire / I2C implementations.
+The user has to call **Wire.begin()** and can optionally set the I2C pins 
 before calling **begin()**.
 
 
 #### Related
 
-- https://github.com/RobTillaart/MCP_ADC  (10 & 12 bit ADC, SPI, fast)
-- https://github.com/RobTillaart/PCF8591  (8 bit ADC + 1 bit DAC)
+- https://github.com/RobTillaart/ADC081S 10-12 bit, single channel ADC
+- https://github.com/RobTillaart/ADC08XS 10-12 bit, 2 + 4 channel ADC
+- https://gammon.com.au/adc tutorial about ADC's (UNO specific)
+- https://github.com/RobTillaart/MCP_ADC 10-12 bit, 1,2,4,8 channel ADC
+- https://github.com/RobTillaart/ADS1x15
+- https://github.com/RobTillaart/PCF8591 8 bit single ADC (+ 1 bit DAC)
 
 
 ## I2C Address
 
-The address of the ADS1113/4/5 is determined by to which pin the **ADDR**
-is connected to:
+The I2C address of the ADS1113 /14 /15 is determined by to which pin 
+the **ADDR** is connected to:
 
 |  ADDR pin connected to  |  Address  |  Notes    |
 |:-----------------------:|:---------:|:---------:|
@@ -108,32 +130,39 @@ and optional the Wire interface as parameter.
 and optional the Wire interface as parameter.
 
 
-After construction the **ADS.begin()** need to be called. This will return false
-if an invalid address is used.
-The function **bool isConnected()** can be used to verify the reading of the ADS.
-The function **void reset()** is sets the parameters to their initial value as
+After construction the **ADS.begin()** must be called, typical in **setup()**.
+
+- **bool begin()** Returns false if an invalid address is used.
+- **bool isConnected()** is used to check if the device address is visible on I2C.
+- **void reset()** sets the internal parameters to their initial value as
 in the constructor.
 
 For example.
 
 ```cpp
-#include "ADS1X15.h"
+  #include "ADS1X15.h"
 
-// initialize ADS1115 on I2C bus 1 with default address 0x48
-ADS1115 ADS(0x48);
+  //  initialize ADS1115 on I2C bus 1 with default address 0x48
+  ADS1115 ADS(0x48);
 
-void begin() {
-  if (!ADS.isConnected()) {
-    // error ADS1115 not connected
+  void setup() 
+  {
+    if (!ADS.begin()) 
+    {
+      //  invalid address ADS1115 or 0x48 not found
+    }
+    if (!ADS.isConnected()) 
+    {
+      //  address 0x48 not found
+    }
   }
-}
 ```
 
 
 #### I2C clock speed
 
 The function **void setWireClock(uint32_t speed = 100000)** is used to set the clock speed
-in Hz of the used I2C interface. typical value is 100 KHz.
+in Hz of the used I2C interface. Typical value is 100 KHz.
 
 The function **uint32_t getWireClock()** is a prototype.
 It returns the value set by setWireClock().
@@ -177,14 +206,15 @@ Check the [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples
 ```cpp
   float f = ADS.toVoltage();
   ADS.setComparatorThresholdLow( 3.0 / f );
-  ADS.setComparatorThresholdLow( 4.3 / f );
+  ADS.setComparatorThresholdHigh( 4.3 / f );
 ```
 
 
 #### Operational mode
 
 The ADS sensor can operate in single shot or continuous mode.
 Depending on how often conversions needed you can tune the mode.
+
 - **void setMode(uint8_t mode)** 0 = CONTINUOUS, 1 = SINGLE (default)
 Note: the mode is not set in the device until an explicit read/request of the ADC (any read call will do).
 - **uint8_t getMode()** returns current mode 0 or 1, or ADS1X15_INVALID_MODE = 0xFE.
@@ -219,35 +249,38 @@ Data rate in samples per second, based on datasheet is described on table below.
 
 Reading the ADC is very straightforward, the **readADC()** function handles all in one call.
 Under the hood it uses the asynchronous calls.
+
 - **int16_t readADC(uint8_t pin = 0)** normal ADC functionality, pin = 0..3.
-If the pin number is out of range, this function will return 0.
-Default pin = 0 as this is convenient for 1 channel devices.
+If the pin number is out of range, this function will return 0 (seems safest).
+Default pin = 0 as this is convenient for the single channel devices.
 
 ```cpp
-// read ADC in pin 2
-ADS.readADC(2);
+  //  read ADC in pin 2
+  ADS.readADC(2);
 
-// read ADC in pin 0 - two ways
-ADS.readADC();
-ADS.readADC(0);
+  //  read ADC in pin 0 - two ways
+  ADS.readADC();
+  ADS.readADC(0);
 ```
 
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_minimum/ADS_minimum.ino).
 
 To read the ADC in an asynchronous way (e.g. to minimize blocking) you need call three functions:
+
 - **void requestADC(uint8_t pin = 0)**  Start the conversion. pin = 0..3.
 Default pin = 0 as this is convenient for 1 channel devices.
 - **bool isBusy()** Is the conversion not ready yet? Works only in SINGLE mode!
 - **bool isReady()** Is the conversion ready? Works only in SINGLE mode!  (= wrapper around **isBusy()** )
 - **int16_t getValue()** Read the result of the conversion.
 
 
-in terms of code
+in terms of code:
+
 ```cpp
   void setup()
   {
-    // other setup things here
-    ADS.setMode(1);               // SINGLE SHOT MODE
+    //  other setup things here
+    ADS.setMode(1);               //  SINGLE SHOT MODE
     ADS.requestADC(pin);
   }
 
@@ -256,9 +289,9 @@ in terms of code
     if (ADS.isReady())
     {
       value = ADS.getValue();
-      ADS.requestADC(pin);       // request new conversion
+      ADS.requestADC(pin);       //  request new conversion
     }
-    // do other things here
+    //  do other things here
   }
 ```
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_async/ADS_read_async.ino).
@@ -276,8 +309,8 @@ For reading the ADC in a differential way there are 4 calls possible.
 - **int16_t readADC_Differential_1_2()** ADS1x15 only - in software (no async equivalent)
 
 ```cpp
-// read differential ADC between pin 0 and 1
-ADS.readADC_Differential_0_1(0);
+  //  read differential ADC between pin 0 and 1
+  ADS.readADC_Differential_0_1(0);
 ```
 
 The differential reading of the ADC can also be done with asynchronous calls.
@@ -328,6 +361,7 @@ one of the two single pin values.
 #### ReadADC continuous mode
 
 To use the continuous mode you need call three functions:
+
 - **void setMode(0)** 0 = CONTINUOUS, 1 = SINGLE (default).
 Note: the mode is not set in the device until an explicit read/request of the ADC (any read call will do).
 - **int16_t readADC(uint8_t pin)** or **void requestADC(uint8_t pin)** to get the continuous mode started.
@@ -336,16 +370,18 @@ Note this can be a different pin, so be warned.
 Calling this over and over again can give the same value multiple times.
 
 ```cpp
-void setup() {
-  // configuration things here
-  ADS.setMode(ADS.MODE_CONTINUOUS);
-  ADS.requestADC(0);              // request on pin 0
-}
-
-void loop() {
-  value = ADS.getValue()
-  sleep(1)
-}
+  void setup() 
+  {
+    //  configuration things here
+    ADS.setMode(ADS.MODE_CONTINUOUS);
+    ADS.requestADC(0);              //  request on pin 0
+  }
+
+  void loop()
+  {
+    value = ADS.getValue()
+    sleep(1)
+  }
 ```
 
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_continuous/ADS_continuous.ino)
@@ -381,7 +417,14 @@ This explicit stop takes extra time, however it should prevent "incorrect" readi
 
 #### Threshold registers
 
-If the thresholdHigh is set to 0x0100 and the thresholdLow to 0x0000
+(datasheet 9.3.8)  
+_Conversion Ready Pin (ADS1114 and ADS1115 Only)
+The ALERT/RDY pin can also be configured as a conversion ready pin. Set the most-significant bit of the
+Hi_thresh register to 1 and the most-significant bit of Lo_thresh register to 0 to enable the pin as a conversion
+ready pin._
+
+
+If the thresholdHigh is set to 0x8000 and the thresholdLow to 0x0000
 the **ALERT/RDY** pin is triggered when a conversion is ready.
 
 - **void setComparatorThresholdLow(int16_t lo)** writes value to device directly.
@@ -443,22 +486,28 @@ even if actual value has been 'restored to normal' value.
 #### QueConvert
 
 Set the number of conversions before trigger activates.
+
 The **void setComparatorQueConvert(uint8_t mode)** is used to set the number of
 conversions that exceed the threshold before the **ALERT/RDY** pin is set **HIGH**.
 A value of 3 (or above) effectively disables the comparator. See table below. 
-To enable the conversion-ready function of the ALERT/RDY pin, it is necessary to set the MSB of the Hi_thresh register to 1 and the MSB of the Lo_thresh register to 0.
 
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_continuous_differential/ADS_continuous_differential.ino).
 
 - **void setComparatorQueConvert(uint8_t mode)** See table below.
-- **uint8_t getComparatorQueConvert()**  returns value set.
+- **uint8_t getComparatorQueConvert()**  returns the value set.
 
 |  value  |  meaning                            |  Notes    |
 |:-------:|:------------------------------------|:----------|
 |    0    |  trigger alert after 1 conversion   |           |
 |    1    |  trigger alert after 2 conversions  |           |
 |    2    |  trigger alert after 4 conversions  |           |
 |    3    |  Disable comparator                 |  default  |
+|  other  |  Disable comparator                 |           |
+
+To enable the conversion-ready function of the **ALERT/RDY** pin, 
+it is necessary to set the MSB of the Hi_threshold register to 1 (value 0x8000)
+and the MSB of the Lo_threshold register to 0.
+See section **Threshold registers** above.
 
 
 #### Threshold registers comparator mode
@@ -477,23 +526,26 @@ mean something different see - Comparator Mode above or datasheet.
 #### Must
 
 - Improve documentation (always)
+  - split off separate topics?
 
 #### Should
 
+- remove the experimental **getWireClock()** as this is not really a library function
+  but a responsibility of the I2C library.
+- investigate ADS1118 library which should be a similar SPI based ADC.
 
 #### Could
 
+- some **void** functions could return **bool** to be more informative?
 - More examples
 - SMB alert command (00011001) on I2C bus?
 - sync order .h / .cpp
 
-
 #### Wont (unless requested)
 
 - type flag?
 - constructor for ADS1X15? No as all types are supported.
 
-
 ## Support
 
 If you appreciate my libraries, you can support the development and maintenance.

diff --git a/examples/ADS_high_speed_differential/ADS_high_speed_differential.ino b/examples/ADS_high_speed_differential/ADS_high_speed_differential.ino
@@ -1,5 +1,5 @@
 //
-//    FILE: ADS_high_speed_differential.ino.ino
+//    FILE: ADS_high_speed_differential.ino
 //  AUTHOR: Rob.Tillaart
 // PURPOSE: read from 2 IC's for high speed differential
 //          interrupt driven to catch all conversions.