fix #82, minimal timeout 10 ms for RTOS (#83)

- fix #82, minimal timeout 10 ms for RTOS, kudos to deKees687 
- set error flag for TIMEOUT
- add error codes to keywords.txt

ADS1X15.cpp

@@ -1,14 +1,15 @@
 //
 //    FILE: ADS1X15.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.0
+// VERSION: 0.5.1
 //    DATE: 2013-03-24
 // PURPOSE: Arduino library for ADS1015 and ADS1115
 //     URL: https://github.com/RobTillaart/ADS1X15
 
 
 #include "ADS1X15.h"
 
+
 #define ADS1015_CONVERSION_DELAY    1
 #define ADS1115_CONVERSION_DELAY    8
 
@@ -229,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;
   }
 }
@@ -448,25 +449,30 @@ 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 }
-    //  a few ms more than max conversion time.
-    uint8_t timeOut = (128 >> (_datarate >> 5)) + 1;
+    //  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())
     {
-      yield();   //  wait for conversion; yield for ESP.
       if ( (millis() - start) > timeOut)
       {
+        _error = ADS1X15_ERROR_TIMEOUT;
         return ADS1X15_ERROR_TIMEOUT;
       }
+      yield();   //  wait for conversion; yield for ESP.
     }
   }
   else
   {
-    //  needed in continuous mode too, otherwise one get old value.
+    //  needed in continuous mode too, otherwise one get an old value.
     delay(_conversionDelay);
   }
   return getValue();

ADS1X15.h

@@ -2,7 +2,7 @@
 //
 //    FILE: ADS1X15.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.5.0
+// VERSION: 0.5.1
 //    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.5.0"))
+#define ADS1X15_LIB_VERSION               (F("0.5.1"))
 
 //  allow compile time default address
 //  address in { 0x48, 0x49, 0x4A, 0x4B }, no test...

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.5.1] - 2024-10-17
+- fix #82, minimal timeout 10 ms for RTOS, kudos to deKees687 
+- set error flag for TIMEOUT
+- add error codes to keywords.txt
+
 ## [0.5.0] - 2024-08-20
 - Fix #80, setComparatorPolarity() and setComparatorLatch() inverting.
 - add test example to test parameters.

README.md

@@ -269,8 +269,26 @@ Default pin = 0 as this is convenient for the single channel devices.
   ADS.readADC(0);
 ```
 
+
 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.
+
+```cpp
+   Value = ADS.readADC()
+   if (ADS.getError() == ADS1X15_OK)
+      //  Use value
+   else
+      //  handle error
+```
+
+The errorhandling within the library need to be improved, see also 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.

examples/ADS_read_getError/ADS_read_getError.ino

@@ -0,0 +1,71 @@
+//
+//    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);
+
+int16_t value[4];
+int err = ADS1X15_OK;
+float voltageFactor = 1;
+
+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();
+
+  voltageFactor = ADS.toVoltage(1);
+}
+
+
+void loop()
+{
+  ADS.setGain(0);
+
+  float f = ADS.toVoltage(1);  //  voltage factor
+
+  for (int channel = 0; channel < 4; channel++)
+  {
+    value[channel] = ADS.readADC(channel);
+    err = ADS.getError();
+    if (err != ADS1X15_OK)
+    {
+      Serial.print(channel);
+      Serial.print(" returns error: ");
+      Serial.println(err);
+    }
+
+    Serial.print("\tChannel ");
+    Serial.print(channel);
+    Serial.print(": ");
+    Serial.print(value[channel]);
+    Serial.print('\t');
+    Serial.println(value[channel] * voltageFactor, 3);
+  }
+
+  //  optional do other things with value[channel]
+
+  delay(1000);
+}
+
+
+//  -- END OF FILE --

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
+

library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/ADS1X15"
   },
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

library.properties

@@ -1,5 +1,5 @@
 name=ADS1X15
-version=0.5.0
+version=0.5.1
 author=Rob Tillaart <[email protected]>
 maintainer=Rob Tillaart <[email protected]>
 sentence=Arduino library for ADS1015 - I2C 12 bit ADC and ADS1115 I2C 16 bit ADC