2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
|
|
|
[](https://github.com/RobTillaart/RAIN/actions/workflows/arduino-lint.yml)
|
|
|
|
|
[](https://github.com/RobTillaart/RAIN/actions/workflows/jsoncheck.yml)
|
|
|
|
|
[](https://github.com/RobTillaart/RAIN/blob/master/LICENSE)
|
|
|
|
|
[](https://github.com/RobTillaart/RAIN/releases)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# RAIN
|
|
|
|
|
|
2022-12-06 05:26:48 -05:00
|
|
|
RAIN is an Arduino library for a rain sensor (analog).
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
## Description
|
|
|
|
|
|
2022-12-06 05:26:48 -05:00
|
|
|
A rain sensor is a relative simple device.
|
|
|
|
|
It measures the resistance of a number of wires when these are put in a liquid (water)
|
|
|
|
|
The device converts the resistance to a voltage typical 0 .. 5 Volt.
|
2022-12-04 11:55:37 -05:00
|
|
|
The more the wires are covered by the liquid, the higher the voltage.
|
|
|
|
|
|
2022-12-06 05:26:48 -05:00
|
|
|
The breakout I used to test also has a digital output, which goes HIGH if a certain
|
|
|
|
|
threshold (to be set with a potentiometer on the breakout) is reached.
|
|
|
|
|
The meaning / potential of this digital-out for the library needs to be investigated.
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
The library is EXPERIMENTAL as it needs more testing.
|
2022-12-06 05:26:48 -05:00
|
|
|
(changes of the interface are definitely possible).
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
## Interface
|
|
|
|
|
|
|
|
|
|
- **RAIN(uint8_t port)** constructor.
|
|
|
|
|
port is the internal analog port to use.
|
|
|
|
|
- **bool begin(float maxVoltage, uint16_t maxSteps)** sets the ADC parameters.
|
|
|
|
|
Allows to be changed runtime, e.g. if voltage fluctuates the math can be adapted by calling **begin()** again.
|
|
|
|
|
Might be a separate **setVoltage()** is more efficient.
|
|
|
|
|
- **float raw(uint8_t times = 1)** makes 1 or more measurements and averages them.
|
|
|
|
|
returned value is the average number of ADC steps.
|
|
|
|
|
- **float read(uint8_t times = 1)** makes 1 or more measurements, averages them and convert the average to a voltage.
|
|
|
|
|
THis voltage is returned, and also cached for **percentage()** and **getLevel()**.
|
|
|
|
|
|
|
|
|
|
#### Analysis
|
|
|
|
|
|
|
|
|
|
- **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.
|
2022-12-06 05:26:48 -05:00
|
|
|
- **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()**
|
2022-12-04 11:55:37 -05:00
|
|
|
Returns the level of the current cached voltage.
|
|
|
|
|
See example.
|
|
|
|
|
|
2022-12-06 05:26:48 -05:00
|
|
|
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()**
|
|
|
|
|
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
#### MultiMap
|
|
|
|
|
|
2022-12-06 05:26:48 -05:00
|
|
|
For a continuous mapping one can use the **MultiMap** library.
|
|
|
|
|
It allows to map the voltage to any other useful unit as it can handle
|
|
|
|
|
even non-linearities well.
|
2022-12-04 11:55:37 -05:00
|
|
|
See https://github.com/RobTillaart/MultiMap
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Operation
|
|
|
|
|
|
|
|
|
|
The examples show the basic working of the functions.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Future
|
|
|
|
|
|
|
|
|
|
#### Must
|
|
|
|
|
- update documentation
|
|
|
|
|
- links etc.
|
2022-12-06 05:26:48 -05:00
|
|
|
- add interrupt example for digital output capture.
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Should
|
2022-12-06 05:26:48 -05:00
|
|
|
- optimizations
|
|
|
|
|
- a lot of floats...==> more uint16_t millivolts?
|
2022-12-04 11:55:37 -05:00
|
|
|
- add examples.
|
|
|
|
|
- investigate possibilities of the digital output
|
|
|
|
|
- how to include
|
|
|
|
|
- example (see above)
|
2022-12-06 05:26:48 -05:00
|
|
|
- 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?
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Could
|
2022-12-06 05:26:48 -05:00
|
|
|
- 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
|
2022-12-04 11:55:37 -05:00
|
|
|
|
|
|
|
|
#### Won't
|
2022-12-06 05:26:48 -05:00
|
|
|
- example with multiMap
|
|
|
|
|
- see multiMap library.
|
2022-12-04 11:55:37 -05:00
|
|
|
|
