0.1.1 RAIN

libraries/rain/CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.1.1] - 2022-12-03
+- change levels to milliVolts (uint16_t).
+- rewrite setLevel(milliVolts) and getLevel().
+- update readme.md
+- add/update examples
+- update keywords.txt
+- add delta() => delta with previous read().
+
+
 ## [0.1.0] - 2022-12-03
 - initial version
 

libraries/rain/README.md

@@ -8,22 +8,22 @@
 
 # RAIN
 
-Arduino library for rain sensor (analog).
+RAIN is an Arduino library for a rain sensor (analog).
 
 
 ## Description
 
-The RAIN sensor is a relative simple device. 
+A rain sensor is a relative simple device. 
-It measures the resistance of a number of wires when these are put un a liquid (water)
+It measures the resistance of a number of wires when these are put in a liquid (water)
-The device converts that resistance to a voltage 0..VCC - typical 5V.
+The device converts the resistance to a voltage typical 0 .. 5 Volt.
 The more the wires are covered by the liquid, the higher the voltage.
 
-Furthermore the breakout I used to test had a digital output, which becomes HIGH if a certain
+The breakout I used to test also has a digital output, which goes HIGH if a certain
-threshold (to be set with a potentiometer) was reached.
+threshold (to be set with a potentiometer on the breakout) is reached.
-The meaning / potential of this digi-out for the library is not clear yet.
+The meaning / potential of this digital-out for the library needs to be investigated.
 
 The library is EXPERIMENTAL as it needs more testing. 
-(changes of the interface are possible).
+(changes of the interface are definitely possible).
 
 
 ## Interface
@@ -42,16 +42,27 @@ THis voltage is returned, and also cached for **percentage()** and **getLevel()*
 
 - **float percentage()** returns the last **read()** to a percentage.
 Note one needs to call read() again to get a new value as this uses a cached value.
-- **bool setLevel(uint8_t nr, float voltage)** allows a user to set 5 voltage levels. 
+- **float delta()** returns the delta voltage compared to previous read.
+It give the first derivative of the signal. How fast does it rise.
+- **bool setLevel(uint8_t nr, uint16_t millivolts)** allows a user to set 5 voltage levels in milliVolts.
 - **uint8_t getLevel()**
 Returns the level of the current cached voltage. 
 See example.
 
+The library allows the user to set 5 thresholds or levels for the **getLevel()** function.
+These 5 levels can help to control behaviour at a certain level. 
+Typical levels are almost empty, to almost full and full. 
+The level do not need to be on a linear mapping like 20% steps, if your project need 
+other levels you can define these.
+
+Note it is possible to adjust the levels runTime with **setLevel()**
+
 
 #### MultiMap
 
-One might use the **MultiMap** library to map the voltage read to some
+For a continuous mapping one can use the **MultiMap** library. 
-other, more useful unit.
+It allows to map the voltage to any other useful unit as it can handle 
+even non-linearities well.
 See https://github.com/RobTillaart/MultiMap
 
 
@@ -64,29 +75,39 @@ The examples show the basic working of the functions.
 
 #### Must
 - update documentation
-  - a lot, 
   - links etc.
-- test more
+- add interrupt example for digital output capture.
-  - different salinity
-  - different liquids? which?
-  - how linear is the device?
 
 
 #### Should
-- investigate "a scale of wetness"
+- optimizations
-- add unit-tests
+  - a lot of floats...==> more uint16_t millivolts?
 - add examples.
-  - interrupt example for digital output capture.
-  - multimap example 
 - investigate possibilities of the digital output 
   - how to include
   - example (see above)
-- **float readExt(float voltage)** for external ADC
+- improve the **percentage()** maxVoltage setter?
+  - 2 different meanings of maxVoltage. For ADC and sensor out.
+  - is the device linear? does percentage make sense if it is not?
 
 
 #### Could
-
+- add unit-tests
+- make the number of levels configurable
+  - dynamic array allocation.?
+- **float readExt(float voltage)** for external ADC
+- investigate level-changed "event"
+- investigate: **getLevel()** should it do a read()?
+  - **setForcedRead(bool flag)** + getter
+- investigate "a scale of wetness"
+- investigate
+  - different salinity
+  - different liquids? which?
+  - how linear is the device?
+- **incrLevel(nr, amount = 1)** + **decrLevel(nr, amount = 1)**
+  to allow easier runtime tuning
 
 #### Won't
-
+- example with multiMap
+  - see multiMap library.
 

libraries/rain/examples/rain_delta/rain_delta.ino

@@ -0,0 +1,36 @@
+//
+//    FILE: rain_delta.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo read + delta
+//     URL: https://github.com/RobTillaart/RAIN
+
+
+#include "rain.h"
+
+RAIN  RS(A0);
+
+void setup()
+{
+  Serial.begin(115200);
+  while (!Serial);
+  Serial.println(__FILE__);
+  Serial.print("RAIN_LIB_VERSION: ");
+  Serial.println(RAIN_LIB_VERSION);
+  Serial.println("EXPERIMENTAL:");
+
+  RS.begin(5.000, 1023);
+  Serial.println("READ\tDELTA");
+}
+
+
+void loop()
+{
+  Serial.print(RS.read(), 3);
+  Serial.print('\t');
+  Serial.print(RS.delta(), 1);
+  Serial.print('\n');
+  delay(100);
+}
+
+
+// -- END OF FILE --

libraries/rain/examples/rain_demo/rain_demo.ino

@@ -1,7 +1,7 @@
 //
 //    FILE: rain_demo.ino
 //  AUTHOR: Rob Tillaart
-// PURPOSE: demo
+// PURPOSE: demo read + percentage
 //     URL: https://github.com/RobTillaart/RAIN
 
 

libraries/rain/examples/rain_setLevel/rain_setLevel.ino

@@ -1,7 +1,7 @@
 //
-//    FILE: rain_demo.ino
+//    FILE: rain_setLevel.ino
 //  AUTHOR: Rob Tillaart
-// PURPOSE: demo
+// PURPOSE: demo setLevel + getLevel
 //     URL: https://github.com/RobTillaart/RAIN
 
 
@@ -20,12 +20,13 @@ void setup()
 
   RS.begin(5.000, 1023);
 
-  //  set the levels
+  //  set the 4 levels in milliVolts
-  //  no need to be equi-distant
+  //  they do not need to be equi-distant
-  RS.setLevel(1, 0.25);
+  //  level 0 == 0 volts.
-  RS.setLevel(2, 2.75);
+  RS.setLevel(1, 0250);
-  RS.setLevel(3, 3.25);
+  RS.setLevel(2, 2750);
-  RS.setLevel(4, 3.50);
+  RS.setLevel(3, 3250);
+  RS.setLevel(4, 3500);
 }
 
 
@@ -35,7 +36,7 @@ void loop()
   Serial.print('\t');
   Serial.print(RS.getLevel());
   Serial.print('\n');
-  delay(10);
+  delay(100);
 }
 
 

libraries/rain/examples/rain_setLevel_guard_low/rain_setLevel_guard_low.ino

@@ -0,0 +1,91 @@
+//
+//    FILE: rain_setLevel_guard_low.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo how to control a pump with the sensor.
+//     URL: https://github.com/RobTillaart/RAIN
+
+
+#include "rain.h"
+
+RAIN  RS(A0);
+
+uint32_t lastTime = 0;
+
+const int PUMP_PIN = 6;   //  UNO PWM pin.
+uint8_t prevLevel = -1;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  while (!Serial);
+  Serial.println(__FILE__);
+  Serial.print("RAIN_LIB_VERSION: ");
+  Serial.println(RAIN_LIB_VERSION);
+
+  RS.begin(5.000, 1023);  //  adjust if needed
+
+  //  set the levels in milliVolts
+  //  very low levels need to start the pump quite fast.
+  //  adapt to your needs.
+  RS.setLevel(1,  50);
+  RS.setLevel(2, 100);
+  RS.setLevel(3, 200);
+  RS.setLevel(4, 500);
+
+}
+
+
+void loop()
+{
+  uint32_t now = millis();
+  if (now - lastTime > 1000)
+  {
+    lastTime = now;
+    RS.read();
+    int level = RS.getLevel();
+    switch (level)
+    {
+      case 4:
+        if (prevLevel != level)
+        {
+          Serial.println("Pump speed 100%");
+        }
+        analogWrite(PUMP_PIN, 255);
+        break;
+      case 3:
+        if (prevLevel != level)
+        {
+          Serial.println("Pump speed 90%");
+        }
+        analogWrite(PUMP_PIN, 230);
+        break;
+      case 2:
+        if (prevLevel != level)
+        {
+          Serial.println("Pump speed 75%");
+        }
+        analogWrite(PUMP_PIN, 195);  //  ~75%
+        break;
+      case 1:
+        if (prevLevel != level)
+        {
+          Serial.println("Start pumping");
+        }
+        analogWrite(PUMP_PIN, 130);  //  ~50%
+        break;
+      case 0:
+      default:
+        if (prevLevel != level)
+        {
+          Serial.println("Stop pumping");
+        }
+        analogWrite(PUMP_PIN, 0);
+        break;
+    }
+    prevLevel = level;
+  }
+}
+
+
+// -- END OF FILE --

libraries/rain/keywords.txt

@@ -5,9 +5,12 @@ RAIN	KEYWORD1
 
 # Methods and Functions (KEYWORD2)
 begin	KEYWORD2
+raw	KEYWORD2
 read	KEYWORD2
-percentage	KEYWORD2
 
+percentage	KEYWORD2
+setLevel	KEYWORD2
+getLevel	KEYWORD2
 
 # Constants (LITERAL1)
 RAIN_LIB_VERSION	LITERAL1

libraries/rain/library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/RAIN.git"
   },
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

libraries/rain/library.properties

@@ -1,5 +1,5 @@
 name=RAIN
-version=0.1.0
+version=0.1.1
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for rain sensor (analog).

libraries/rain/rain.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: rain.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2021-12-03
 // PURPOSE: Arduino library for a rain sensor
 //     URL: https://github.com/RobTillaart/RAIN
@@ -43,6 +43,7 @@ float RAIN::raw(uint8_t times)
 
 float RAIN::read(uint8_t times)
 {
+  _previous = _voltage;
   _voltage = raw(times) * _mVstep;
   return _voltage;
 }
@@ -54,20 +55,27 @@ float RAIN::percentage()
 }
 
 
-bool RAIN::setLevel(uint8_t nr, float voltage)
+float RAIN::delta()
+{
+  return _voltage - _previous;
+}
+
+
+bool RAIN::setLevel(uint8_t nr, uint16_t milliVolts)
 {
   if (nr == 0) return false;
   if (nr > 4) return false;
-  _level[nr] = voltage;
+  _level[nr] = milliVolts;
   return true;
 }
 
 
 uint8_t RAIN::getLevel()
 {
+  uint16_t value = _voltage * 1000;
   for (int index = 4; index > 0; index--)
   {
-    if (_voltage >= _level[index]) return index;
+    if (value >= _level[index]) return index;
   }
   return 0;
 }

libraries/rain/rain.h

@@ -33,11 +33,14 @@ public:
   //  ANALYSIS
   //  returns last read value as percentage of maxVoltage.
   //  indicating wetness?
+  //  it assumes / implies linear behaviour
   float    percentage();
+  float    delta();
+
 
   //  level = 1..4 (level 0 == 0 Volt)
   //  user is responsible that values are increasing voltages.
-  bool     setLevel(uint8_t nr, float voltage);
+  bool     setLevel(uint8_t nr, uint16_t milliVolts);
   uint8_t  getLevel();
 
 
@@ -47,7 +50,8 @@ private:
   uint16_t _maxSteps;
   float    _mVstep;
   float    _voltage;
-  float    _level[5] = { 0, 1, 2, 3, 4 };  // default
+  float    _previous;
+  uint16_t _level[5] = { 0, 1000, 2000, 3000, 4000 };  //  millivolts
 };