Add select functions (#35)

* add select() functions
* add example

Author: RobTillaart

CHANGELOG.md

@@ -6,12 +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.5] - 2022-06-17
+
+### Added
+- add select(), selectN(), selectNone() and selectAll()
+  convenience wrappers
+
+
 ## [0.3.4] - 2022-04-11
 
 ### Added
 - add CHANGELOG.md
 
-### Changed
 
 ### Fixed
 - **begin(int sda, int scl)** int parameters for ESP alike.

PCF8574.cpp

@@ -2,7 +2,7 @@
 //    FILE: PCF8574.cpp
 //  AUTHOR: Rob Tillaart
 //    DATE: 02-febr-2013
-// VERSION: 0.3.4
+// VERSION: 0.3.5
 // PURPOSE: Arduino library for PCF8574 - 8 channel I2C IO expander
 //     URL: https://github.com/RobTillaart/PCF8574
 //          http://forum.arduino.cc/index.php?topic=184800
@@ -27,7 +27,7 @@ PCF8574::PCF8574(const uint8_t deviceAddress, TwoWire *wire)
 #if defined (ESP8266) || defined(ESP32)
 bool PCF8574::begin(int dataPin, int clockPin, uint8_t value)
 {
-  _wire      = &Wire;
+  _wire = &Wire;
   if ((dataPin < 255) && (clockPin < 255))
   {
     _wire->begin(dataPin, clockPin);
@@ -224,5 +224,22 @@ uint8_t PCF8574::readButton(const uint8_t pin)
 }
 
 
+void PCF8574::select(const uint8_t pin)
+{
+  uint8_t n = 0x00;
+  if (pin < 8) n = 1 << pin;
+  write8(n);
+};
+
+
+void PCF8574::selectN(const uint8_t pin) 
+{
+  uint8_t n = 0xFF;
+  if (pin < 8) n = (2 << pin) - 1;
+  write8(n);
+};
+
+
+
 // -- END OF FILE --
 

PCF8574.h

@@ -3,21 +3,18 @@
 //    FILE: PCF8574.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 02-febr-2013
-// VERSION: 0.3.4
+// VERSION: 0.3.5
 // PURPOSE: Arduino library for PCF8574 - 8 channel I2C IO expander
 //     URL: https://github.com/RobTillaart/PCF8574
 //          http://forum.arduino.cc/index.php?topic=184800
 //
-// HISTORY:
-// see PCF8574.cpp file
-//
 
 
 #include "Arduino.h"
 #include "Wire.h"
 
 
-#define PCF8574_LIB_VERSION         (F("0.3.4"))
+#define PCF8574_LIB_VERSION         (F("0.3.5"))
 
 #ifndef PCF8574_INITIAL_VALUE
 #define PCF8574_INITIAL_VALUE       0xFF
@@ -57,11 +54,11 @@ class PCF8574
 
 
   //added 0.1.07/08 Septillion
-  inline uint8_t readButton8()  { return PCF8574::readButton8(_buttonMask); }
-  uint8_t        readButton8(const uint8_t mask);
-  uint8_t        readButton(const uint8_t pin);
-  inline void    setButtonMask(const uint8_t mask) { _buttonMask = mask; };
-  uint8_t        getButtonMask() { return _buttonMask; };
+  uint8_t readButton8()  { return PCF8574::readButton8(_buttonMask); }
+  uint8_t readButton8(const uint8_t mask);
+  uint8_t readButton(const uint8_t pin);
+  void    setButtonMask(const uint8_t mask) { _buttonMask = mask; };
+  uint8_t getButtonMask() { return _buttonMask; };
 
 
   // rotate, shift, toggle, reverse expect all lines are output
@@ -74,6 +71,12 @@ class PCF8574
   void    reverse();
 
 
+  void    select(const uint8_t pin);
+  void    selectN(const uint8_t pin);
+  void    selectNone() { write8(0x00); };
+  void    selectAll()  { write8(0xFF); };
+
+
   int     lastError();
 
 

README.md

@@ -25,10 +25,27 @@ These chips are identical in behaviour although there are two distinct address r
 
 So you can connect up to 16 PCF8574 on one I2C bus, giving access 
 to 16 x 8 = 128 IO lines. To maximize IO lines combine 8 x PCF8575 + 8 x PCF8574A giving
-128 + 64 = 192 IO lines. Be sure to have a well dimensioned power supply.
+128 + 64 = 192 IO lines. 
+Be sure to have a well dimensioned power supply.
 
 The library allows to read and write both single pins or 8 pins at once.
-Furthermore some additional functions are implemented that are playful but useful.
+Furthermore some additional functions are implemented that are playful and useful.
+
+
+## I2C Clock
+
+Tested on UNO with **PCF8574_performance** showed that the PCF8574 still works at 500 KHz and failed at 600 KHz.
+These values are outside the specs of the datasheet so they are not recommended.
+However when performance is needed you can try to overclock the chip. 
+
+| clock speed |  Read  |  Write  |  Notes            |
+|:-----------:|:------:|:-------:|:------------------|
+|  100000     |  236   |   240   | spec datasheet    |
+|  200000     |  132   |   140   |
+|  300000     |  104   |   108   |
+|  400000     |   96   |    96   | max advised speed |
+|  500000     |   92   |    92   | not recommended   |
+|  600000     | crash  |  crash  | 
 
 
 ## Interface
@@ -59,7 +76,7 @@ in the class this is faster than reread the pins.
 - **void write8(const uint8_t value)** writes all 8 pins at once. This one does the actual writing.
 - **uint8_t write(const uint8_t pin, const uint8_t value)** writes a single pin; pin = 0..7; 
 value is HIGH(1) or LOW (0)
-- **valueOut()** returns the last written data.
+- **uint8_t valueOut()** returns the last written data.
 
 
 ### Button
@@ -90,12 +107,26 @@ Fills the higher lines with zero's.
 Fills the lower lines with zero's.
 - **void rotateRight(const uint8_t n = 1)** rotates output channels to right, moving lowest line to highest line.
 - **void rotateLeft(const uint8_t n = 1)** rotates output channels to left, moving highest line to lowest line.
-- **void reverse()** reverse the "bit pattern" of the lines, swapping pin 7 with 0, 6 with 1, 5 with 2 and 4 with 3.
+- **void reverse()** reverse the "bit pattern" of the lines, swapping pin 7 with 0, 6 with 1, 5 with 2 etc.
+
+
+### Select
+
+Some convenience wrappers.
+
+- **void select(const uint8_t pin)** sets a single pin to HIGH, all others are set to LOW.
+If pin > 7 all pins are set to LOW.
+Can be used to select one of n devices.
+- **void selectN(const uint8_t pin)** sets pins 0..pin to HIGH, all others are set to LOW.
+If pin > 7 all pins are set to LOW.
+This can typical be used to implement a VU meter.
+- **void selectNone()** sets all pins to LOW.
+- **void selectAll()** sets all pins to HIGH.
 
 
-### Misc
+### Miscellaneous
 
-- **int lastError()** returns the last error from the lib. (see .h file)
+- **int lastError()** returns the last error from the lib. (see .h file).
 
 
 ## Error codes
@@ -109,13 +140,13 @@ Fills the lower lines with zero's.
 
 ## Operation
 
-See examples
+See examples.
 
 It is advised to use pull-up or pull-down resistors so the lines have a defined state at startup.
 
 
 ## Future
 
--
+- 
 
 

examples/PCF8574_performance/PCF8574_performance.ino

@@ -22,7 +22,7 @@ void setup()
   PCF.begin();
   Serial.println(PCF.isConnected());
 
-  for (long clk = 100000; clk < 500000; clk += 50000)
+  for (long clk = 100000; clk < 800000; clk += 100000)
   {
     Serial.println(clk);
     Wire.setClock(clk);
@@ -49,4 +49,3 @@ void loop()
 
 
 // -- END OF FILE --
-

examples/PCF8574_performance/performance_0.3.5.txt

@@ -0,0 +1,19 @@
+...\PCF8574_performance.ino
+PCF8574_LIB_VERSION:	0.3.5
+1
+100000
+Read:	236
+Write:	 240
+200000
+Read:	132
+Write:	 140
+300000
+Read:	104
+Write:	 108
+400000
+Read:	96
+Write:	 96
+500000
+Read:	92
+Write:	 92
+600

examples/PCF8574_select/PCF8574_select.ino

@@ -0,0 +1,64 @@
+//
+//    FILE: PCF8574_select.ino
+//  AUTHOR: Rob Tillaart
+//    DATE: 2022-06-18
+// PUPROSE: demo PCF8574 library select functions
+
+
+
+#include "PCF8574.h"
+
+PCF8574 PCF(0x38);
+
+uint32_t start, stop;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("PCF8574_LIB_VERSION:\t");
+  Serial.println(PCF8574_LIB_VERSION);
+
+  PCF.begin();
+  Serial.println(PCF.isConnected());
+  Serial.println();
+
+  PCF.selectAll();
+  delay(1000);
+  PCF.selectNone();
+  delay(1000);
+  
+  // VU meter up
+  for (int i = 0; i < 7; i++)
+  {
+    PCF.selectN(i);
+    delay(100);
+  }
+
+  // VU meter down
+  for (int i = 7; i >= 0; i--)
+  {
+    PCF.selectN(i);
+    delay(100);
+  }
+}
+
+
+void loop()
+{
+  // night rider
+  for (int i = 0; i < 7; i++)
+  {
+    PCF.select(i);
+    delay(100);
+  }
+  for (int i = 7; i >= 0; i--)
+  {
+    PCF.select(i);
+    delay(100);
+  }
+}
+
+
+// -- END OF FILE --

keywords.txt

@@ -27,14 +27,20 @@ toggle	KEYWORD2
 toggleMask	KEYWORD2
 shiftRight	KEYWORD2
 shiftLeft	KEYWORD2
+
 rotateRight	KEYWORD2
 rotateLeft	KEYWORD2
 reverse	KEYWORD2
-lastError	KEYWORD2
+
+select	KEYWORD2
+selectN	KEYWORD2
+selectNone	KEYWORD2
+selectAll	KEYWORD2
 
 
 # Constants (	LITERAL1)
 PCF8574_LIB_VERSION	LITERAL1
+PCF8574_INITIAL_VALUE	LITERAL1
 PCF8574_OK	LITERAL1
 PCF8574_PIN_ERROR	LITERAL1
 PCF8574_I2C_ERROR	LITERAL1

library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/PCF8574.git"
   },
-  "version": "0.3.4",
+  "version": "0.3.5",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

library.properties

@@ -1,5 +1,5 @@
 name=PCF8574
-version=0.3.4
+version=0.3.5
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for PCF8574 - 8 channel I2C IO expander