refactor interface + update readme.md (#13)

- 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

Author: RobTillaart

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

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

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

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": "*",

library.properties

@@ -1,5 +1,5 @@
 name=rotaryDecoder
-version=0.3.0
+version=0.3.1
 author=Rob Tillaart <[email protected]>
 maintainer=Rob Tillaart <[email protected]>
 sentence=Arduino library for rotary decoder with a PCF8574.

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

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 @@ class rotaryDecoder
   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 @@ class rotaryDecoder
   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