From 11755d138c2fc03db797a312842bd69806354ddb Mon Sep 17 00:00:00 2001
From: Rob Tillaart <rob.tillaart@gmail.com>
Date: Thu, 17 Oct 2024 17:16:35 +0200
Subject: [PATCH] fix #82, minimal timeout 10 ms for RTOS

---
 ADS1X15.cpp                                   | 11 ++-
 CHANGELOG.md                                  |  1 +
 README.md                                     | 10 +++
 .../ADS_read_getError/ADS_read_getError.ino   | 80 +++++++++++++++++++
 keywords.txt                                  | 10 +++
 5 files changed, 108 insertions(+), 4 deletions(-)
 create mode 100644 examples/ADS_read_getError/ADS_read_getError.ino

diff --git a/ADS1X15.cpp b/ADS1X15.cpp
index 94e6378..2b8bdb3 100644
--- a/ADS1X15.cpp
+++ b/ADS1X15.cpp
@@ -230,7 +230,7 @@ void ADS1X15::setMode(uint8_t mode)
   switch (mode)
   {
     case 0: _mode = ADS1X15_MODE_CONTINUE; break;
-    default:
+    default:  //  catch invalid modi
     case 1: _mode = ADS1X15_MODE_SINGLE;   break;
   }
 }
@@ -449,13 +449,16 @@ uint32_t ADS1X15::getWireClock()
 //
 int16_t ADS1X15::_readADC(uint16_t readmode)
 {
+  //  note readmode includes the channel
   _requestADC(readmode);
+
   if (_mode == ADS1X15_MODE_SINGLE)
   {
     uint32_t start = millis();
-    //  timeout == { 129, 65, 33, 17, 9, 5, 3, 2 }
-    //  add 10 ms more than max conversion time.
-    //  to prevent premature timeout in RTOS context. See #82
+    //  timeout == { 138, 74, 42, 26, 18, 14, 12, 11 }
+    //  added 10 ms more than maximum conversion time from datasheet.
+    //  to prevent premature timeout in RTOS context.
+    //  See #82
     uint8_t timeOut = (128 >> (_datarate >> 5)) + 10;
     while (isBusy())
     {
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 99785a4..bb19cee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [0.5.1] - 2024-10-17
 - fix #82, minimal timeout 10 ms for RTOS
 - set error flag for TIMEOUT
+- add error codes to keywords.txt
 
 ## [0.5.0] - 2024-08-20
 - Fix #80, setComparatorPolarity() and setComparatorLatch() inverting.
diff --git a/README.md b/README.md
index 63f5084..d512df9 100644
--- a/README.md
+++ b/README.md
@@ -271,6 +271,16 @@ Default pin = 0 as this is convenient for the single channel devices.
 
 See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_minimum/ADS_minimum.ino).
 
+
+The **readADC()** can return **ADS1X15_ERROR_TIMEOUT (-101)** which is an errorcode.
+This may conflict with a possible actual value of -101. 
+Therefore the user should check with **getError()** if an error has occurred after reading the ADC.
+
+This need to be fixed in the future, see issue #84.
+
+
+### Read the ADC in asynchronous way
+
 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.
diff --git a/examples/ADS_read_getError/ADS_read_getError.ino b/examples/ADS_read_getError/ADS_read_getError.ino
new file mode 100644
index 0000000..2706dc5
--- /dev/null
+++ b/examples/ADS_read_getError/ADS_read_getError.ino
@@ -0,0 +1,80 @@
+//
+//    FILE: ADS_read_getError.ino
+//  AUTHOR: Rob.Tillaart
+// PURPOSE: read analog inputs and check for error.
+//     URL: https://github.com/RobTillaart/ADS1X15
+
+//  test
+//  connect 1 potmeter per port.
+//
+//  GND ---[   x   ]------ 5V
+//             |
+//
+//  measure at x (connect to AIN0).
+
+
+#include "ADS1X15.h"
+
+ADS1115 ADS(0x48);
+
+
+void setup() 
+{
+  Serial.begin(115200);
+  Serial.println();
+  Serial.println(__FILE__);
+  Serial.print("ADS1X15_LIB_VERSION: ");
+  Serial.println(ADS1X15_LIB_VERSION);
+  Serial.println();
+
+  Wire.begin();
+  ADS.begin();
+}
+
+
+void loop() 
+{
+  ADS.setGain(0);
+
+  int16_t val_0 = ADS.readADC(0);
+  int err = ADS.getError();
+  if (err != ADS1X15_OK)
+  {
+    Serial.print("input 0 => ");
+    Serial.println(err);
+  }
+  int16_t val_1 = ADS.readADC(1);  
+  err = ADS.getError();
+  if (err != ADS1X15_OK)
+  {
+    Serial.print("input 1 => ");
+    Serial.println(err);
+  }
+  int16_t val_2 = ADS.readADC(2);  
+  err = ADS.getError();
+  if (err != ADS1X15_OK)
+  {
+    Serial.print("input 2 => ");
+    Serial.println(err);
+  }
+  int16_t val_3 = ADS.readADC(3);  
+  err = ADS.getError();
+  if (err != ADS1X15_OK)
+  {
+    Serial.print("input 3 => ");
+    Serial.println(err);
+  }
+
+  float f = ADS.toVoltage(1);  //  voltage factor
+
+  Serial.print("\tAnalog0: "); Serial.print(val_0); Serial.print('\t'); Serial.println(val_0 * f, 3);
+  Serial.print("\tAnalog1: "); Serial.print(val_1); Serial.print('\t'); Serial.println(val_1 * f, 3);
+  Serial.print("\tAnalog2: "); Serial.print(val_2); Serial.print('\t'); Serial.println(val_2 * f, 3);
+  Serial.print("\tAnalog3: "); Serial.print(val_3); Serial.print('\t'); Serial.println(val_3 * f, 3);
+  Serial.println();
+
+  delay(1000);
+}
+
+
+//  -- END OF FILE --
diff --git a/keywords.txt b/keywords.txt
index 6880492..7240bcd 100644
--- a/keywords.txt
+++ b/keywords.txt
@@ -85,3 +85,13 @@ ADS1x15_COMP_MODE_WINDOW	LITERAL1
 ADS1x15_COMP_POL_FALLING_EDGE	LITERAL1
 ADS1x15_COMP_POL_RISING_EDGE	LITERAL1
 
+
+# Error Codes
+
+ADS1X15_OK	KEYWORD2
+ADS1X15_INVALID_VOLTAGE	KEYWORD2
+ADS1X15_ERROR_TIMEOUT	KEYWORD2
+ADS1X15_ERROR_I2C	KEYWORD2
+ADS1X15_INVALID_GAIN	KEYWORD2
+ADS1X15_INVALID_MODE	KEYWORD2
+