RAIN
RAIN is an Arduino library for a rain sensor (analog).
Description
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. The more the wires are covered by the liquid, the higher the voltage.
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.
The library is EXPERIMENTAL as it needs more testing. (changes of the interface are definitely possible).
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.
- 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
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. See https://github.com/RobTillaart/MultiMap
Operation
The examples show the basic working of the functions.
Future
Must
- update documentation
- links etc.
- add interrupt example for digital output capture.
Should
- optimizations
- a lot of floats...==> more uint16_t millivolts?
- add examples.
- investigate possibilities of the digital output
- how to include
- example (see above)
- 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.