0.1.0 RAIN

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
+

libraries/rain/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: RobTillaart
+

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

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

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$"
+

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)
+
+

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.

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
+
+

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 --

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 --

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
+
+

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"
+}

libraries/rain/library.properties

@@ -0,0 +1,11 @@
+name=RAIN
+version=0.1.0
+author=Rob Tillaart <rob.tillaart@gmail.com>
+maintainer=Rob Tillaart <rob.tillaart@gmail.com>
+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=

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 --
+

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 --
+

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 <ArduinoUnitTests.h>
+
+#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 --