0.1.1 Vibration

libraries/Vibration/.arduino-ci.yml

@@ -0,0 +1,30 @@
+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:
+    - "printHelpers"

libraries/Vibration/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: RobTillaart
+custom: "https://www.paypal.me/robtillaart"

libraries/Vibration/.github/workflows/arduino-lint.yml

@@ -0,0 +1,13 @@
+name: Arduino-lint
+
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/arduino-lint-action@v1
+        with:
+          library-manager: update
+          compliance: strict

libraries/Vibration/.github/workflows/arduino_test_runner.yml

@@ -0,0 +1,17 @@
+name: Arduino CI
+
+on: [push, pull_request]
+
+jobs:
+  runTest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - run: |
+          gem install arduino_ci
+          arduino_ci.rb

libraries/Vibration/.github/workflows/jsoncheck.yml

@@ -0,0 +1,18 @@
+name: JSON check
+
+on:
+  push:
+    paths:
+      - '**.json'
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - name: json-syntax-check
+        uses: limitusus/json-syntax-check@v2
+        with:
+          pattern: "\\.json$"

libraries/Vibration/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change Log Vibration
+
+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.1] - 2024-09-30
+- initial release
+- rename + add functions
+- rewrite functions to duration.
+- add minimal unit test
+
+
+## [0.1.0] - 2024-04-26
+- initial version
+
+
+

libraries/Vibration/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2024 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/Vibration/README.md

@@ -0,0 +1,122 @@
+
+[![Arduino CI](https://github.com/RobTillaart/Vibration/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+[![Arduino-lint](https://github.com/RobTillaart/Vibration/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/Vibration/actions/workflows/arduino-lint.yml)
+[![JSON check](https://github.com/RobTillaart/Vibration/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/Vibration/actions/workflows/jsoncheck.yml)
+[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/Vibration.svg)](https://github.com/RobTillaart/Vibration/issues)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/Vibration/blob/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/RobTillaart/Vibration.svg?maxAge=3600)](https://github.com/RobTillaart/Vibration/releases)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/Vibration.svg)](https://registry.platformio.org/libraries/robtillaart/Vibration)
+
+
+# Vibration
+
+Arduino library for a vibration / tilt sensor e.g. SW-420, SW-18010P.
+
+
+## Description
+
+**Experimental**
+
+This library is to interact with an analog vibration sensor. 
+Goal is to detect if there is movement or tilt.
+
+Vibration sensors, a.k.a. tilt switches can work in different ways so they are 
+meant for different applications.
+Some have a conducting ball that has a home position and when vibrations occur
+or when tilted it will move out of this position, connecting a switch.
+If the sensor stays tilted the switch can stay connected for longer times. 
+Some of the sensors e.g. SW-18010P, have a spring connected to the ball that forces
+the ball to the home position if there is no vibration. Even in a tilted position.
+
+The library assumes that the sensor connects to VCC when connected, so not connected 
+reads as zero (0).
+However the library uses analogReads so the sensor can e.g. also "load" a capacitor
+which slowly increases the voltage (RC). 
+This allows measuring a first order (relative) magnitude of a vibration.
+
+The different functions of the library might fit more (or less) to your needs.
+If functionality is missing, please open an issue.
+
+
+### Interrupts
+
+The library does not use interrupts to count the pulses of the vibration
+ / tilt sensor. 
+ For now it supports only polling to  see if there is any vibration. 
+As vibrations are relative long in CPU clock cycles, polling a few times
+per second worked well for my needs.
+
+
+### Related
+
+TODO
+
+
+### Tested
+
+Arduino UNO.
+
+
+## Interface
+
+```cpp
+#include "Vibration.h"
+```
+
+### Constructor
+
+- **VibrationSensor(uint8_t analogPin)** constructor, set the analogPin to use.
+- **bool begin()** place holder for now.
+
+### Measurements
+
+- **float zeroCount(uint32_t duration, uint16_t noise = 10)** read the sensor, 
+count the times the value is zero.
+Returns the percentage reads as below or equal to noise level.
+This noise level has a default value of 10.
+- **uint16_t average(uint32_t duration)** reads the sensor for a defined duration,
+but at least once. Returns the average of multiple reads.
+- **uint16_t poll(uint32_t duration)** polls the sensor for a given duration
+(in millis), with a minimum of one sample. 
+The function returns the maximum value sampled.
+Note this code is blocking for at least duration milliseconds.
+
+
+## Future
+
+
+#### Must
+
+- improve documentation
+
+#### Should
+
+
+#### Could
+
+- **bool isVibrating(uint8_t samples)** ?
+- use (fast) external ADC.
+  - https://github.com/RobTillaart/ADS1x15
+  - https://github.com/RobTillaart/MCPADC
+- add delay between average reads (option, blocks even longer).
+- default values parameters?
+- investigate interrupts.
+  - platform specific probably
+- investigate the acquisition time ==> differs per board.
+- refactor interface - 0.2.0
+  - measure(duration);
+  - result functions.
+
+#### Wont
+
+
+## Support
+
+If you appreciate my libraries, you can support the development and maintenance.
+Improve the quality of the libraries by providing issues and Pull Requests, or
+donate through PayPal or GitHub sponsors.
+
+Thank you,
+
+

libraries/Vibration/Vibration.h

@@ -0,0 +1,93 @@
+#pragma once
+//
+//    FILE: Vibration.h
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.1
+//    DATE: 2024-04-24
+// PURPOSE: Arduino library for a vibration / tilt sensor e.g. SW-420, SW-18010P.
+//     URL: https://github.com/RobTillaart/Vibration
+
+
+#include "Arduino.h"
+
+#define VIBRATION_LIB_VERSION                 (F("0.1.1"))
+
+
+class VibrationSensor
+{
+public:
+  explicit VibrationSensor(uint8_t analogPin)
+  {
+    _analogPin = analogPin;
+  }
+
+
+  bool begin()
+  {
+    // what to do here?
+    return true;
+  }
+
+
+  float zeroCount(uint32_t duration, uint16_t noise = 10)
+  {
+    uint16_t count = 0;
+    uint16_t total = 0;
+    uint32_t start = millis();
+    do
+    {
+      if (analogRead(_analogPin) <= noise) count++;
+      total++;
+    }
+    while ((millis() - start) < duration);
+    return 100.0 * count / total;
+  }
+
+
+  float average(uint32_t duration)
+  {
+    float sum = 0;
+    uint32_t samples = 0;
+    uint32_t start = millis();
+    do
+    {
+      sum += analogRead(_analogPin);
+      samples++;
+    }
+    while ((millis() - start) < duration);
+    if (samples > 1) sum /= samples;
+    return sum;
+  }
+
+
+  uint16_t poll(uint32_t duration)
+  {
+    uint16_t maxValue = 0;
+    uint32_t start = millis();
+    do
+    {
+      uint16_t val = analogRead(_analogPin);
+      if (val > maxValue) maxValue = val;
+    }
+    while ((millis() - start) < duration);
+    return maxValue;
+  }
+
+
+protected:
+  uint8_t _analogPin;
+  uint16_t _noiseLevel = 0;  //  to be detected automatically.
+};
+
+
+/*
+
+interrupt count / timing?
+
+analog for signal strength?
+
+*/
+
+
+//  -- END OF FILE --
+

libraries/Vibration/examples/Vibration_average/Vibration_average.ino

@@ -0,0 +1,29 @@
+//
+//    FILE: Vibration_average.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo
+//     URL: https://github.com/RobTillaart/Vibration
+
+
+#include "Vibration.h"
+
+VibrationSensor VBS(A0);
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.print(__FILE__);
+  Serial.print("VIBRATION_LIB_VERSION: ");
+  Serial.println(VIBRATION_LIB_VERSION);
+
+  Serial.println("done...\n");
+}
+
+
+void loop()
+{
+  Serial.println(VBS.average(1000));
+}
+
+
+//  -- END OF FILE --

libraries/Vibration/examples/Vibration_poll/Vibration_poll.ino

@@ -0,0 +1,30 @@
+//
+//    FILE: Vibration_poll.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo
+//     URL: https://github.com/RobTillaart/Vibration
+
+
+#include "Vibration.h"
+
+VibrationSensor VBS(A0);
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println();
+  Serial.println(__FILE__);
+  Serial.print("VIBRATION_LIB_VERSION: ");
+  Serial.println(VIBRATION_LIB_VERSION);
+
+  Serial.println("done...\n");
+}
+
+
+void loop()
+{
+  Serial.println(VBS.poll(1000));
+}
+
+
+//  -- END OF FILE --

libraries/Vibration/examples/Vibration_zeroCount/Vibration_zeroCount.ino

@@ -0,0 +1,33 @@
+//
+//    FILE: Vibration_zeroCount.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo
+//     URL: https://github.com/RobTillaart/Vibration
+
+
+#include "Vibration.h"
+
+VibrationSensor VBS(A0);
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println();
+  Serial.println(__FILE__);
+  Serial.print("VIBRATION_LIB_VERSION: ");
+  Serial.println(VIBRATION_LIB_VERSION);
+
+  Serial.println("done...\n");
+}
+
+
+void loop()
+{
+  //  measure for one second
+  //  percentage with one decimal
+  Serial.print("ZERO: \t");
+  Serial.println(VBS.zeroCount(1000), 1);
+}
+
+
+//  -- END OF FILE --

libraries/Vibration/keywords.txt

@@ -0,0 +1,17 @@
+# Syntax Colouring Map For Vibration
+
+# Data types (KEYWORD1)
+VibrationSensor	KEYWORD1
+
+
+# Methods and Functions (KEYWORD2)
+begin	KEYWORD2
+
+zeroCount	KEYWORD2
+average	KEYWORD2
+poll	KEYWORD2
+
+
+# Constants (LITERAL1)
+VIBRATION_LIB_VERSION	LITERAL1
+

libraries/Vibration/library.json

@@ -0,0 +1,23 @@
+{
+  "name": "Vibration",
+  "keywords": "Vibration, SW-420, SW-18010P, tilt",
+  "description": "Arduino library for a vibration / tilt sensor.",
+  "authors":
+  [
+    {
+      "name": "Rob Tillaart",
+      "email": "Rob.Tillaart@gmail.com",
+      "maintainer": true
+    }
+  ],
+  "repository":
+  {
+    "type": "git",
+    "url": "https://github.com/RobTillaart/Vibration.git"
+  },
+  "version": "0.1.1",
+  "license": "MIT",
+  "frameworks": "*",
+  "platforms": "*",
+  "headers": "Vibration.h"
+}

libraries/Vibration/library.properties

@@ -0,0 +1,11 @@
+name=Vibration
+version=0.1.1
+author=Rob Tillaart <rob.tillaart@gmail.com>
+maintainer=Rob Tillaart <rob.tillaart@gmail.com>
+sentence=Arduino library for a vibration / tilt sensor.
+paragraph=SW-420, SW-18010P, tilt
+category=Sensors
+url=https://github.com/RobTillaart/Vibration
+architectures=*
+includes=Vibration.h
+depends=

libraries/Vibration/test/unit_test_001.cpp

@@ -0,0 +1,54 @@
+//
+//    FILE: unit_test_001.cpp
+//  AUTHOR: Rob Tillaart
+//    DATE: 2024-10-01
+// PURPOSE: unit tests for the Vibration library
+//     URL: https://github.com/RobTillaart/Vibration
+//          https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md
+//
+
+// supported assertions
+// https://github.com/Arduino-CI/arduino_ci/blob/master/cpp/unittest/Assertion.h#L33-L42
+// ----------------------------
+// assertEqual(expected, actual)
+// assertNotEqual(expected, actual)
+// assertLess(expected, actual)
+// assertMore(expected, actual)
+// assertLessOrEqual(expected, actual)
+// assertMoreOrEqual(expected, actual)
+// assertTrue(actual)
+// assertFalse(actual)
+// assertNull(actual)
+// assertNotNull(actual)
+
+#include <ArduinoUnitTests.h>
+
+
+#include "Arduino.h"
+#include "Vibration.h"
+
+
+unittest_setup()
+{
+  fprintf(stderr, "VIBRATION_LIB_VERSION: %s\n", (char *) VIBRATION_LIB_VERSION);
+}
+
+
+unittest_teardown()
+{
+}
+
+
+unittest(test_constructor)
+{
+  VibrationSensor vib(A2);
+
+  assertTrue(vib.begin());
+}
+
+
+unittest_main()
+
+
+//  -- END OF FILE --
+