add read16() read24() read32() (#12)

- add (experimental) read16(), read24(), read32() functions.
- changed return types of some functions.
- update keywords.txt
- update readme.md
- update GitHub actions
- update license 2023
- minor edits

Author: RobTillaart

CHANGELOG.md

@@ -6,14 +6,24 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.3.2] - 2023-02-20
+- add (experimental) read16(), read24(), read32() functions.
+- changed return types of some functions.
+- update keywords.txt
+- update readme.md
+- update GitHub actions
+- update license 2023
+- minor edits
+
+
 ## [0.3.1] - 2022-11-06
 - redo clock pulse
 
-
 ## [0.3.0] - 2022-11-05
 - fix inputRegister bug
 - refactor for code size
 
+----
 
 ## [0.2.4] - 2022-11-05
 - add changelog.md
@@ -27,10 +37,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [0.2.2] - 2020-12-22
 
+----
 
 ## No history ...
 
-
 ## [0.1.0 - 2013-09-29
 - initial version
 

FastShiftIn.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: FastShiftIn.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.3.0
+// VERSION: 0.3.2
 // PURPOSE: Fast ShiftIn for 74HC165 register, AVR optimized
 //    DATE: 2013-09-29
 //     URL: https://github.com/RobTillaart/FastShiftIn
@@ -14,8 +14,8 @@
 
 FastShiftIn::FastShiftIn(uint8_t dataIn, uint8_t clockPin, uint8_t bitOrder)
 {
-  _bitOrder = bitOrder;
-  _value    = 0;
+  _bitOrder  = bitOrder;
+  _lastValue = 0;
   pinMode(dataIn, INPUT);
   pinMode(clockPin, OUTPUT);
   //  https://www.arduino.cc/reference/en/language/functions/advanced-io/shiftin/
@@ -41,8 +41,7 @@ FastShiftIn::FastShiftIn(uint8_t dataIn, uint8_t clockPin, uint8_t bitOrder)
 }
 
 
-
-int FastShiftIn::read()
+uint16_t FastShiftIn::read()
 {
   if (_bitOrder == LSBFIRST)
   {
@@ -52,8 +51,65 @@ int FastShiftIn::read()
 }
 
 
+uint16_t FastShiftIn::read16()
+{
+  uint16_t rv;
+  if (_bitOrder == LSBFIRST)
+  {
+    rv = readLSBFIRST();
+    rv += uint16_t(readLSBFIRST()) << 8;
+    return rv;
+  }
+  rv = readMSBFIRST();
+  rv <<= 8;
+  rv += readMSBFIRST();
+  return rv;
+}
+
+
+uint32_t FastShiftIn::read24()
+{
+  uint32_t rv;
+  if (_bitOrder == LSBFIRST)
+  {
+    rv = readLSBFIRST();
+    rv += uint32_t(readLSBFIRST()) << 8;
+    rv += uint32_t(readLSBFIRST()) << 16;
+    return rv;
+  }
+  rv = readMSBFIRST();
+  rv <<= 8;
+  rv += readMSBFIRST();
+  rv <<= 8;
+  rv += readMSBFIRST();
+  return rv;
+}
+
+
+uint32_t FastShiftIn::read32()
+{
+  uint32_t rv;
+  if (_bitOrder == LSBFIRST)
+  {
+    rv = readLSBFIRST();
+    rv += uint32_t(readLSBFIRST()) << 8;
+    rv += uint32_t(readLSBFIRST()) << 16;
+    rv += uint32_t(readLSBFIRST()) << 24;
+    return rv;
+  }
+  rv = readMSBFIRST();
+  rv <<= 8;
+  rv += readMSBFIRST();
+  rv <<= 8;
+  rv += readMSBFIRST();
+  rv <<= 8;
+  rv += readMSBFIRST();
+  return rv;
+}
+
+
 
-int FastShiftIn::readLSBFIRST()
+uint8_t FastShiftIn::readLSBFIRST()
 {
 #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR)
 
@@ -74,20 +130,20 @@ int FastShiftIn::readLSBFIRST()
     *_clockRegister &= cbmask2;
     SREG = oldSREG;
   }
-  _value = rv;
+  _lastValue = rv;
   return rv;
 
 #else
 
-  // reference implementation
-  _value = shiftIn(_dataPinIn, _clockPin, LSBFIRST);
-  return _value;
+  //  reference implementation
+  _lastValue = shiftIn(_dataPinIn, _clockPin, LSBFIRST);
+  return _lastValue;
 
 #endif
 }
 
 
-int FastShiftIn::readMSBFIRST()
+uint8_t FastShiftIn::readMSBFIRST()
 {
 #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR)
 
@@ -108,23 +164,23 @@ int FastShiftIn::readMSBFIRST()
     *_clockRegister &= cbmask2;
     SREG = oldSREG;
   }
-  _value = rv;
+  _lastValue = rv;
   return rv;
 
 #else
 
-  // reference implementation
-  _value = shiftIn(_dataPinIn, _clockPin, MSBFIRST);
-  return _value;
+  //  reference implementation
+  _lastValue = shiftIn(_dataPinIn, _clockPin, MSBFIRST);
+  return _lastValue;
 
 #endif
 
 }
 
 
-int FastShiftIn::lastRead(void)
+uint32_t FastShiftIn::lastRead(void)
 {
-  return _value;
+  return _lastValue;
 };
 
 
@@ -145,5 +201,5 @@ uint8_t FastShiftIn::getBitOrder(void)
 };
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

FastShiftIn.h

@@ -2,7 +2,7 @@
 //
 //    FILE: FastShiftIn.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.3.1
+// VERSION: 0.3.2
 // PURPOSE: Fast ShiftIn for 74HC165 register, AVR optimized
 //    DATE: 2013-09-29
 //     URL: https://github.com/RobTillaart/FastShiftIn
@@ -11,7 +11,7 @@
 #include "Arduino.h"
 
 
-#define FASTSHIFTIN_LIB_VERSION         (F("0.3.1"))
+#define FASTSHIFTIN_LIB_VERSION         (F("0.3.2"))
 
 
 class FastShiftIn
@@ -20,36 +20,40 @@ class FastShiftIn
   //  bitOrder = { LSBFIRST, MSBFIRST };
   FastShiftIn(uint8_t dataIn, uint8_t clockPin, uint8_t bitOrder = LSBFIRST);
 
-  int     read(void);
-  int     lastRead(void);
+  uint16_t read(void);
+  uint16_t read16(void);
+  uint32_t read24(void);
+  uint32_t read32(void);
+  uint32_t lastRead(void);
 
-  bool    setBitOrder(uint8_t bitOrder);
-  uint8_t getBitOrder(void);
+  //  returns false if bitOrder out of range.
+  bool     setBitOrder(uint8_t bitOrder);
+  uint8_t  getBitOrder(void);
 
   //  overrule bitOrder (most optimized).
-  int     readLSBFIRST(void);
-  int     readMSBFIRST(void);
+  uint8_t  readLSBFIRST(void);
+  uint8_t  readMSBFIRST(void);
 
 private:
-  uint8_t _bitOrder;
-  int     _value;
+  uint8_t  _bitOrder;
+  uint32_t _lastValue;
 
 #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR)
 
   volatile uint8_t *_dataInRegister;
-  uint8_t _dataInBit;
+  uint8_t  _dataInBit;
 
   volatile uint8_t *_clockRegister;
-  uint8_t _clockBit;
+  uint8_t  _clockBit;
 
 #else
 
-  uint8_t _dataPinIn;
-  uint8_t _clockPin;
+  uint8_t  _dataPinIn;
+  uint8_t  _clockPin;
 
 #endif
 };
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

README.md

@@ -27,6 +27,9 @@ in the constructor of the FastShiftIn object.
 If not an **ARDUINO_ARCH_AVR** or **ARDUINO_ARCH_MEGAAVR** the class falls back 
 to the default shiftIn() implementation.
 
+Since 0.3.2 read16(), read24() and read32() are added.
+These are experimental and not fully tested yet.
+
 
 ## Performance
 
@@ -35,26 +38,50 @@ The performance of **read()** is substantially faster than the default Arduino
 Exact how big the performance gain is can be seen with the example sketch.
 It does a comparison and shows how the class is to be used.
 
-test 0.2.3  Arduino UNO
+Time in microseconds, Arduino UNO
+
+|  function            |   0.2.3  |   0.3.2  |
+|:---------------------|---------:|---------:|
+|  read()              |   19.30  |   20.49  |
+|  read16()            |          |   41.04  |
+|  read24()            |          |   62.91  |
+|  read32()            |          |   83.95  |
+|  readLSBFIRST()      |   19.04  |   19.92  |
+|  readMSBFIRST()      |   19.04  |   19.92  |
+|  reference shiftIn() |  107.82  |  108.20  |
+
+
+0.3.2 is a bit slower (incl. reference) than 0.2.3 but still much
+faster than the reference.
 
-|  function            | time (us) |
-|:---------------------|----------:|
-|  read()              |    19.30  |
-|  readLSBFIRST()      |    19.04  |
-|  readMSBFIRST()      |    19.04  |
-|  reference shiftIn() |   107.82  |
 
 
 ## Interface
 
-The interface exists of the following functions:
+```cpp
+#include "FastShiftIn.h"
+```
+
+#### Functions
+
+- **FastShiftIn(uint8_t dataIn, uint8_t clockPin, uint8_t bitOrder = LSBFIRST)** Constructor
+- **uint16_t read(void)** reads a new value, 8 bit.
+- **uint16_t read16(void)** reads a new value, 16 bit.
+- **uint32_t read24(void)** reads a new value, 24 bit.
+- **uint32_t read32(void)** reads a new value, 32 bit.
+- **uint32_t lastRead()** returns last value read.
+- **bool setBitOrder(uint8_t bitOrder)** set LSBFIRST or MSBFIRST. 
+Returns false for other values.
+- **uint8_t getBitOrder(void)** returns LSBFIRST or MSBFIRST.
+- **uint16_t readLSBFIRST(void)**  optimized LSB read(), 8 bit.
+- **uint16_t readMSBFIRST(void)**  optimized MSB read(), 8 bit.
+
 
-- **int read(void)** reads a new value.
-- **int lastRead()** returns last value read.
-- **bool setBitOrder(uint8_t bitOrder)** set LSBFIRST or MSBFIRST. Returns false for other values.
-- **uint8_t getBitOrder(void)** returns LSBFIRST or MSBFIRST
-- **int readLSBFIRST(void)**  optimized LSB read().
-- **int readMSBFIRST(void)**  optimized MSB read().
+#### Byte order
+
+It might be that **read16/24/32** has bytes not in the right order.
+Then you should use multiple calls to **read()** and merge these
+bytes in the order you want them.
 
 
 ## Notes
@@ -64,15 +91,22 @@ The interface exists of the following functions:
 pull up resistors, especially if wires are exceeding 10 cm (4").
 
 
-## Operation
+## Future
 
-See examples
+#### Must
 
+#### Should
 
-## Future
+- extend unit tests
+
+#### Could
 
 - esp32 optimization readLSBFIRST readMSBFIRST
-- read8() read16(), read24(), read32() 
 - **read(uint8_t \* arr, uint8_t nr)** ??
 - example schema
+- would it be interesting to make a fastShiftIn16() etc?
+  - squeeze performance but more maintenance.?
+
+#### Wont
+