add writeArray() and readArray() (#61)

- add **writeArray(array, size)** and **readArray(array, size)**.
- add PCF8574_writeArray.ino
- update readme.md
- minor edits

Author: RobTillaart

CHANGELOG.md

@@ -6,8 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.4] - 2025-09-01
+- add **writeArray(array, size)** and **readArray(array, size)**.
+- add PCF8574_writeArray.ino
+- update readme.md
+- minor edits
+
 ## [0.4.3] - 2025-08-21
-- update github actions
+- update GitHub actions
 - minor edits
 
 ## [0.4.2] - 2025-04-18

PCF8574.cpp

@@ -2,14 +2,18 @@
 //    FILE: PCF8574.cpp
 //  AUTHOR: Rob Tillaart
 //    DATE: 02-febr-2013
-// VERSION: 0.4.3
+// VERSION: 0.4.4
 // PURPOSE: Arduino library for PCF8574 - 8 channel I2C IO expander
 //     URL: https://github.com/RobTillaart/PCF8574
 //          http://forum.arduino.cc/index.php?topic=184800
 
 
 #include "PCF8574.h"
 
+#ifndef I2C_BUFFER_LENGTH
+#define I2C_BUFFER_LENGTH    (32)
+#endif
+
 
 PCF8574::PCF8574(const uint8_t deviceAddress, TwoWire *wire)
 : _address {deviceAddress}, _wire {wire}
@@ -93,6 +97,48 @@ void PCF8574::write(const uint8_t pin, const uint8_t value)
 }
 
 
+//  experimental 0.4.4
+bool PCF8574::writeArray(uint8_t *array, uint8_t size)
+{
+  if (size > (I2C_BUFFER_LENGTH - 1))
+  {
+    _error = PCF8574_BUFFER_LENGTH_ERROR;
+    return false;
+  }
+  yield();
+  _wire->beginTransmission(_address);
+  for (uint8_t i = 0; i < size; i++)
+  {
+    _wire->write(array[i]);
+  }
+  _error = _wire->endTransmission();
+  _dataOut = array[size - 1];
+  return true;
+}
+
+
+bool PCF8574::readArray(uint8_t *array, uint8_t size)
+{
+  if (size > (I2C_BUFFER_LENGTH - 1))
+  {
+    _error = PCF8574_BUFFER_LENGTH_ERROR;
+    return false;
+  }
+  yield();
+  if (_wire->requestFrom(_address, size) != size)
+  {
+    _error = PCF8574_I2C_ERROR;
+    return false;
+  }
+  for (uint8_t i = 0; i < size; i++)
+  {
+    array[i] = _wire->read();
+  }
+  _dataIn = array[size - 1];
+  return true;
+}
+
+
 void PCF8574::toggle(const uint8_t pin)
 {
   if (pin > 7)

PCF8574.h

@@ -3,7 +3,7 @@
 //    FILE: PCF8574.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 02-febr-2013
-// VERSION: 0.4.3
+// VERSION: 0.4.4
 // PURPOSE: Arduino library for PCF8574 - 8 channel I2C IO expander
 //     URL: https://github.com/RobTillaart/PCF8574
 //          http://forum.arduino.cc/index.php?topic=184800
@@ -13,15 +13,16 @@
 #include "Wire.h"
 
 
-#define PCF8574_LIB_VERSION         (F("0.4.3"))
+#define PCF8574_LIB_VERSION           (F("0.4.4"))
 
 #ifndef PCF8574_INITIAL_VALUE
-#define PCF8574_INITIAL_VALUE       0xFF
+#define PCF8574_INITIAL_VALUE         0xFF
 #endif
 
-#define PCF8574_OK                  0x00
-#define PCF8574_PIN_ERROR           0x81
-#define PCF8574_I2C_ERROR           0x82
+#define PCF8574_OK                    0x00
+#define PCF8574_PIN_ERROR             0x81
+#define PCF8574_I2C_ERROR             0x82
+#define PCF8574_BUFFER_LENGTH_ERROR   0x83
 
 
 class PCF8574
@@ -32,21 +33,25 @@ class PCF8574
   bool    begin(uint8_t value = PCF8574_INITIAL_VALUE);
   bool    isConnected();
 
-
   //  note: setting the address corrupt internal buffer values
   //  a read8() / write8() call updates them.
   bool    setAddress(const uint8_t deviceAddress);
   uint8_t getAddress() const { return _address; }
 
+
+  //  read write
   uint8_t read8();
   uint8_t read(const uint8_t pin);
   uint8_t value() const { return _dataIn; };
 
-
   void    write8(const uint8_t value);
   void    write(const uint8_t pin, const uint8_t value);
   uint8_t valueOut() const { return _dataOut; }
 
+  //  experimental 0.4.4
+  bool    writeArray(uint8_t *array, uint8_t size);
+  bool    readArray(uint8_t *array, uint8_t size);
+
 
   //  added 0.1.07/08 Septillion
   uint8_t readButton8() { return PCF8574::readButton8(_buttonMask); }

README.md

@@ -99,21 +99,29 @@ before calling **begin()**.
 - https://github.com/RobTillaart/MCP23S17  SPI 16 IO lines.
 - https://github.com/RobTillaart/PCF8575  I2C 16 IO lines.
 - https://github.com/RobTillaart/PCA9671  I2C 16 IO lines. - successor PCF8575
-
+- https://github.com/RobTillaart/TCA9555  I2C 16 IO lines.
 
 8 bit port expanders
 
 - https://github.com/RobTillaart/MCP23008  I2C 8 IO lines.
 - https://github.com/RobTillaart/MCP23S08  SPI 8 IO lines.
 - https://github.com/RobTillaart/PCF8574  I2C 8 IO lines.
+- https://github.com/RobTillaart/TCA9554  I2C 8 IO lines.
+
+Other libs based upon PCF8574
+
+- https://github.com/RobTillaart/I2CKeyPad
+- https://github.com/RobTillaart/rotaryDecoder
+- https://github.com/RobTillaart/rotaryDecoderSwitch
 
 
 ## I2C
 
 
 ### Performance
 
-Tested on UNO with **PCF8574_performance** showed that the PCF8574 still works at 500 KHz and failed at 600 KHz.
+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. 
 
@@ -122,7 +130,7 @@ However when performance is needed you can try to overclock the chip.
 |  100000     |  236   |   240   |  spec datasheet     |
 |  200000     |  132   |   140   |
 |  300000     |  104   |   108   |
-|  400000     |   96   |    96   |  max advised speed  |
+|  400000     |   96   |    96   |  max speed advised  |
 |  500000     |   92   |    92   |  not recommended    |
 |  600000     | crash  |  crash  | 
 
@@ -179,6 +187,63 @@ value is HIGH(1) or LOW (0)
 - **uint8_t valueOut()** returns the last written data.
 
 
+### ReadArray and WriteArray 
+
+**Experimental (0.4.4)**
+
+Needs testing and verification with scope.
+See issue #60 and datasheet, 7.4 Device Functional Modes
+
+These array functions read / write up to 30 bytes in one I2C transaction.
+30 bytes is the maximum length of an AVR I2C buffer.
+Other lengths are possible by patching the PCF8574.cpp file.
+
+- **bool writeArray(uint8_t \*array, uint8_t size)** writes size bytes in one **blocking** call. 
+Blocking time depends on the I2C bus speed.
+ValueOut() is set to the last byte send.
+- **bool readArray(uint8_t \*array, uint8_t size)** reads size bytes in one **blocking** call.
+Value() is set to the last byte received.
+
+With **writeArray()** one can implement short pulses on the output pins.
+The duration of those pulses are 9 I2C clock pulses.
+So the duration of the pulse depends on (1) in how many bytes the pin 
+is HIGH, (2) the I2C clock speed, and (3) the precision of the I2C clock.
+
+```cpp
+uint8_t arr[10] = { 0, 1, 0, 1, 1, 0, 1, 1, 1, 0 };
+Wire.setClock(300000);
+PCF.writeArray(arr, 10);
+Wire.setClock(100000);
+```
+
+Indicative pulse duration, depends also on the precision of the I2C clock. 
+By varying the clock speed one can adjust pulse length.
+(e.g. a pulse of 50 us needs about 9000/50 = 180 kHz, with len = 1)
+
+|  I2C CLK  |  len = 1  |   len = 2  |   len = 3  |  notes  |
+|:---------:|:---------:|:----------:|:----------:|:--------|
+|   45 kHz  | 200.0 us  |  400.0 us  |  600.0 us  |
+|   90 kHz  | 100.0 us  |  200.0 us  |  300.0 us  |
+|  100 kHz  |  90.0 us  |  180.0 us  |  270.0 us  |
+|  200 kHz  |  45.0 us  |   90.0 us  |  135.0 us  |
+|  300 kHz  |  30.0 us  |   60.0 us  |   90.0 us  |
+|  400 kHz  |  22.5 us  |   45.0 us  |   67.5 us  |  max speed advised
+|  450 kHz  |  20.0 us  |   40.0 us  |   60.0 us  |  could work.
+
+Note 1: that one writes to all pins so one might need a **read8()** to get the
+status of the pins that should not be affected.
+
+Note 2: I2C clocks might not be able to be set to all possible frequencies.
+
+
+With **readArray()** one can implement a parallel sampling of up to 
+32 bytes of up to 8 input lines at a sub millisecond range. 
+This is not enough data for a full logical analyser, however it 
+might be useful in other applications.
+
+As stated, these function needs testing, so feedback is welcome.
+
+
 ### Button
 
 The **"button"** functions are to be used when you mix input and output on one IC.

docs/PCF8574_I2C_busExpander.pdf docs/PCF8574_I2C_busExpander_Oct_2005.pdfdocs/PCF8574_I2C_busExpander.pdf renamed to docs/PCF8574_I2C_busExpander_Oct_2005.pdf

@@ -42,9 +42,11 @@ void doToggle()
 void setup()
 {
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
-  Serial.print("PCF8574_LIB_VERSION:\t");
+  Serial.print("PCF8574_LIB_VERSION: ");
   Serial.println(PCF8574_LIB_VERSION);
+  Serial.println();
 
   Wire1.begin();
 

docs/pcf8574.pdf docs/pcf8574_sept_2024.pdfdocs/pcf8574.pdf renamed to docs/pcf8574_sept_2024.pdf

@@ -9,7 +9,7 @@
 #include "PCF8574.h"
 
 //  adjust addresses if needed
-PCF8574 PCF(0x39, &Wire2);  //  Wire2 ==> Teensy 
+PCF8574 PCF(0x39, &Wire2);  //  Wire2 ==> Teensy
 
 
 void doHigh()
@@ -42,9 +42,11 @@ void doToggle()
 void setup()
 {
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
-  Serial.print("PCF8574_LIB_VERSION:\t");
+  Serial.print("PCF8574_LIB_VERSION: ");
   Serial.println(PCF8574_LIB_VERSION);
+  Serial.println();
 
   Wire2.begin();
 

docs/pcf8574a_aug_2021.pdf

@@ -39,10 +39,12 @@ void pcf_irq()
 void setup()
 {
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
   Serial.print("PCF8574_LIB_VERSION: ");
   Serial.println(PCF8574_LIB_VERSION);
-  
+  Serial.println();
+
   Wire.begin();
   PCF.begin();