diff --git a/libraries/rotaryDecoder/CHANGELOG.md b/libraries/rotaryDecoder/CHANGELOG.md index cbb55b35..0b63b59f 100644 --- a/libraries/rotaryDecoder/CHANGELOG.md +++ b/libraries/rotaryDecoder/CHANGELOG.md @@ -6,8 +6,18 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## [0.3.1] - 2024-06-20 +- changed **uint8_t readInitialState()** to return the read state. +- changed **bool setValue(uint8_t re, int32_t value = 0)** to return false +if parameter re is out of range, prevent possible bug. +- changed **int32_t getValue(uint8_t re)** to return 0 +if parameter re is out of range, prevent possible bug. +- add example **rotaryDecoder_demo_RE_IO.ino** +- update readme.md, interface section. +- minor edits + ## [0.3.0] - 2024-02-14 -- Fix #10 +- Fix #10, add read and write for free IO pins. - add **read1(pin)** - add **write1(pin, value)** experimental see #10 - made **read8()** and **write8()** public for faster multi pin access diff --git a/libraries/rotaryDecoder/README.md b/libraries/rotaryDecoder/README.md index b7317925..77820396 100644 --- a/libraries/rotaryDecoder/README.md +++ b/libraries/rotaryDecoder/README.md @@ -39,7 +39,8 @@ pins to GND so you will not get unintended interrupts. #### Constructor -- **rotaryDecoder(const int8_t address, TwoWire \*wire = Wire);** +- **rotaryDecoder(const int8_t address, TwoWire \*wire = Wire)** +constructor to set the address and optional the Wire bus. - **bool begin(uint8_t count = 4)** UNO ea. initializes the class. count is the number of rotary encoders connected. (Max 4 per PCF8574) Returns true if the PCF8574 is on the I2C bus. @@ -48,23 +49,31 @@ Returns true if the PCF8574 is on the I2C bus. #### Core functions -- **void readInitialState()** read the initial 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 internal counters. -- **void update()** update the internal counters of the RE. +- **uint8_t readInitialState()** read the initial state of the 4 rotary encoders. +Typically called in setup only, or after a sleep e.g. in combination with **setValue()**. +Since 0.3.1 this function returns the read state, saves an additional read8() call. +- **bool checkChange()** used for polling to see if one or more RE have changed. +This function does NOT update the internal counters. +- **bool update()** returns true if there is a change detected. +It updates the internal counters of the RE. The counters will add +1 or -1 depending on rotation 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. +Note that **update()** must be called as soon as possible after the interrupt occurs +or as often as possible when polling. +Returns false if there is no change since last read. +- **bool updateSingle()** returns true if there is a change detected. +It updates 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. +Returns false if there is no change since last read. #### Counters -- **uint32_t getValue(uint8_r re)** returns the RE counter. -- **void setValue(uint8_r re, uint32_t value = 0)** (re)set the internal counter to value, default 0 +- **int32_t getValue(uint8_r re)** returns the RE counter. +If the parameter re > 3 then 0 is returned. +- **bool setValue(uint8_r re, int32_t value = 0)** (re)set the internal counter to value, default 0. +If the parameter re > 3 then false is returned, true otherwise. #### Read1 - Write1 - experimental @@ -73,6 +82,7 @@ Warning the **write1(pin, value)** might alter the state of the rotary encoder p So this functionality should be tested thoroughly for your application. Especially the **write()** is **experimental**, see issue #10, feedback welcome. +See example **rotaryDecoder_demo_RE_IO.ino** (since 0.3.1). **Read1()** and **write1()** are functions to access the pins of the PCF8574 that are not used for rotary encoders. @@ -98,7 +108,7 @@ rotary encoder pins. As the decoder is based upon a PCF8574, a I2C device, the performance is affected by the clock speed of the I2C bus. -All four core functions have one call to **\read8()** which is the most expensive part. +All four core functions have one call to **read8()** 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). diff --git a/libraries/rotaryDecoder/examples/rotaryDecoder_demo_RE_IO/rotaryDecoder_demo_RE_IO.ino b/libraries/rotaryDecoder/examples/rotaryDecoder_demo_RE_IO/rotaryDecoder_demo_RE_IO.ino new file mode 100644 index 00000000..83ae73d0 --- /dev/null +++ b/libraries/rotaryDecoder/examples/rotaryDecoder_demo_RE_IO/rotaryDecoder_demo_RE_IO.ino @@ -0,0 +1,90 @@ +// +// FILE: rotaryDecoder_demo_RE_IO.ino +// AUTHOR: Rob Tillaart +// DATE: 2024-02-13 +// PURPOSE: demo +// URL: https://github.com/RobTillaart/rotaryDecoder +// +// example configuration +// connect one rotary encoders +// connect multiple switches +// connect one line to the other end of the switches to enable them +// connect a buzzer +// +// RotaryEncoder PCF8574 UNO +// -------------------------------------- +// pin A pin 0 +// pin B pin 1 +// switch pin 2 +// switch pin 3 +// switch pin 4 +// enable line pin 5 +// buzzer pin 6 +// switch pin 7 +// +// SDA A4 +// SCL A5 +// + + +#include "rotaryDecoder.h" + +rotaryDecoder decoder(0x39); // 0x39 = 57 + + +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); + + // only one rotary encoder + decoder.begin(1); + decoder.readInitialState(); + + // other lines are switches (INPUT) + decoder.write1(2, LOW); + decoder.write1(3, LOW); + decoder.write1(4, LOW); + decoder.write1(7, LOW); + + // enable/disable switches + // HIGH == switches enabled + decoder.write1(5, HIGH); + + // line 6 == buzzer + decoder.write1(6, LOW); +} + + +void loop() +{ + // if one of the lines is updated, print them. + if (decoder.update()) + { + Serial.print("\t"); + Serial.print(decoder.getValue(0)); + Serial.print("\t"); + Serial.print(decoder.read1(2)); + Serial.print("\t"); + Serial.print(decoder.read1(3)); + Serial.print("\t"); + Serial.print(decoder.read1(4)); + Serial.print("\t"); + Serial.print(decoder.read1(5)); + Serial.print("\t"); + Serial.print(decoder.read1(6)); + Serial.print("\t"); + Serial.print(decoder.read1(7)); + Serial.println(); + } + + // other tasks... +} + + +// -- END OF FILE -- diff --git a/libraries/rotaryDecoder/library.json b/libraries/rotaryDecoder/library.json index 8a4331b3..c6bfe830 100644 --- a/libraries/rotaryDecoder/library.json +++ b/libraries/rotaryDecoder/library.json @@ -15,7 +15,7 @@ "type": "git", "url": "https://github.com/RobTillaart/rotaryDecoder.git" }, - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "frameworks": "*", "platforms": "*", diff --git a/libraries/rotaryDecoder/library.properties b/libraries/rotaryDecoder/library.properties index fbc73d85..19ce601d 100644 --- a/libraries/rotaryDecoder/library.properties +++ b/libraries/rotaryDecoder/library.properties @@ -1,5 +1,5 @@ name=rotaryDecoder -version=0.3.0 +version=0.3.1 author=Rob Tillaart maintainer=Rob Tillaart sentence=Arduino library for rotary decoder with a PCF8574. diff --git a/libraries/rotaryDecoder/rotaryDecoder.cpp b/libraries/rotaryDecoder/rotaryDecoder.cpp index 29eda617..ea1c7abf 100644 --- a/libraries/rotaryDecoder/rotaryDecoder.cpp +++ b/libraries/rotaryDecoder/rotaryDecoder.cpp @@ -1,7 +1,7 @@ // // FILE: rotaryDecoder.cpp // AUTHOR: Rob Tillaart -// VERSION: 0.3.0 +// VERSION: 0.3.1 // DATE: 2021-05-08 // PURPOSE: Arduino library for rotary decoder // URL: https://github.com/RobTillaart/rotaryDecoder @@ -38,7 +38,7 @@ bool rotaryDecoder::isConnected() } -void rotaryDecoder::readInitialState() +uint8_t rotaryDecoder::readInitialState() { uint8_t value = read8(); _lastValue = value; @@ -47,6 +47,7 @@ void rotaryDecoder::readInitialState() _lastPos[i] = value & 0x03; value >>= 2; } + return _lastValue; } @@ -133,13 +134,16 @@ bool rotaryDecoder::updateSingle() int32_t rotaryDecoder::getValue(uint8_t re) { + if (re > 3) return 0; return _encoder[re]; } -void rotaryDecoder::setValue(uint8_t re, int32_t value) +bool rotaryDecoder::setValue(uint8_t re, int32_t value) { + if (re > 3) return false; _encoder[re] = value; + return true; } diff --git a/libraries/rotaryDecoder/rotaryDecoder.h b/libraries/rotaryDecoder/rotaryDecoder.h index 9acff90b..4d100d8f 100644 --- a/libraries/rotaryDecoder/rotaryDecoder.h +++ b/libraries/rotaryDecoder/rotaryDecoder.h @@ -2,7 +2,7 @@ // // FILE: rotaryDecoder.h // AUTHOR: Rob Tillaart -// VERSION: 0.3.0 +// VERSION: 0.3.1 // DATE: 2021-05-08 // PURPOSE: Arduino library for rotary decoder // URL: https://github.com/RobTillaart/rotaryDecoder @@ -11,7 +11,7 @@ #include "Arduino.h" #include "Wire.h" -#define ROTARY_DECODER_LIB_VERSION (F("0.3.0")) +#define ROTARY_DECODER_LIB_VERSION (F("0.3.1")) class rotaryDecoder @@ -22,7 +22,7 @@ public: bool begin(uint8_t count = 4); bool isConnected(); - void readInitialState(); + uint8_t readInitialState(); // for polling version, // checkChange is bit faster than a call to update @@ -34,8 +34,9 @@ public: bool updateSingle(); // assumes single direction => + ++ +++ // re = rotary encoder + // returns 0, false if re > 3. int32_t getValue(uint8_t re); - void setValue(uint8_t re, int32_t value = 0); + bool setValue(uint8_t re, int32_t value = 0); // READ - WRITE interface