0.2.1 TCA9548

Author: RobTillaart

libraries/TCA9548/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.2.1] - 2023-12-09
+- add derived classes
+  - PCA9543 (2 channel), PCA9545 (4 channel), PCA9546 (4 channel)
+- add **uint8_t getInterruptMask()**
+- fix begin() : remove wire-> begin() as dependency should be outside lib
+- fix readme.md
+
+
 ## [0.2.0] - 2023-12-09
 - refactor API, begin()
 - update readme.md

libraries/TCA9548/README.md

@@ -11,25 +11,42 @@
 
 # TCA9548
 
-Arduino Library for TCA9548 I2C multiplexer.
+Arduino Library for TCA9548 I2C multiplexer and compatibles.
 
 
 ## Description
 
-Library for the TCA9548 and TCA9548a (PCA9548, PCA9548a) I2C multiplexer.
+Library for the TCA9548 and TCA9548a 8 channel I2C multiplexer.
 
-The library allows you to enable 0 to 7 I2C channels (ports) uniquely or simultaneously.
-This is especially useful if you have multiple devices/sensors that have a fixed address,
-or you have address conflicts between I2C devices
+Compatible with PCA9548, PCA9548a, PCA9546, PCA9545, PCA9543.
+
+The library allows you to enable 0 to 7 I2C channels (SDA + SCL) uniquely or simultaneously.
+In fact the TCA9548 is therefore a **switch**, although often named a multiplexer.
+A multiplexer is useful if you have 
+- multiple identical devices that have a fixed address,
+- a too small address range or 
+- if there are address conflicts between different I2C devices.
+
+The library caches the channels enabled, and if a channel is enabled,
+it will not be enabled again (low level) to optimize performance.
+
+The device works with 2.3 V to 5.5 V so it should work with most MCU's.
 
 **Warning**
 The library is not tested extensively.
 
+
+#### I2C 
+
 I2C address of the device itself is 0x70 .. 0x77.
-This address may not be used on any of the I2C channels of course.
+This address can not be used on any of the I2C channels of course.
 
-The library caches the channels enabled, and if a channel is enabled,
-it will not be enabled again (low level) to optimize performance.
+Note if your first multiplexer is 0x70, you may have an array of 0x71 multiplexers behind it.
+(This will give 8 x 8 = 64 I2C buses, a lot of admin overhead and probably performance penalties).
+
+Pull-up resistors are required on all upstream and downstream channels.
+
+The TCA9548 can work up to 400 KHz according to the datasheet.
 
 
 #### 0.2.0 Breaking change
@@ -38,28 +55,30 @@ 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()**.
+before calling the TCA9548 **begin()**.
 
 
 #### Compatible devices
 
-This library is expected to work for the PCA9548(a) too as the TCA is pin compatible newer version.
+This library is expected to work for the following devices: (since 0.2.1)
 
-|  Device    |  Tested  |  Notes  |
-|:-----------|:--------:|:-------:|
-|  TCA9548s  |    n     |
-|  PCA9548   |    n     |  see links below  |
-|  PCA9548a  |    n     |
+|  device   |  address  |  channel  |  interrupt  |  reset  |  verified  |  notes  |
+|:---------:|:---------:|:---------:|:-----------:|:-------:|:----------:|:-------:|
+|  PCA9543  |     4     |     2     |      Y      |    Y    |      N     |
+|  PCA9545  |     4     |     4     |      Y      |    Y    |      N     |
+|  PCA9546  |     8     |     4     |             |    Y    |      N     |
+|  PCA9548  |     8     |     8     |             |    Y    |      N     |  equals TCA9648 
+|  PCA9548  |     8     |     8     |             |    Y    |      N     |  equals TCA9648 
 
 
+Note: these are not tested with hardware yet, please share your experiences.
 
 There are however small differences, check the data sheets to see the details.
 - [difference TCA PCA](https://e2e.ti.com/support/interface-group/interface/f/interface-forum/815758/faq-what-is-the-difference-between-an-i2c-device-with-the-family-name-pca-and-tca)
 - https://electronics.stackexchange.com/questions/209616/is-nxps-pca9548a-compatible-with-tis-tca9548a
 - https://www.nxp.com/docs/en/application-note/AN262.pdf
 
 
-
 #### Related
 
 - https://github.com/RobTillaart/HC4051  (1x8 mux)
@@ -78,52 +97,62 @@ There are however small differences, check the data sheets to see the details.
 
 - **TCA9548(const uint8_t deviceAddress, TwoWire \*wire = &Wire)** Constructor.
 deviceAddress = 0x70 .. 0x77, wire = Wire or WireN.
-- **bool begin(uint8_t dataPin, uint8_t clockPin, uint8_t mask = 0x00)**  Set I2C pins for ESP32.
-Set mask of channels to be enabled, default all disabled.
 - **bool begin(uint8_t mask = 0x00)**  set mask of channels to be enabled, default all disabled.
 - **bool isConnected()** returns true if address of the multiplexer is found on I2C bus.
 
 
-The derived class PCA9548 has same interface, except constructor.
+The derived classes PCA9548/PCA9546 have the same interface, except constructor.
+(see #15)
 
 - **PCA9548(const uint8_t deviceAddress, TwoWire \*wire = &Wire)** Constructor.
-deviceAddress = 0x70 .. 0x77, wire = Wire or WireN.
+- **PCA9546(const uint8_t deviceAddress, TwoWire \*wire = &Wire)** Constructor.
+- **PCA9545(const uint8_t deviceAddress, TwoWire \*wire = &Wire)** Constructor.
+- **PCA9543(const uint8_t deviceAddress, TwoWire \*wire = &Wire)** Constructor.
 
 
 #### Find device
 
 - **bool isConnected(uint8_t address)** returns true if arbitrary address is found on I2C bus.
-This can be used to verify a certain device is available (or not) on an enabled channel.
+This can be used to verify if a certain device is available (or not) on an **enabled** channel.
+So it does not scan all 8 channels to see if any of them has a device with the address given.
 
 
 #### Channel functions
 
 All "channel functions" return true on success.
 
-- **bool enableChannel(uint8_t channel)** enables channel 0 .. 7 non-exclusive.
+- **bool enableChannel(uint8_t channel)** enables channel 0 .. 7 **non-exclusive**.  
 Multiple channels can be enabled in parallel.
 - **bool disableChannel(uint8_t channel)** disables channel 0 .. 7.
 Will not disable other channels.
-- **bool selectChannel(uint8_t channel)** enables a single channel 0 .. 7 exclusive.
+- **bool selectChannel(uint8_t channel)** enables a single channel 0 .. 7 **exclusive**.  
 All other channels will be disabled in the same call, so not before or after.
 - **bool isEnabled(uint8_t channel)** returns true if the channel is enabled.
-- **bool disableAllChannels()** fast way to disable all.
+- **bool disableAllChannels()** fast way to disable all channels.
+
+Multiple channels can also be enabled in one call with a mask.
+
 - **bool setChannelMask(uint8_t mask)** enables 0 or more channels simultaneously with a bit mask.
 - **uint8_t getChannelMask()** reads back the bit mask of the channels enabled.
 
 
 #### Reset
 
-- **void setResetPin(uint8_t resetPin)** sets the pin to reset the chip. (Not tested)
+Optional the library can reset the device.
+
+- **void setResetPin(uint8_t resetPin)** sets the pin to reset the chip.
 - **void reset()** trigger the reset pin.
+
+#### Debug
+
 - **int getError()** returns the last I2C error.
 
 
 #### Forced IO
 
-When forced IO is set all writes and read - **getChannelMask()** - will go to the device.
-If the flag is set to false it will cache the value of the channels enabled.
-This will result in more responsive / faster calls.
+When forced IO is set, all writes and read, e.g. **uint8_t getChannelMask()**, will go to the device.
+If the **forced-IO** flag is set to false, it will cache the value of the channels enabled.
+This will result in far more responsive and faster calls.
 Note that writes are only optimized if the channels are already set.
 
 - **void setForced(bool forced = false)** set forced write, slower but more robust.
@@ -132,39 +161,27 @@ Note that writes are only optimized if the channels are already set.
 - **bool getForced()** returns set flag.
 
 
+#### Interrupts
+
+The PCA9545 and PCA9543 support interrupts. 
+These two derived classes have implemented the
+
+- **uint8_t getInterruptMask()** function that returns a bit mask of interrupts set.
+
+
 ## Error Codes
 
-Not implemented yet, preparation for 0.2.0.
+Not implemented yet, preparation for future.
 
 |  name                   |  value  |  description            |
 |:------------------------|:-------:|:------------------------|
-|  TCA9548_OK             |  00     |  no error               |
+|  TCA9548_OK             |   00    |  no error               |
 |  TCA9548_ERROR_I2C      |  -10    |  detected an I2C error  |
 |  TCA9548_ERROR_CHANNEL  |  -20    |  channel out of range   |
 
 
 ## Future
 
-#### PCA954X family
-
-To investigate if these can be made in one derived class tree.
-
-|  chip     |  address  |  channel  |  interrupt  |  reset  |  notes  |
-|:---------:|:---------:|:---------:|:-----------:|:-------:|:-------:|
-|  PCA9540  |     -     |     2     |             |         |  address programmable
-|  PCA9641  |  4 pins   |     2     |             |         |  master selector
-|  PCA9542  |  3 pins   |     2     |   Y         |         |
-|  PCA9543  |  2 pins   |     2     |   Y         |    Y    |
-|  PCA9544  |  3 pins   |     4     |   Y         |         |
-|  PCA9545  |  2 pins   |     4     |   Y         |    Y    |
-|  PCA9546  |  3 pins   |     4     |             |    Y    |
-|  PCA9548  |  3 pins   |     8     |             |    Y    |  equals TCA9648 
-
-- Most could work if a "channels" was defined and if internals are enough similar.
-- RESET pin is supported in TCA9548
-- INT is more a user code issue.
-- might need a **type()**?
-
 
 #### Must
 
@@ -174,17 +191,13 @@ To investigate if these can be made in one derived class tree.
 #### Should
 
 - add examples.
-- test test and test.
-- write unit test.
-- create derived classes for compatible devices (0.2.0).
-  - see above PCA9548 and PCA9548a.
-- investigate support derived classes
-
+- test with hardware.
 
 #### Could
 
 - set an "always enabled" mask.
   - investigate the consequences!
+- extend the unit tests.
 
 #### Wont