refactor API, begin() (#13)

- refactor API, begin()
- update readme.md
- update examples.

CHANGELOG.md

@@ -6,9 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
-## [0.1.7] - 2023-11-22
+## [0.2.0] - 2023-12-08
+- refactor API, begin()
 - update readme.md
+- update examples.
+
+----
 
+## [0.1.7] - 2023-11-22
+- update readme.md
 
 ## [0.1.6] - 2023-09-23
 - add Wire1 support for ESP32

README.md

@@ -18,7 +18,12 @@ Arduino library for TCA9555 16 channel I2C port expander.
 
 This library gives easy control over the 16 pins of a TCA9555 chip.
 
-The TCA9555 supports up to 400 kHz I2C.
+The pins can be used for input and output, and allow to set polarity.
+
+The pins can be set per pin, or with a mask to set either 8 or 16 pins
+in one call. 
+Note that for the 16 bit interface settings are not simultaneous as the
+16 bit interface does 2 calls to the 8 bit interface.
 
 
 #### TCA9535
@@ -33,12 +38,38 @@ There is a TCA9535 class which is a (convenience) wrapper around the TCA9555 cla
 This allows one to create TCA9535 objects. 
 
 
+#### 0.2.0 Breaking change
+
+Version 0.2.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
+
+- https://github.com/RobTillaart/MCP23017_RT
+- https://github.com/RobTillaart/MCP23S17
+- https://github.com/RobTillaart/PCF8575
+
+8 bit port expanders
+
+- https://github.com/RobTillaart/MCP23008
+- https://github.com/RobTillaart/MCP23S08
+- https://github.com/RobTillaart/PCF8574
+
+
 ## Hardware
 
-#### I2C addresses
+#### I2C
 
 Allowed addresses are 0x20..0x27. to be set with pin A0, A1, A2.
 
+The TCA9555 supports up to 400 kHz I2C.
+
 
 ## Interface
 
@@ -54,11 +85,9 @@ Check the datasheet for details
 Can be overruled with Wire0..WireN.
 - **TCA9535(uint8_t address, TwoWire \*wire = &Wire)** idem.
 - **uint8_t getType()** returns 35 or 55 depending on type.
-
-
-- **bool begin()** for UNO, returns true if successful.
-- **bool begin(uint8_t sda, uint8_t scl)** for ESP32, returns true if successful.
-- **bool isConnected()** returns true if connected, false otherwise.
+- **bool begin()** initializes library.
+Returns true if device can be seen on I2C bus, false otherwise.
+- **bool isConnected()** returns true if device can be seen on I2C bus, false otherwise.
 - **uint8_t getAddress()** returns set address, (debugging).
 
 
@@ -114,11 +143,6 @@ Reading it will reset the flag to **TCA9555_OK**.
 |  TCA9555_INVALID_READ  |  -100   |
 
 
-## Operation
-
-See examples
-
-
 ## Future
 
 
@@ -140,13 +164,13 @@ See examples
 #### Could
 
 - rethink class hierarchy
-  - TCA9535 has less functions so should be base class?
+  - TCA9535 has less functions so should be base class
 - valid address range?
 
 #### Wont (unless)
 
 - add TCA9535 error codes
-  - better reuse them?
+  - better reuse them?  ==> TCA95X5 codes
 
 
 ## Support

TCA9555.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: TCA9555.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.7
+// VERSION: 0.2.0
 // PURPOSE: Arduino library for I2C TCA9555 16 channel port expander
 //    DATE: 2021-06-09
 //     URL: https://github.com/RobTillaart/TCA9555
@@ -30,19 +30,9 @@ TCA9555::TCA9555(uint8_t address, TwoWire *wire)
 }
 
 
-#if defined(ESP8266) || defined(ESP32)
-bool TCA9555::begin(const uint8_t dataPin, const uint8_t clockPin)
-{
-  _wire->begin(dataPin, clockPin);
-  if (! isConnected()) return false;
-  return true;
-}
-#endif
-
-
 bool TCA9555::begin()
 {
-  _wire->begin();
+  if ((_address < 0x20) || (_address > 0x27)) return false;
   if (! isConnected()) return false;
   return true;
 }

TCA9555.h

@@ -2,7 +2,7 @@
 //
 //    FILE: TCA9555.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.7
+// VERSION: 0.2.0
 // PURPOSE: Arduino library for I2C TCA9555 16 channel port expander
 //    DATE: 2021-06-09
 //     URL: https://github.com/RobTillaart/TCA9555
@@ -12,7 +12,7 @@
 #include "Wire.h"
 
 
-#define TCA9555_LIB_VERSION               (F("0.1.7"))
+#define TCA9555_LIB_VERSION               (F("0.2.0"))
 
 #define TCA9555_OK                        0x00
 #define TCA9555_PIN_ERROR                 0x81
@@ -51,10 +51,6 @@ class TCA9555
 public:
   TCA9555(uint8_t address, TwoWire *wire = &Wire);
 
-
-#if defined(ESP8266) || defined(ESP32)
-  bool     begin(const uint8_t dataPin, const uint8_t clockPin);
-#endif
   bool     begin();
   bool     isConnected();
   uint8_t  getAddress();

examples/TCA9535_digitalRead/TCA9535_digitalRead.ino

@@ -15,6 +15,7 @@ TCA9535 TCA(0x27);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println(__FILE__);
   Serial.print("TCA9555_LIB_VERSION: ");
   Serial.println(TCA9555_LIB_VERSION);
 
@@ -37,5 +38,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/TCA9535_digitalWrite/TCA9535_digitalWrite.ino

@@ -15,6 +15,7 @@ TCA9535 TCA(0x27);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println(__FILE__);
   Serial.print("TCA9555_LIB_VERSION: ");
   Serial.println(TCA9555_LIB_VERSION);
 
@@ -26,7 +27,7 @@ void setup()
   Serial.println("TEST digitalWrite(0)");
   for (int i = 0; i < 16; i++)
   {
-    TCA.digitalWrite(0, i % 2);  // alternating HIGH/LOW
+    TCA.digitalWrite(0, i % 2);  //  alternating HIGH/LOW
     Serial.print(i % 2);
     Serial.print('\t');
     delay(250);
@@ -37,7 +38,7 @@ void setup()
   Serial.println("TEST digitalWrite(pin)");
   for (int pin = 0; pin < 16; pin++)
   {
-    TCA.digitalWrite(pin, 1 - pin % 2); // alternating HIGH/LOW
+    TCA.digitalWrite(pin, 1 - pin % 2);  //  alternating HIGH/LOW
     Serial.print(1 - pin % 2);
     Serial.print('\t');
   }
@@ -62,4 +63,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/TCA9555_digitalRead/TCA9555_digitalRead.ino

@@ -15,6 +15,7 @@ TCA9555 TCA(0x27);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println(__FILE__);
   Serial.print("TCA9555_LIB_VERSION: ");
   Serial.println(TCA9555_LIB_VERSION);
 
@@ -37,5 +38,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/TCA9555_digitalWrite/TCA9555_digitalWrite.ino

@@ -15,6 +15,7 @@ TCA9555 TCA(0x27);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println(__FILE__);
   Serial.print("TCA9555_LIB_VERSION: ");
   Serial.println(TCA9555_LIB_VERSION);
 
@@ -26,7 +27,7 @@ void setup()
   Serial.println("TEST digitalWrite(0)");
   for (int i = 0; i < 16; i++)
   {
-    TCA.digitalWrite(0, i % 2);  // alternating HIGH/LOW
+    TCA.digitalWrite(0, i % 2);  //  alternating HIGH/LOW
     Serial.print(i % 2);
     Serial.print('\t');
     delay(250);
@@ -37,7 +38,7 @@ void setup()
   Serial.println("TEST digitalWrite(pin)");
   for (int pin = 0; pin < 16; pin++)
   {
-    TCA.digitalWrite(pin, 1 - pin % 2); // alternating HIGH/LOW
+    TCA.digitalWrite(pin, 1 - pin % 2);  //  alternating HIGH/LOW
     Serial.print(1 - pin % 2);
     Serial.print('\t');
   }
@@ -62,5 +63,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/TCA9555_getType/TCA9555_getType.ino

@@ -16,9 +16,12 @@ TCA9535 TCA1(0x21);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println(__FILE__);
   Serial.print("TCA9555_LIB_VERSION: ");
   Serial.println(TCA9555_LIB_VERSION);
 
+  Wire.begin();
+
   Serial.println(TCA0.getType());
   Serial.println(TCA1.getType());
 }
@@ -29,4 +32,4 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --

examples/TCA9555_setPolarity/TCA9555_setPolarity.ino

@@ -14,6 +14,7 @@ TCA9555 TCA(0x27);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println(__FILE__);
   Serial.print("TCA9555_LIB_VERSION: ");
   Serial.println(TCA9555_LIB_VERSION);
 
@@ -53,5 +54,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/TCA9555.git"
   },
-  "version": "0.1.7",
+  "version": "0.2.0",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

library.properties

@@ -1,5 +1,5 @@
 name=TCA9555
-version=0.1.7
+version=0.2.0
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for I2C TCA9555 16 channel port expander - 16 IO-lines

test/unit_test_001.cpp

@@ -52,6 +52,8 @@ unittest(test_constructor_TCA9555)
 {
   TCA9555 TCA(0x22);
 
+  Wire.begin();
+
   assertTrue(TCA.begin());
   assertTrue(TCA.isConnected());
   assertEqual(55, TCA.getType());
@@ -62,6 +64,8 @@ unittest(test_constructor_TCA9535)
 {
   TCA9535 TCA(0x22);
 
+  Wire.begin();
+
   assertTrue(TCA.begin());
   assertTrue(TCA.isConnected());
   assertEqual(35, TCA.getType());
@@ -102,4 +106,6 @@ unittest(test_constants_II)
 
 unittest_main()
 
-// --------
+
+//  -- END OF FILE --
+