add rotaryDecoder

Author: RobTillaart

libraries/rotaryDecoder/.arduino-ci.yml

@@ -0,0 +1,7 @@
+compile:
+ # Choosing to run compilation tests on 2 different Arduino platforms
+ platforms:
+ - uno
+ - leonardo
+ - due
+ - zero

libraries/rotaryDecoder/.github/workflows/arduino_test_runner.yml

@@ -0,0 +1,13 @@
+---
+name: Arduino CI
+
+on: [push, pull_request]
+
+jobs:
+ arduino_ci:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v2
+ - uses: Arduino-CI/action@master
+ # Arduino-CI/action@v0.1.1

libraries/rotaryDecoder/.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/rotaryDecoder/LICENSE

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

@@ -0,0 +1,77 @@
+
+[![Arduino CI](https://github.com/RobTillaart/rotaryDecoder/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/rotaryDecoder/blob/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/RobTillaart/rotaryDecoder.svg?maxAge=3600)](https://github.com/RobTillaart/rotaryDecoder/releases)
+
+
+# rotaryDecoder
+
+Arduino library for a PCF8574 based rotary decoder - supports 4 RE.
+
+
+## Description
+
+Experimental - not tested yet
+
+## Interface
+
+- **rotaryDecoder(const int8_t address, TwoWire \*wire = Wire);**
+- **bool begin(uint8_t sda, uint8_t scl, uint8_t cnt = 4)** ESP32 ea initializes the class.
+sets I2C pins.
+cnt is the number of rotary encoders connected.
+returns true if the PCF8574 is on the I2C bus.
+- **bool begin(uint8_t cnt = 4)** UNO ea. initializes the class. 
+cnt is the number of rotary encoders connected.
+returns true if the PCF8574 is on the I2C bus.
+- **bool isConnected()** returns true if the PCF8574 is on the I2C bus.
+
+## Core functions
+
+- **void readInitialState()** read the inital state of the 4 rotary encoders. typically called in setup only, or after a sleep e.g. in combination with **setValue()**
+- **bool checkChange()** polling to see if one or more RE have changed, without updating the counters.
+- **void update()** update the internal counters of the RE. These will add +1 or -1 depending on direction. 
+- **void updateSingle()** update the internal counters of the RE. This will add +1 +2 or +3 as it assumes that the rotary encoder only goes into a single direction. 
+
+## Counters
+
+- **uint32_t getValue(uint8_r re)** returns the RE counter.
+- **void setValue(uint8_r re, uint32_t val = 0)** (re)set the internal counter to val, default 0
+
+
+## Debugging
+
+- **int8_t getLastPosition(uint8_r re)**
+
+
+## Performance
+
+As the decoder is based upon a PCF8574, a I2C device, the performance is affected by the 
+clockspeed of the I2C bus. All four core functions have one call to **\_read()** which is the most expensive part.
+
+Early tests gave the following indicative times (Arduino UNO) for the **update()** 
+function (with no updates it is ~8 us faster). Note that above 500KHz the gain becomes less
+while reliability of signal decreases. (500KHz is ~3x faster than 100 KHz)
+
+| I2C speed | time (us) | delta | %% |
+|:---------:|:---------:|:-----:|:-----:|
+| 100 KHz | 247 | | |
+| 200 KHz | 146 | 99 | 40% |
+| 300 KHz | 110 | 36 | 24% |
+| 400 KHz | 95 | 15 | 14% | preferred max
+| 500 KHz | 84 | 11 | 12% |
+| 600 KHz | 79 | 5 | 6% |
+| 700 KHz | 73 | 6 | 8% |
+
+At @400KHz it can update 4 rotary encoders in ~100us. 
+At a 50% update percentage this implies a max of about 
+5000 **update()** calls per second in theory 
+**to be tested in practice**
+
+Note that a high speed drill goes up to 30000 RPM = 500 RPS = 2000 interrupts per second, 
+assuming 4 pulses == 360°. (not tested)
+
+
+## Operational
+
+See examples..
+

libraries/rotaryDecoder/examples/rotaryDecoder_demo_interrupt/rotaryDecoder_demo_interrupt.ino

@@ -0,0 +1,71 @@
+//
+// FILE: rotaryDecoder_demo_interrupt.ino
+// AUTHOR: Rob Tillaart
+// DATE: 2021-05-08
+//
+// PUPROSE: demo
+
+// connect up to 4 rotary encoders to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO
+// --------------------------------------
+// pin A pin 0
+// pin B pin 1
+// .... .... (up to 4 RE)
+//
+// SDA A4
+// SCL A5
+// INT 2
+//
+
+
+#include "Wire.h"
+#include "rotaryDecoder.h"
+
+rotaryDecoder decoder(0x20);
+
+volatile bool flag = false;
+
+void moved()
+{
+ flag = true;
+}
+
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+ Serial.print("ROTARY_DECODER_LIB_VERSION:\t");
+ Serial.println(ROTARY_DECODER_LIB_VERSION);
+
+ pinMode(2, INPUT_PULLUP);
+ attachInterrupt(0, moved, FALLING);
+ flag = false;
+
+ Wire.begin();
+ Wire.setClock(100000);
+ decoder.begin(4);
+ decoder.readInitialState();
+}
+
+
+void loop()
+{
+ if (flag)
+ {
+ decoder.update();
+ flag = false;
+ for (uint8_t i = 0; i < 4; i++)
+ {
+ Serial.print("\t");
+ Serial.print(decoder.getValue(i));
+ }
+ Serial.println();
+ }
+
+ // other tasks...
+}
+
+
+// -- END OF FILE --

libraries/rotaryDecoder/examples/rotaryDecoder_demo_polling/rotaryDecoder_demo_polling.ino

@@ -0,0 +1,56 @@
+//
+// FILE: rotaryDecoder_demo_polling.ino
+// AUTHOR: Rob Tillaart
+// DATE: 2021-05-08
+//
+// PUPROSE: demo
+
+// connect up to 4 rotary encoders to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO
+// --------------------------------------
+// pin A pin 0
+// pin B pin 1
+// .... .... (up to 4 RE)
+//
+// SDA A4
+// SCL A5
+//
+
+#include "Wire.h"
+#include "rotaryDecoder.h"
+
+rotaryDecoder decoder(0x20);
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+ Serial.print("ROTARY_DECODER_LIB_VERSION:\t");
+ Serial.println(ROTARY_DECODER_LIB_VERSION);
+
+ Wire.begin();
+ Wire.setClock(100000);
+ decoder.begin(4);
+ decoder.readInitialState();
+}
+
+
+void loop()
+{
+ if (decoder.checkChange())
+ {
+ decoder.update();
+ for (uint8_t i = 0; i < 4; i++)
+ {
+ Serial.print("\t");
+ Serial.print(decoder.getValue(i));
+ }
+ Serial.println();
+ }
+
+ // other tasks...
+}
+
+
+// -- END OF FILE --

libraries/rotaryDecoder/examples/rotaryDecoder_demo_simple/rotaryDecoder_demo_simple.ino

@@ -0,0 +1,56 @@
+//
+// FILE: rotaryDecoder_demo_simple.ino
+// AUTHOR: Rob Tillaart
+// DATE: 2021-05-08
+//
+// PUPROSE: demo
+
+// connect up to 4 rotary encoders to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO
+// --------------------------------------
+// pin A pin 0
+// pin B pin 1
+// .... .... (up to 4 RE)
+//
+// SDA A4
+// SCL A5
+//
+
+#include "Wire.h"
+#include "rotaryDecoder.h"
+
+rotaryDecoder decoder(0x20);
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+ Serial.print("ROTARY_DECODER_LIB_VERSION:\t");
+ Serial.println(ROTARY_DECODER_LIB_VERSION);
+
+ Wire.begin();
+ Wire.setClock(100000);
+ decoder.begin(4);
+ decoder.readInitialState();
+}
+
+
+void loop()
+{
+ // if one of the counters is updated, print them.
+ if (decoder.update())
+ {
+ for (uint8_t i = 0; i < 4; i++)
+ {
+ Serial.print("\t");
+ Serial.print(decoder.getValue(i));
+ }
+ Serial.println();
+ }
+
+ // other tasks...
+}
+
+
+// -- END OF FILE --

libraries/rotaryDecoder/examples/rotaryDecoder_demo_single/rotaryDecoder_demo_single.ino

@@ -0,0 +1,58 @@
+//
+// FILE: rotaryDecoder_demo_single.ino
+// AUTHOR: Rob Tillaart
+// DATE: 2021-05-08
+//
+// PUPROSE: demo
+
+// note this is used for e.g. RPM counters that are unidirectional.
+
+// connect up to 4 rotary encoders to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO
+// --------------------------------------
+// pin A pin 0
+// pin B pin 1
+// .... .... (up to 4 RE)
+//
+// SDA A4
+// SCL A5
+//
+
+#include "Wire.h"
+#include "rotaryDecoder.h"
+
+rotaryDecoder decoder(0x20);
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+ Serial.print("ROTARY_DECODER_LIB_VERSION:\t");
+ Serial.println(ROTARY_DECODER_LIB_VERSION);
+
+ Wire.begin();
+ Wire.setClock(100000);
+ decoder.begin(4);
+ decoder.readInitialState();
+}
+
+
+void loop()
+{
+ // if one of the counters is updated, print them.
+ if (decoder.updateSingle()) // note values will only go up!
+ {
+ for (uint8_t i = 0; i < 4; i++)
+ {
+ Serial.print("\t");
+ Serial.print(decoder.getValue(i));
+ }
+ Serial.println();
+ }
+
+ // other tasks...
+}
+
+
+// -- END OF FILE --