From 4ed681cb0fe6f4e39df68f9f9a4e4fbe7896b46f Mon Sep 17 00:00:00 2001 From: rob tillaart Date: Sun, 4 Dec 2022 17:55:37 +0100 Subject: [PATCH] 0.1.0 RAIN --- libraries/rain/.arduino-ci.yml | 28 ++++++ libraries/rain/.github/FUNDING.yml | 4 + .../rain/.github/workflows/arduino-lint.yml | 13 +++ .../.github/workflows/arduino_test_runner.yml | 17 ++++ .../rain/.github/workflows/jsoncheck.yml | 18 ++++ libraries/rain/CHANGELOG.md | 16 ++++ libraries/rain/LICENSE | 21 +++++ libraries/rain/README.md | 92 +++++++++++++++++++ .../rain/examples/rain_demo/rain_demo.ino | 35 +++++++ .../examples/rain_setLevel/rain_setLevel.ino | 42 +++++++++ libraries/rain/keywords.txt | 15 +++ libraries/rain/library.json | 23 +++++ libraries/rain/library.properties | 11 +++ libraries/rain/rain.cpp | 77 ++++++++++++++++ libraries/rain/rain.h | 55 +++++++++++ libraries/rain/test/unit_test_001.cpp | 49 ++++++++++ 16 files changed, 516 insertions(+) create mode 100644 libraries/rain/.arduino-ci.yml create mode 100644 libraries/rain/.github/FUNDING.yml create mode 100644 libraries/rain/.github/workflows/arduino-lint.yml create mode 100644 libraries/rain/.github/workflows/arduino_test_runner.yml create mode 100644 libraries/rain/.github/workflows/jsoncheck.yml create mode 100644 libraries/rain/CHANGELOG.md create mode 100644 libraries/rain/LICENSE create mode 100644 libraries/rain/README.md create mode 100644 libraries/rain/examples/rain_demo/rain_demo.ino create mode 100644 libraries/rain/examples/rain_setLevel/rain_setLevel.ino create mode 100644 libraries/rain/keywords.txt create mode 100644 libraries/rain/library.json create mode 100644 libraries/rain/library.properties create mode 100644 libraries/rain/rain.cpp create mode 100644 libraries/rain/rain.h create mode 100644 libraries/rain/test/unit_test_001.cpp diff --git a/libraries/rain/.arduino-ci.yml b/libraries/rain/.arduino-ci.yml new file mode 100644 index 00000000..77a333f9 --- /dev/null +++ b/libraries/rain/.arduino-ci.yml @@ -0,0 +1,28 @@ +platforms: + rpipico: + board: rp2040:rp2040:rpipico + package: rp2040:rp2040 + gcc: + features: + defines: + - ARDUINO_ARCH_RP2040 + warnings: + flags: + +packages: + rp2040:rp2040: + url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json + +compile: + # Choosing to run compilation tests on 2 different Arduino platforms + platforms: + - uno + # - due + # - zero + # - leonardo + - m4 + - esp32 + - esp8266 + # - mega2560 + - rpipico + diff --git a/libraries/rain/.github/FUNDING.yml b/libraries/rain/.github/FUNDING.yml new file mode 100644 index 00000000..90d9ab4c --- /dev/null +++ b/libraries/rain/.github/FUNDING.yml @@ -0,0 +1,4 @@ +# These are supported funding model platforms + +github: RobTillaart + diff --git a/libraries/rain/.github/workflows/arduino-lint.yml b/libraries/rain/.github/workflows/arduino-lint.yml new file mode 100644 index 00000000..b2ca058c --- /dev/null +++ b/libraries/rain/.github/workflows/arduino-lint.yml @@ -0,0 +1,13 @@ + +name: Arduino-lint + +on: [push, pull_request] +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: arduino/arduino-lint-action@v1 + with: + library-manager: update + compliance: strict diff --git a/libraries/rain/.github/workflows/arduino_test_runner.yml b/libraries/rain/.github/workflows/arduino_test_runner.yml new file mode 100644 index 00000000..096b975b --- /dev/null +++ b/libraries/rain/.github/workflows/arduino_test_runner.yml @@ -0,0 +1,17 @@ +--- +name: Arduino CI + +on: [push, pull_request] + +jobs: + runTest: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.6 + - run: | + gem install arduino_ci + arduino_ci.rb diff --git a/libraries/rain/.github/workflows/jsoncheck.yml b/libraries/rain/.github/workflows/jsoncheck.yml new file mode 100644 index 00000000..04603d08 --- /dev/null +++ b/libraries/rain/.github/workflows/jsoncheck.yml @@ -0,0 +1,18 @@ +name: JSON check + +on: + push: + paths: + - '**.json' + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: json-syntax-check + uses: limitusus/json-syntax-check@v1 + with: + pattern: "\\.json$" + diff --git a/libraries/rain/CHANGELOG.md b/libraries/rain/CHANGELOG.md new file mode 100644 index 00000000..bb047a12 --- /dev/null +++ b/libraries/rain/CHANGELOG.md @@ -0,0 +1,16 @@ +# Change Log RAIN + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/) +and this project adheres to [Semantic Versioning](http://semver.org/). + + +## [0.1.0] - 2022-12-03 +- initial version + + +## [0.0.1] - 2021-12-?? +- experimental version (not released) + + diff --git a/libraries/rain/LICENSE b/libraries/rain/LICENSE new file mode 100644 index 00000000..5777550e --- /dev/null +++ b/libraries/rain/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2021-2022 Rob Tillaart + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/libraries/rain/README.md b/libraries/rain/README.md new file mode 100644 index 00000000..7564caf4 --- /dev/null +++ b/libraries/rain/README.md @@ -0,0 +1,92 @@ + +[![Arduino CI](https://github.com/RobTillaart/RAIN/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci) +[![Arduino-lint](https://github.com/RobTillaart/RAIN/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/RAIN/actions/workflows/arduino-lint.yml) +[![JSON check](https://github.com/RobTillaart/RAIN/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/RAIN/actions/workflows/jsoncheck.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/RAIN/blob/master/LICENSE) +[![GitHub release](https://img.shields.io/github/release/RobTillaart/RAIN.svg?maxAge=3600)](https://github.com/RobTillaart/RAIN/releases) + + +# RAIN + +Arduino library for rain sensor (analog). + + +## Description + +The RAIN sensor is a relative simple device. +It measures the resistance of a number of wires when these are put un a liquid (water) +The device converts that resistance to a voltage 0..VCC - typical 5V. +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 +threshold (to be set with a potentiometer) was reached. +The meaning / potential of this digi-out for the library is not clear yet. + +The library is EXPERIMENTAL as it needs more testing. +(changes of the interface are 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. +- **bool setLevel(uint8_t nr, float voltage)** allows a user to set 5 voltage levels. +- **uint8_t getLevel()** +Returns the level of the current cached voltage. +See example. + + +#### MultiMap + +One might use the **MultiMap** library to map the voltage read to some +other, more useful unit. +See https://github.com/RobTillaart/MultiMap + + +## Operation + +The examples show the basic working of the functions. + + +## Future + +#### Must +- update documentation + - a lot, + - links etc. +- test more + - different salinity + - different liquids? which? + - how linear is the device? + + +#### Should +- investigate "a scale of wetness" +- add unit-tests +- 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 + + +#### Could + + +#### Won't + + diff --git a/libraries/rain/examples/rain_demo/rain_demo.ino b/libraries/rain/examples/rain_demo/rain_demo.ino new file mode 100644 index 00000000..e6207504 --- /dev/null +++ b/libraries/rain/examples/rain_demo/rain_demo.ino @@ -0,0 +1,35 @@ +// +// FILE: rain_demo.ino +// AUTHOR: Rob Tillaart +// PURPOSE: demo +// 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); +} + + +void loop() +{ + Serial.print(RS.read(), 3); + Serial.print('\t'); + Serial.print(RS.percentage(), 1); + Serial.print('\n'); + delay(1000); +} + + +// -- END OF FILE -- diff --git a/libraries/rain/examples/rain_setLevel/rain_setLevel.ino b/libraries/rain/examples/rain_setLevel/rain_setLevel.ino new file mode 100644 index 00000000..5780ba3c --- /dev/null +++ b/libraries/rain/examples/rain_setLevel/rain_setLevel.ino @@ -0,0 +1,42 @@ +// +// FILE: rain_demo.ino +// AUTHOR: Rob Tillaart +// PURPOSE: demo +// 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); + + // set the levels + // no need to be equi-distant + RS.setLevel(1, 0.25); + RS.setLevel(2, 2.75); + RS.setLevel(3, 3.25); + RS.setLevel(4, 3.50); +} + + +void loop() +{ + Serial.print(RS.read(), 3); + Serial.print('\t'); + Serial.print(RS.getLevel()); + Serial.print('\n'); + delay(10); +} + + +// -- END OF FILE -- diff --git a/libraries/rain/keywords.txt b/libraries/rain/keywords.txt new file mode 100644 index 00000000..136ca202 --- /dev/null +++ b/libraries/rain/keywords.txt @@ -0,0 +1,15 @@ +# Syntax Colouring Map For RAIN + +# Data types (KEYWORD1) +RAIN KEYWORD1 + +# Methods and Functions (KEYWORD2) +begin KEYWORD2 +read KEYWORD2 +percentage KEYWORD2 + + +# Constants (LITERAL1) +RAIN_LIB_VERSION LITERAL1 + + diff --git a/libraries/rain/library.json b/libraries/rain/library.json new file mode 100644 index 00000000..923f2b29 --- /dev/null +++ b/libraries/rain/library.json @@ -0,0 +1,23 @@ +{ + "name": "RAIN", + "keywords": "RAIN, wet", + "description": "Arduino library for rain sensor. (analog)", + "authors": + [ + { + "name": "Rob Tillaart", + "email": "Rob.Tillaart@gmail.com", + "maintainer": true + } + ], + "repository": + { + "type": "git", + "url": "https://github.com/RobTillaart/RAIN.git" + }, + "version": "0.1.0", + "license": "MIT", + "frameworks": "arduino", + "platforms": "*", + "headers": "rain.h" +} diff --git a/libraries/rain/library.properties b/libraries/rain/library.properties new file mode 100644 index 00000000..378864ea --- /dev/null +++ b/libraries/rain/library.properties @@ -0,0 +1,11 @@ +name=RAIN +version=0.1.0 +author=Rob Tillaart +maintainer=Rob Tillaart +sentence=Arduino library for rain sensor (analog). +paragraph=wet, wetness. +category=Signal Input/Output +url=https://github.com/RobTillaart/RAIN +architectures=* +includes=rain.h +depends= diff --git a/libraries/rain/rain.cpp b/libraries/rain/rain.cpp new file mode 100644 index 00000000..da423915 --- /dev/null +++ b/libraries/rain/rain.cpp @@ -0,0 +1,77 @@ +// +// FILE: rain.cpp +// AUTHOR: Rob Tillaart +// VERSION: 0.1.0 +// DATE: 2021-12-03 +// PURPOSE: Arduino library for a rain sensor +// URL: https://github.com/RobTillaart/RAIN +// https://www.tinytronics.nl/shop/nl/sensoren/vloeistof/regensensor + + +#include "rain.h" + +RAIN::RAIN(uint8_t port) +{ + _port = port; + _maxVoltage = 5; + _maxSteps = 1023; +} + + +bool RAIN::begin(float maxVoltage, uint16_t maxSteps) +{ + _maxVoltage = maxVoltage; + _maxSteps = maxSteps; + _mVstep = _maxVoltage / _maxSteps; + read(); + return true; +} + + +float RAIN::raw(uint8_t times) +{ + if (times == 0) times = 1; + float sum = 0; + for (int i = 0; i < times; i++) + { + sum += analogRead(_port); + } + if (times > 1) sum /= times; + return sum; +} + + +float RAIN::read(uint8_t times) +{ + _voltage = raw(times) * _mVstep; + return _voltage; +} + + +float RAIN::percentage() +{ + return _voltage * 100.0 / _maxVoltage; +} + + +bool RAIN::setLevel(uint8_t nr, float voltage) +{ + if (nr == 0) return false; + if (nr > 4) return false; + _level[nr] = voltage; + return true; +} + + +uint8_t RAIN::getLevel() +{ + for (int index = 4; index > 0; index--) + { + if (_voltage >= _level[index]) return index; + } + return 0; +} + + +// -- END OF FILE -- + diff --git a/libraries/rain/rain.h b/libraries/rain/rain.h new file mode 100644 index 00000000..e0a14d9e --- /dev/null +++ b/libraries/rain/rain.h @@ -0,0 +1,55 @@ +#pragma once +// +// FILE: rain.h +// AUTHOR: Rob Tillaart +// VERSION: 0.1.0 +// DATE: 2022-11-23 +// PURPOSE: Arduino library for rain sensor (analog). +// URL: https://github.com/RobTillaart/RAIN +// https://www.tinytronics.nl/shop/nl/sensoren/vloeistof/regensensor + + +#include "Arduino.h" + + +#define RAIN_LIB_VERSION (F("0.1.0")) + + +class RAIN +{ +public: + RAIN(uint8_t port); + + // set the ADC parameters + // can be changed runtime, e.g if voltage fluctuates. + bool begin(float maxVoltage, uint16_t maxSteps); + + // returns steps + float raw(uint8_t times = 1); + // returns voltage + float read(uint8_t times = 1); + + + // ANALYSIS + // returns last read value as percentage of maxVoltage. + // indicating wetness? + float percentage(); + + // level = 1..4 (level 0 == 0 Volt) + // user is responsible that values are increasing voltages. + bool setLevel(uint8_t nr, float voltage); + uint8_t getLevel(); + + +private: + uint8_t _port; + float _maxVoltage; + uint16_t _maxSteps; + float _mVstep; + float _voltage; + float _level[5] = { 0, 1, 2, 3, 4 }; // default +}; + + +// -- END OF FILE -- + diff --git a/libraries/rain/test/unit_test_001.cpp b/libraries/rain/test/unit_test_001.cpp new file mode 100644 index 00000000..dc110aa2 --- /dev/null +++ b/libraries/rain/test/unit_test_001.cpp @@ -0,0 +1,49 @@ +// +// FILE: unit_test_001.cpp +// AUTHOR: Rob Tillaart +// DATE: 2022-12-03 +// PURPOSE: unit tests for the RAIN sensor +// https://github.com/RobTillaart/RAIN +// https://www.adafruit.com/product/2857 +// https://www.tinytronics.nl/shop/nl/sensoren/vloeistof/regensensor +// + +// supported assertions +// ---------------------------- +// assertEqual(expected, actual) +// assertNotEqual(expected, actual) +// assertLess(expected, actual) +// assertMore(expected, actual) +// assertLessOrEqual(expected, actual) +// assertMoreOrEqual(expected, actual) +// assertTrue(actual) +// assertFalse(actual) +// assertNull(actual) + + +#include + +#include "Arduino.h" +#include "rain.h" + + +unittest_setup() +{ + fprintf(stderr, "RAIN_LIB_VERSION: %s\n", (char *) RAIN_LIB_VERSION); +} + +unittest_teardown() +{ +} + + +unittest(test_constants) +{ + assertEqual(1, 1); +} + + +unittest_main() + + +// -- END OF FILE --