refactor interface + update readme.md

CHANGELOG.md

@@ -7,7 +7,11 @@ 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

README.md

@@ -48,26 +48,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.
-- **bool 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.  
 Returns false if there is no change since last read.
-- **bool updateSingle()** update the internal counters of the RE. 
-This will add +1 +2 or +3 as it assumes that the rotary encoder 
+- **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
 
 - **int32_t getValue(uint8_r re)** returns the RE counter.
-- **void setValue(uint8_r re, int32_t value = 0)** (re)set the internal counter to value, default 0
+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
@@ -76,6 +81,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.

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