0.3.9 ADS1X15 + update examples

Author: RobTillaart

libraries/ADS1x15/CHANGELOG.md

@@ -5,6 +5,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+- update and add examples
+
+
 ## [0.3.9] - 2023-01-21
 - update GitHub actions
 - update license 2023

libraries/ADS1x15/README.md

@@ -46,7 +46,11 @@ is connected to:
 
 ## Interface
 
-### Initializing
+```cpp
+#include "ADS1X15.h"
+```
+
+#### Initializing
 
 To initialize the library you must call constructor as described below.
 
@@ -87,7 +91,7 @@ void begin() {
 ```
 
 
-### I2C clock speed
+#### 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.
@@ -104,7 +108,7 @@ See - https://github.com/arduino/Arduino/issues/11457
 Question: should this functionality be in this library?
 
 
-### Programmable Gain
+#### Programmable Gain
 
 - **void setGain(uint8_t gain)** set the gain value, indicating the maxVoltage that can be measured
 Adjusting the gain allowing to make more precise measurements.
@@ -138,7 +142,7 @@ Check the [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples
 ```
 
 
-### Operational mode
+#### Operational mode
 
 The ADS sensor can operate in single shot or continuous mode.
 Depending on how often conversions needed you can tune the mode.
@@ -147,7 +151,7 @@ Note: the mode is not set in the device until an explicit read/request of the AD
 - **uint8_t getMode()** returns current mode 0 or 1, or ADS1X15_INVALID_MODE = 0xFE.
 
 
-### Data rate
+#### Data rate
 
 - **void setDataRate(uint8_t dataRate)** Data rate depends on type of device.
 For all devices the index 0..7 can be used, see table below.
@@ -172,7 +176,7 @@ Data rate in samples per second, based on datasheet is described on table below.
 |     7       |   3300    |    860    |  fastest  |
 
 
-### ReadADC Single mode
+#### ReadADC Single mode
 
 Reading the ADC is very straightforward, the **readADC()** function handles all in one call.
 Under the hood it uses the asynchronous calls.
@@ -221,7 +225,7 @@ in terms of code
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_async/ADS_read_async.ino).
 
 
-## ReadADC Differential
+#### ReadADC Differential
 
 For reading the ADC in a differential way there are 4 calls possible.
 
@@ -250,7 +254,7 @@ After one of these calls you need to call
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_differential/ADS_differential.ino).
 
 
-### ReadADC continuous mode
+#### ReadADC continuous mode
 
 To use the continuous mode you need call three functions:
 - **void setMode(0)** 0 = CONTINUOUS, 1 = SINGLE (default).
@@ -283,7 +287,7 @@ Instead you can configure the threshold registers to allow the **ALERT/RDY**
 pin to trigger an interrupt signal when conversion data ready.
 
 
-### Threshold registers
+#### Threshold registers
 
 If the thresholdHigh is set to 0x0100 and the thresholdLow to 0x0000
 the **ALERT/RDY** pin is triggered when a conversion is ready.
@@ -296,7 +300,7 @@ the **ALERT/RDY** pin is triggered when a conversion is ready.
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_RDY/ADS_read_RDY.ino).
 
 
-## Comparator
+#### Comparator
 
 Please read Page 15 of the datasheet as the behaviour of the
 comparator is not trivial.
@@ -305,7 +309,7 @@ NOTE: all comparator settings are copied to the device only after calling
 **readADC()** or **requestADC()** functions.
 
 
-### Comparator Mode
+#### Comparator Mode
 
 When configured as a **TRADITIONAL** comparator, the **ALERT/RDY** pin asserts
 (active low by default) when conversion data exceed the limit set in the
@@ -326,7 +330,7 @@ the high threshold register or falls below the low threshold register.
 In this mode the alert is held if the **LATCH** is set. This is similar as above.
 
 
-### Polarity
+#### Polarity
 
 Default state of the **ALERT/RDY** pin is **LOW**, can be to set **HIGH**.
 
@@ -335,7 +339,7 @@ Flag is only explicitly set after a **readADC()** or a **requestADC()**
 - **uint8_t getComparatorPolarity()** returns value set.
 
 
-### Latch
+#### Latch
 
 Holds the **ALERT/RDY** to **HIGH** (or **LOW** depending on polarity) after triggered
 even if actual value has been 'restored to normal' value.
@@ -344,7 +348,7 @@ even if actual value has been 'restored to normal' value.
 - **uint8_t getComparatorLatch()** returns value set.
 
 
-### QueConvert
+#### QueConvert
 
 Set the number of conversions before trigger activates.
 The **void setComparatorQueConvert(uint8_t mode)** is used to set the number of
@@ -362,7 +366,7 @@ A value of 3 (or above) effectively disables the comparator. See table below.
 |    3    |  Disable comparator                 |  default  |
 
 
-### Threshold registers comparator mode
+#### Threshold registers comparator mode
 
 Depending on the comparator mode **TRADITIONAL** or **WINDOW** the thresholds registers
 mean something different see - Comparator Mode above or datasheet.
@@ -373,7 +377,7 @@ mean something different see - Comparator Mode above or datasheet.
 - **int16_t getComparatorThresholdHigh()** reads value from device.
 
 
-### RP2040 specific
+## RP2040 specific
 
 - **bool begin(int sda, int scl)** begin communication with the ADC.
 It has the parameter for selecting on which pins the communication should happen.

libraries/ADS1x15/examples/ADS_1114_four/ADS_1114_four.ino

@@ -36,7 +36,7 @@ void setup()
     Serial.print("  ");
     Serial.println(ADS[i].begin() ? "connected" : "not connected");
 
-    ADS[i].setDataRate(4);        //  7 is fastest, but more noise
+    ADS[i].setDataRate(4);        // 0 = slow   4 = medium   7 = fast, but more noise
   }
   ADS_request_all();
 }

libraries/ADS1x15/examples/ADS_1114_two_continuous/ADS_1114_two_continuous.ino

@@ -31,7 +31,7 @@ void setup()
   // SETUP FIRST ADS1114
   ADS_1.begin();
   ADS_1.setGain(0);         //  0 == 6.144 volt, default
-  ADS_1.setDataRate(7);     //  7 == highest
+  ADS_1.setDataRate(7);     //  0 = slow   4 = medium   7 = fast
 
   // SET ALERT RDY PIN
   ADS_1.setComparatorThresholdHigh(0x8000);

libraries/ADS1x15/examples/ADS_RP2040_WIRE1/ADS_RP2040_WIRE1.ino

@@ -1,9 +1,8 @@
 //
 //    FILE: ADS_RP2040_WIRE1.ino
 //  AUTHOR: Rob.Tillaart / Intubun
-// VERSION: 0.1.1
 // PURPOSE: read analog input
-//
+//     URL: https://github.com/RobTillaart/ADS1X15
 
 // test
 // connect 1 potmeter
@@ -35,7 +34,7 @@ void setup()
 
   ADS.begin(26, 27);   // SDA (Pin 26), SCL(Pin 27)
   ADS.setGain(0);      // 6.144 volt
-  ADS.setDataRate(7);  // fast
+  ADS.setDataRate(7);  // 0 = slow   4 = medium   7 = fast
   ADS.setMode(0);      // continuous mode
   ADS.readADC(0);      // first read to trigger
 }

libraries/ADS1x15/examples/ADS_async_16_channel/ADS_async_16_channel.ino

@@ -39,7 +39,7 @@ void setup()
     Serial.print("  ");
     Serial.println(ADS[i].begin() ? "connected" : "not connected");
 
-    ADS[i].setDataRate(4);  // 7 is fastest, but more noise
+    ADS[i].setDataRate(4);  // 0 = slow   4 = medium   7 = fast, but more noise
   }
   ADS_request_all();
 }

libraries/ADS1x15/examples/ADS_async_8_channel/ADS_async_8_channel.ino

@@ -46,7 +46,7 @@ void setup()
   //  Serial.println(ADS2.isConnected());
   //  Serial.println(ADS3.isConnected());
 
-  ADS0.setDataRate(4);  // 7 is fastest, but more noise
+  ADS0.setDataRate(4);  // 0 = slow   4 = medium   7 = fast but more noise
   ADS1.setDataRate(4);
   //  ADS2.setDataRate(4);
   //  ADS3.setDataRate(4);

libraries/ADS1x15/examples/ADS_async_differential/ADS_async_differential.ino

@@ -3,7 +3,7 @@
 //  AUTHOR: Rob.Tillaart
 // VERSION: 0.1.0
 // PURPOSE: read multiple differential continuously
-//
+//     URL: https://github.com/RobTillaart/ADS1X15
 
 // test
 // connect 4 potmeters
@@ -42,7 +42,7 @@ void setup()
 
   ADS.begin();
   ADS.setGain(0);        // 6.144 volt
-  ADS.setDataRate(4);    // medium
+  ADS.setDataRate(4);    // 0 = slow   4 = medium   7 = fast
 
   // single shot mode
   ADS.setMode(1);

libraries/ADS1x15/examples/ADS_continuous/ADS_continuous.ino

@@ -1,9 +1,8 @@
 //
 //    FILE: ADS_continuous.ino
 //  AUTHOR: Rob.Tillaart
-// VERSION: 0.1.1
 // PURPOSE: read analog input
-//
+//     URL: https://github.com/RobTillaart/ADS1X15
 
 // test
 // connect 1 potmeter
@@ -35,7 +34,7 @@ void setup()
 
   ADS.begin();
   ADS.setGain(0);      // 6.144 volt
-  ADS.setDataRate(7);  // fast
+  ADS.setDataRate(7);  // 0 = slow   4 = medium   7 = fast
   ADS.setMode(0);      // continuous mode
   ADS.readADC(0);      // first read to trigger
 }

libraries/ADS1x15/examples/ADS_continuous_3_channel/ADS_continuous_3_channel.ino

@@ -0,0 +1,121 @@
+//
+//    FILE: ADS_continuous_3_channel.ino
+//  AUTHOR: Rob.Tillaart
+// PURPOSE: read multiple analog inputs continuously
+//          interrupt driven to catch all conversions.
+//     URL: https://github.com/RobTillaart/ADS1X15
+//          https://github.com/RobTillaart/ADS1X15/issues/49
+//
+//  experimental, not tested extensively
+
+// test
+// connect multiple potmeters
+//
+//  RDY ----------------- pin 2 (for IRQ)
+//
+//  GND ---[   x   ]------ 5V
+//             |
+//             |
+//           ADS(n)
+//
+//  measure at x  - connect to AIN0..3.
+//
+//  for the test it is an option to have AIN3 connected to 5V and AIN4 to GND
+//  so one can see these as references in the output.
+//
+//  has an issue with the index of the channels. not not investigated yet.
+
+
+#include "ADS1X15.h"
+
+
+// choose your sensor
+// ADS1013 ADS(0x48);
+// ADS1014 ADS(0x48);
+// ADS1015 ADS(0x48);
+// ADS1113 ADS(0x48);
+// ADS1114 ADS(0x48);
+ADS1115 ADS(0x48);
+
+volatile bool RDY = false;
+uint8_t channel = 0;
+int16_t val[4] = { 0, 0, 0, 0 };
+
+int SPS = 0;
+uint32_t lastTime = 0;
+
+
+void setup()
+{
+  Serial.begin(230400);       //  <<<<<<<<<  fast!
+  Serial.println(__FILE__);
+  Serial.print("ADS1X15_LIB_VERSION: ");
+  Serial.println(ADS1X15_LIB_VERSION);
+
+  Wire.setClock(400000);
+
+  ADS.begin();
+  ADS.setGain(0);        // 6.144 volt
+  ADS.setDataRate(7);    // 0 = slow   4 = medium   7 = fast
+
+  // SET ALERT RDY PIN
+  ADS.setComparatorThresholdHigh(0x8000);
+  ADS.setComparatorThresholdLow(0x0000);
+  ADS.setComparatorQueConvert(0);
+
+  // SET INTERRUPT HANDLER TO CATCH CONVERSION READY
+  pinMode(2, INPUT_PULLUP);
+  attachInterrupt(digitalPinToInterrupt(2), adsReady, RISING);
+
+  ADS.setMode(0);            //  continuous mode
+  channel = 0;
+  ADS.requestADC(channel);   //  start at 0
+}
+
+
+void loop()
+{
+  //  if conversion ready
+  //  request a new one and print the last one.
+  if (RDY)
+  {
+    SPS++;
+    val[channel] = ADS.getValue();
+    // request next channel asap
+    channel++;
+    if (channel >= 3) channel = 0;
+    ADS.requestADC(channel);
+    RDY = false;
+
+    //  to see it works
+    if (SPS % 200 == 0)
+    {
+      for (int i = 0; i < 4; i++)
+      {
+        Serial.print('\t');
+        Serial.print(val[i]);
+      }
+      Serial.println();
+    }
+  }
+
+
+  //  print the SPS
+  if (millis() - lastTime >= 1000)
+  {
+    lastTime = millis();
+    Serial.print("SPS: ");
+    Serial.println(SPS);
+    SPS = 0;
+  }
+}
+
+
+//  interrupt service routine
+//  kept as minimal as possible
+void adsReady()
+{
+  RDY = true;
+}
+
+//  -- END OF FILE --