refactor API, begin() (#45)

- refactor API, begin() - update readme.md - update examples - add examples ESP32 RP2040 - minor edits
RobTillaart · Dec 11, 2023 · b89253b · b89253b
1 parent e5089a5
commit b89253b
Show file tree

Hide file tree

Showing 22 changed files with 323 additions and 94 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,12 +6,20 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.0] - 2023-09-23
+- refactor API, begin()
+- update readme.md
+- update examples
+- add examples ESP32 RP2040
+- minor edits
+
+----
+
 ## [0.3.9] - 2023-09-23
 - Add Wire1 support for ESP32
 - update readme.md
 - minor edits
 
-
 ## [0.3.8] - 2023-02-04
 - update readme.md
 - update GitHub actions

diff --git a/PCF8574.cpp b/PCF8574.cpp
@@ -2,7 +2,7 @@
 //    FILE: PCF8574.cpp
 //  AUTHOR: Rob Tillaart
 //    DATE: 02-febr-2013
-// VERSION: 0.3.9
+// VERSION: 0.4.0
 // PURPOSE: Arduino library for PCF8574 - 8 channel I2C IO expander
 //     URL: https://github.com/RobTillaart/PCF8574
 //          http://forum.arduino.cc/index.php?topic=184800
@@ -22,25 +22,8 @@ PCF8574::PCF8574(const uint8_t deviceAddress, TwoWire *wire)
 }
 
 
-#if defined (ESP8266) || defined(ESP32)
-bool PCF8574::begin(int dataPin, int clockPin, uint8_t value)
-{
-  if ((dataPin < 255) && (clockPin < 255))
-  {
-    _wire->begin(dataPin, clockPin);
-  } else {
-    _wire->begin();
-  }
-  if (! isConnected()) return false;
-  PCF8574::write8(value);
-  return true;
-}
-#endif
-
-
 bool PCF8574::begin(uint8_t value)
 {
-  _wire->begin();
   if (! isConnected()) return false;
   PCF8574::write8(value);
   return true;

diff --git a/PCF8574.h b/PCF8574.h
@@ -3,7 +3,7 @@
 //    FILE: PCF8574.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 02-febr-2013
-// VERSION: 0.3.9
+// VERSION: 0.4.0
 // 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,7 +13,7 @@
 #include "Wire.h"
 
 
-#define PCF8574_LIB_VERSION         (F("0.3.9"))
+#define PCF8574_LIB_VERSION         (F("0.4.0"))
 
 #ifndef PCF8574_INITIAL_VALUE
 #define PCF8574_INITIAL_VALUE       0xFF
@@ -29,9 +29,6 @@ class PCF8574
 public:
   explicit PCF8574(const uint8_t deviceAddress = 0x20, TwoWire *wire = &Wire);
 
-#if defined (ESP8266) || defined(ESP32)
-  bool    begin(int sda, int scl, uint8_t value = PCF8574_INITIAL_VALUE);
-#endif
   bool    begin(uint8_t value = PCF8574_INITIAL_VALUE);
   bool    isConnected();
 

diff --git a/README.md b/README.md
@@ -49,6 +49,15 @@ There are two examples to show how interrupts can be used:
 - PCF8574_rotaryEncoder.ino
 
 
+#### 0.4.0 Breaking change
+
+Version 0.4.0 introduced a breaking change.
+You cannot set the pins in **begin()** any more.
+This reduces the dependency of processor dependent Wire implementations.
+The user has to call **Wire.begin()** and can optionally set the Wire pins 
+before calling **begin()**.
+
+
 #### Related
 
 16 bit port expanders
@@ -87,24 +96,23 @@ However when performance is needed you can try to overclock the chip.
 #include "PCF8574.h"
 ```
 
-**PCF8574_INITIAL_VALUE** is a define that can be set compile time or before
+**PCF8574_INITIAL_VALUE** is a define 0xFF that can be set compile time or before
 the include of "pcf8574.h" to overrule the default value used with the **begin()** call.
 
 
-### Constructor
+#### Constructor
 
-- **PCF8574(uint8_t deviceAddress = 0x20, TwoWire \*wire = &Wire)** Constructor with optional device address, default 0x20, 
+- **PCF8574(uint8_t deviceAddress = 0x20, TwoWire \*wire = &Wire)** Constructor with optional address, default 0x20, 
 and the optional Wire interface as parameter.
-- **bool begin(uint8_t value = PCF8574_INITIAL_VALUE)** set the initial value for the pins and masks.
-- **bool begin(int sda, int scl, uint8_t value = PCF8574_INITIAL_VALUE)** idem, for the ESP32 where one can choose the I2C pins.
+- **bool begin(uint8_t value = PCF8574_INITIAL_VALUE)** set the initial value (default 0xFF) for the pins and masks.
 - **bool isConnected()** checks if the address set in the constructor or by **setAddress()** is visible on the I2C bus.
 - **bool setAddress(const uint8_t deviceAddress)** sets the device address after construction. 
 Can be used to switch between PCF8574 modules runtime. Note this corrupts internal buffered values, 
 so one might need to call **read8()** and/or **write8()**. Returns true if address can be found on I2C bus.
-- **uint8_t getAddress()** returns the device address.
+- **uint8_t getAddress()** Returns the device address.
 
 
-### Read and Write
+#### Read and Write
 
 - **uint8_t read8()** reads all 8 pins at once. This one does the actual reading.
 - **uint8_t read(uint8_t pin)** reads a single pin; pin = 0..7
@@ -116,7 +124,7 @@ value is HIGH(1) or LOW (0)
 - **uint8_t valueOut()** returns the last written data.
 
 
-### Button
+#### Button
 
 The **"button"** functions are to be used when you mix input and output on one IC.
 It does not change / affect the pins used for output by masking these.
@@ -133,7 +141,7 @@ Note this can be a subset of the pins set with **setButtonMask()** if one wants
 Background - https://github.com/RobTillaart/Arduino/issues/38
 
 
-### Special
+#### Special
 
 - **void toggle(const uint8_t pin)** toggles a single pin
 - **void toggleMask(const uint8_t mask = 0xFF)** toggles a selection of pins, 
@@ -147,7 +155,7 @@ Fills the lower lines with zero's.
 - **void reverse()** reverse the "bit pattern" of the lines, swapping pin 7 with 0, 6 with 1, 5 with 2 etc.
 
 
-### Select
+#### Select
 
 Some convenience wrappers.
 
@@ -161,7 +169,7 @@ This can typical be used to implement a VU meter.
 - **void selectAll()** sets all pins to HIGH.
 
 
-### Miscellaneous
+#### Miscellaneous
 
 - **int lastError()** returns the last error from the lib. (see .h file).
 

diff --git a/examples/PCF8574_Wire2/PCF8574_Wire2.ino b/examples/PCF8574_Wire2/PCF8574_Wire2.ino
@@ -2,12 +2,12 @@
 //    FILE: PCF8574_Wire2.ino
 //  AUTHOR: Rob Tillaart
 //    DATE: 2016-04-30
-// PUPROSE: demo
+// PURPOSE: demo
 
 
 #include "PCF8574.h"
 
-// adjust addresses if needed
+//  adjust addresses if needed
 PCF8574 PCF(0x39, &Wire2);
 
 
@@ -18,6 +18,8 @@ void setup()
   Serial.print("PCF8574_LIB_VERSION:\t");
   Serial.println(PCF8574_LIB_VERSION);
 
+  Wire2.begin();
+
   if (!PCF.begin())
   {
     Serial.println("could not initialize...");
@@ -75,5 +77,5 @@ void doToggle()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/PCF8574_interrupt/PCF8574_interrupt.ino b/examples/PCF8574_interrupt/PCF8574_interrupt.ino
@@ -2,7 +2,7 @@
 //    FILE: PCF8574_interrupt.ino
 //  AUTHOR: Rob Tillaart
 //    DATE: 2020-12-07
-// PUPROSE: test PCF8574 library
+// PURPOSE: test PCF8574 library
 //
 // TEST SETUP
 //   Connect INT pin of the PCF8574 to UNO pin 2
@@ -19,7 +19,7 @@ PCF8574 PCF(0x38);
 
 ////////////////////////////////////
 //
-// INTERRUPT ROUTINE + FLAG
+//  INTERRUPT ROUTINE + FLAG
 //
 const int IRQPIN = 2;
 
@@ -33,15 +33,16 @@ void pcf_irq()
 
 ////////////////////////////////////
 //
-// MAIN CODE
+//  MAIN CODE
 //
 void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
   Serial.print("PCF8574_LIB_VERSION: ");
   Serial.println(PCF8574_LIB_VERSION);
-
+
+  Wire.begin();
   PCF.begin();
 
   pinMode(IRQPIN, INPUT_PULLUP);
@@ -67,5 +68,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/PCF8574_isConnected/PCF8574_isConnected.ino b/examples/PCF8574_isConnected/PCF8574_isConnected.ino
@@ -2,12 +2,12 @@
 //    FILE: PCF8574_isConnected.ino
 //  AUTHOR: Rob Tillaart
 //    DATE: 2021-01-03
-// PUPROSE: demo isConnected function
+// PURPOSE: demo isConnected function
 
 
 #include "PCF8574.h"
 
-// adjust addresses if needed
+//  adjust addresses if needed
 PCF8574 PCF_39(0x39);
 
 
@@ -18,6 +18,8 @@ void setup()
   Serial.print("PCF8574_LIB_VERSION:\t");
   Serial.println(PCF8574_LIB_VERSION);
 
+  Wire.begin();
+
   if (!PCF_39.begin())
   {
     Serial.println("could not initialize...");
@@ -38,5 +40,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/PCF8574_performance/PCF8574_performance.ino b/examples/PCF8574_performance/PCF8574_performance.ino
@@ -2,7 +2,7 @@
 //    FILE: PCF8574_performance.ino
 //  AUTHOR: Rob Tillaart
 //    DATE: 2021-01-24
-// PUPROSE: test PCF8574 library at different I2C speeds.
+// PURPOSE: test PCF8574 library at different I2C speeds.
 
 
 #include "PCF8574.h"
@@ -19,6 +19,8 @@ void setup()
   Serial.print("PCF8574_LIB_VERSION:\t");
   Serial.println(PCF8574_LIB_VERSION);
 
+  Wire.begin();
+
   PCF.begin();
   Serial.println(PCF.isConnected());
 
@@ -50,4 +52,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
diff --git a/examples/PCF8574_rotaryEncoder/PCF8574_rotaryEncoder.ino b/examples/PCF8574_rotaryEncoder/PCF8574_rotaryEncoder.ino
@@ -2,7 +2,7 @@
 //    FILE: PCF8574_rotaryEncoder.ino
 //  AUTHOR: Rob Tillaart
 //    DATE: 2021-05-08
-// PUPROSE: demo PCF8574 as rotary encoder reader.
+// PURPOSE: demo PCF8574 as rotary encoder reader.
 //
 //
 //  RotaryEncoder    PCF8574      UNO
@@ -49,6 +49,7 @@ void setup()
   flag = false;
 
   Wire.begin();
+
   if (decoder.begin() == false)
   {
     Serial.println("\nERROR: cannot communicate to PCF8574.");
@@ -101,7 +102,7 @@ void updateRotaryDecoder()
 {
   uint8_t val = decoder.read8();
 
-  // check which of 4 has changed
+  //  check which of 4 has changed
   for (uint8_t i = 0; i < 4; i++)
   {
     uint8_t currentpos = (val & 0x03);
@@ -130,5 +131,5 @@ void updateRotaryDecoder()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/PCF8574_select/PCF8574_select.ino b/examples/PCF8574_select/PCF8574_select.ino
@@ -2,8 +2,7 @@
 //    FILE: PCF8574_select.ino
 //  AUTHOR: Rob Tillaart
 //    DATE: 2022-06-18
-// PUPROSE: demo PCF8574 library select functions
-
+// PURPOSE: demo PCF8574 library select functions
 
 
 #include "PCF8574.h"
@@ -20,6 +19,8 @@ void setup()
   Serial.print("PCF8574_LIB_VERSION:\t");
   Serial.println(PCF8574_LIB_VERSION);
 
+  Wire.begin();
+
   PCF.begin();
   Serial.println(PCF.isConnected());
   Serial.println();
@@ -29,14 +30,14 @@ void setup()
   PCF.selectNone();
   delay(1000);
 
-  // VU meter up
+  //  VU meter up
   for (int i = 0; i < 7; i++)
   {
     PCF.selectN(i);
     delay(100);
   }
 
-  // VU meter down
+  //  VU meter down
   for (int i = 7; i >= 0; i--)
   {
     PCF.selectN(i);
@@ -47,7 +48,7 @@ void setup()
 
 void loop()
 {
-  // night rider
+  //  night rider
   for (int i = 0; i < 7; i++)
   {
     PCF.select(i);
@@ -61,4 +62,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --