add rotaryDecoderSwitch

Author: RobTillaart

libraries/rotaryDecoderSwitch/.arduino-ci.yml

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

libraries/rotaryDecoderSwitch/.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/rotaryDecoderSwitch/.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/rotaryDecoderSwitch/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/rotaryDecoderSwitch/README.md

@@ -0,0 +1,110 @@
+
+[![Arduino CI](https://github.com/RobTillaart/rotaryDecoderSwitch/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/rotaryDecoderSwitch/blob/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/RobTillaart/rotaryDecoderSwitch.svg?maxAge=3600)](https://github.com/RobTillaart/rotaryDecoderSwitch/releases)
+
+
+# rotaryDecoderSwitch
+
+Arduino library for a PCF8574 based rotary decoder - supports 2 rotary encoders with a switch
+
+
+## Description
+
+Experimental - not tested extensively
+
+related to https://github.com/RobTillaart/rotaryDecoder
+interface is kept same as much as possible.
+
+```cpp
+// connect up to 2 rotary encoders with a switch to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO REMARKS
+// -----------------------------------------------------------
+// 1 pin A pin 0
+// 1 pin B pin 1
+// 1 switch pin 2 (switch to gnd)
+// pin 3 (reserved)
+// 2 pin A pin 4
+// 2 pin B pin 5
+// 2 switch pin 6 (switch to gnd)
+// pin 7 (reserved)
+//
+// SDA A4
+// SCL A5
+//
+```
+
+Note the above mapping is sort of compatible to using the rotaryDecoder class and using device 0 and 2 only,
+
+
+
+## Interface
+
+- **rotaryDecoderSwitch(const int8_t address, TwoWire \*wire = Wire);** constructor to set the address and optional the Wire bus.
+- **bool begin(uint8_t sda, uint8_t scl, uint8_t cnt = 2)** 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 = 2)** 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 2 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, and the flags if a key is pressed. The counters will add +1 or -1 depending on direction. Need to be called before **getValue()** or before **getKeyPressed()**. Note that **update()** must be called as soon as possible after the interrupt occurs (or as often as possible when polling).
+- **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 & keypresses
+
+- **uint32_t getValue(uint8_r re)** returns the RE counter. (re = 0 or 1).
+- **void setValue(uint8_r re, uint32_t val = 0)** (re)set the internal counter to val, default 0
+- **bool isKeyPressed(uint8_t re)** returns true is the switch is pressed of the RE selected (re = 0 or 1). Note one needs to call **update()** first!
+
+
+## Debugging
+
+- **int8_t getLastPosition(uint8_r re)** (re = 0 or 1).
+- **int8_t getRaw()**
+
+
+## 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. 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 | 234 | | |
+| 200 KHz | 136 | 98 | 42% |
+| 300 KHz | 100 | 36 | 26% |
+| 400 KHz | 85 | 15 | 15% | preferred max
+| 500 KHz | 78 | 7 | 8% |
+| 600 KHz | 67 | 11 | 14% | (strange outlier)
+| 700 KHz | 63 | 4 | 6% |
+
+At @400KHz it can update 2 rotary encoders in less than 90 us. 
+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..
+
+## TODO
+
+- think of what to do with the two "idle lines"

libraries/rotaryDecoderSwitch/examples/rotaryDecoderSwitch_demo_interrupt/rotaryDecoderSwitch_demo_interrupt.ino

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

libraries/rotaryDecoderSwitch/examples/rotaryDecoderSwitch_demo_polling/rotaryDecoderSwitch_demo_polling.ino

@@ -0,0 +1,63 @@
+//
+// FILE: rotaryDecoderSwitch_demo_polling.ino
+// AUTHOR: Rob Tillaart
+// DATE: 2021-05-17
+//
+// PUPROSE: demo
+
+// connect up to 2 rotary encoders with a switch to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO
+// --------------------------------------
+// 1 pin A pin 0
+// 1 pin B pin 1
+// 1 switch pin 2
+// pin 3 (reserved)
+// 2 pin A pin 4
+// 2 pin B pin 5
+// 2 switch pin 6
+// pin 7 (reserved)
+//
+// SDA A4
+// SCL A5
+//
+
+#include "Wire.h"
+#include "rotaryDecoderSwitch.h"
+
+rotaryDecoderSwitch decoder(0x20);
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+ Serial.print("ROTARY_DECODER_SWITCH_LIB_VERSION:\t");
+ Serial.println(ROTARY_DECODER_SWITCH_LIB_VERSION);
+
+ Wire.begin();
+ Wire.setClock(100000);
+ decoder.begin(2);
+ decoder.readInitialState();
+}
+
+
+void loop()
+{
+ if (decoder.checkChange())
+ {
+ decoder.update();
+ for (uint8_t i = 0; i < 2; i++)
+ {
+ Serial.print("\t");
+ Serial.print(decoder.getValue(i));
+ Serial.print("\t");
+ Serial.print(decoder.isKeyPressed(i));
+ }
+ Serial.println();
+ }
+
+ // other tasks...
+}
+
+
+// -- END OF FILE --

libraries/rotaryDecoderSwitch/examples/rotaryDecoderSwitch_demo_simple/rotaryDecoderSwitch_demo_simple.ino

@@ -0,0 +1,64 @@
+//
+// FILE: rotaryDecoderSwitch_demo_simple.ino
+// AUTHOR: Rob Tillaart
+// DATE: 2021-05-17
+//
+// PUPROSE: demo
+
+// connect up to 2 rotary encoders with a switch to 1 PCF8574.
+//
+// RotaryEncoder PCF8574 UNO
+// --------------------------------------
+// 1 pin A pin 0
+// 1 pin B pin 1
+// 1 switch pin 2
+// pin 3 (reserved)
+// 2 pin A pin 4
+// 2 pin B pin 5
+// 2 switch pin 6
+// pin 7 (reserved)
+//
+// SDA A4
+// SCL A5
+//
+
+#include "Wire.h"
+#include "rotaryDecoderSwitch.h"
+
+rotaryDecoderSwitch decoder(0x20);
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+ Serial.print("ROTARY_DECODER_SWITCH_LIB_VERSION:\t");
+ Serial.println(ROTARY_DECODER_SWITCH_LIB_VERSION);
+
+ Wire.begin();
+ Wire.setClock(100000);
+ decoder.begin(2);
+ decoder.readInitialState();
+}
+
+
+void loop()
+{
+ // if one of the counters is updated, print them.
+ // update() will not check if a key is pressed.
+ if (decoder.update())
+ {
+ for (uint8_t i = 0; i < 2; i++)
+ {
+ Serial.print("\t");
+ Serial.print(decoder.getValue(i));
+ Serial.print("\t");
+ Serial.print(decoder.isKeyPressed(i));
+ }
+ Serial.println();
+ }
+
+ // other tasks...
+}
+
+
+// -- END OF FILE --