Merge branch 'pcf8574' of git-barbudor:barbudor/docs into pcf8574

Author: barbudor

docs/Blinds-and-Shutters.md

@@ -74,7 +74,7 @@ To enable additional shutters, `ShutterRelay<x> <value>` must be executed for ea
 
 Disabling a shutter in the middle of the defined set of shutters will disable all other higher numbered shutters. If the disabled shutter is restored, the higher numbered shutters previously declared will also be restored. When a shutter is added or removed, a list of the active shutters, with their parameters, is output to the log. If you intend to remove shutters, explicitly remove each one beginning with the highest numbered shutter.
 
-With four shutters, eight `Relay<x>` components are needed. If manual operation switches (`Switch<x>` or `Button<x>` pairs) are also used, additional input GPIO are required. The ESP82xx device may not have enough free GPIO to support all the shutter connections required. A GPIO expander such as a PCF8574 or [MCP230xx](MCP230xx) can be used with additional effort.
+With four shutters, eight `Relay<x>` components are needed. If manual operation switches (`Switch<x>` or `Button<x>` pairs) are also used, additional input GPIO are required. The ESP82xx device may not have enough free GPIO to support all the shutter connections required. A GPIO expander such as a [PCF8574](PCF8574) or [MCP230xx](MCP230xx) can be used with additional effort.
 
 Using manual operation `Switch<x>` pairs may require setting `SwitchMode<x> 4` (inverse follow) for proper switch behavior.
 

docs/Commands.md

@@ -448,7 +448,7 @@ SetOption77<a class="cmnd" id="setoption77"></a>|Do not power off if a slider is
 SetOption78<a class="cmnd" id="setoption78"></a>|Version check on Tasmota upgrade<BR>`0` = enabled _(default)_<BR>`1` = disabled
 SetOption79<a class="cmnd" id="setoption79"></a>|Reset counters at TelePeriod time<BR>`0` = disabled _(default)_<BR>`1` = enabled
 SetOption80<a class="cmnd" id="setoption80"></a>|[Blinds and shutters](Blinds-and-Shutters) support<BR>`0` = disable blinds and shutters support *(default)*<BR>`1` = enable blinds and shutters support
-SetOption81<a class="cmnd" id="setoption81"></a>|Set PCF8574 component behavior for all ports<BR>`0` = set as regular state *(default)*<BR>`1` = set as inverted state
+SetOption81<a class="cmnd" id="setoption81"></a>|Set [PCF8574](PCF8574) component behavior for all ports<BR>`0` = set as regular state *(default)*<BR>`1` = set as inverted state
 SetOption82<a class="cmnd" id="setoption82"></a>|Reduce the CT range from 153..500 to 200.380 to accomodate with Alexa range<BR>`0` = CT ranges from 153 to 500 *(default)*<BR>`1` = CT ranges from 200 to 380 (although you can still set in from 153 to 500)
 SetOption83<a class="cmnd" id="setoption83"></a>|Uses Zigbee device friendly name instead of 16 bits short addresses as JSON key when reporting values and commands<BR>`0` = JSON key as short address<BR>`1` = JSON key as friendly name<BR>See [`ZbName <device>,<name>`](#zbname)
 SetOption84<a class="cmnd" id="setoption84"></a>|(Experimental) When using AWS IoT, sends a device shadow update (alternative to retained)<BR>`0` = don't update device shadow (default)<BR>`1` = update device shadow<BR>Note: if the `Topic` contains `'/'` they are replaced with `'_'`

docs/PCF8574.md

@@ -0,0 +1,145 @@
+# PCF8574 / PCF8574A GPIO Expander
+
+## TL;DR;
+
+PCF8574 IO expander allows to add up to 32 digital IO pins to Tasmota
+
+!!! Warning
+    The driver for PCF8574 is not included in any of Tasmota prebuild binaries. See [compiling for PCF8574](#compiling-for-pcf8574).
+
+## Introduction
+
+PCF8574 and PCF8574A are I2C 8-bit IOport extender originally designed by Philips (now NXP) but also 
+now available from various manufacturer.
+
+* PCF8574 and PCF8574A at [NXP](https://www.nxp.com/docs/en/data-sheet/PCF8574_PCF8574A.pdf)
+* [PCF8574](https://www.ti.com/lit/ds/symlink/pcf8574.pdf) and [PCF8574A](https://www.ti.com/lit/ds/symlink/pcf8574a.pdf) at Texas Instruments
+
+As usual when using an electronic part, reading the datasheet is highly recommended as the below 
+document only focus on Tasmota integration.
+
+A few different breakout boards are available although some are dedicated to be mounted as a backpack on
+standard 16x2 or 16x4 LCD displays and are not suitable for general I/Os (but works well with tasmota-display).
+
+![PCF8574 breakout modules](_media/pcf8574_module.png)
+
+* On the left: generic modules suitable for extending IO
+* On the right: specific module to control a LCD display (not the purpose of this doc page)
+
+## Supported I2C addresses and number of PCF8574
+
+PCF8574 and PCF8574A are identical functionally and each can be configured to work on 1 of 8 possible I2C address.
+PCF8574 can use one address of 0x20 to 0x27 and PCF8574A can use one of 0x38 to 0x3F.
+
+As of today, Tasmota driver supports :
+
+* Up to 4 PCF8574 OR PCF8574A is supported by Tasmota allowing up to 32 additional GPIO pins.
+* Addresses 0x27 and 0x38 are excluded to avoid conflict with other I2C peripheral which can't 
+  be differentiated at run-time.
+* if USE_MCP230xx_ADDR is defined, this address is reserved for MCP230XX IO expander.
+
+## Enabling the driver
+
+Once the firmware with the PCF8574 driver has been loaded, be sure to have it enabled with `I2Cdriver22 1`. 
+
+## Compiling for PCF8574
+
+The PCF8574 driver is not included by default in any Tasmota [build](https://github.com/arendst/Tasmota/blob/development/BUILDS.md).
+In order to use it you must [compile](https://tasmota.github.io/docs/Compile-your-build/) your own tasmota build
+by adding the following lines to your `user_config_override.h`:
+``` c++
+#define USE_I2C                                // Add support for I2C
+#define USE_PCF8574                            // [I2cDriver2] Enable PCF8574 I/O Expander (I2C addresses 0x20 - 0x26 and 0x39 - 0x3F) (+1k9 code)
+// #define USE_PCF8574_SENSOR                   // enable PCF8574 inputs and outputs in SENSOR message
+// #define USE_PCF8574_DISPLAYINPUT             // enable PCF8574 inputs display in Web page
+// #define USE_PCF8574_MQTTINPUT                // enable MQTT message & rule process on input change detection : stat/%topic%/PCF8574_INP = {"Time":"2021-03-07T16:19:23+01:00","PCF8574-1_INP":{"D1":1}}
+```
+
+* The first 2 lines are mandatory to enable I2C support and including the driver in the build.
+* By default only "outputs" feature are enabled
+* The 3 other lines allows to add optional features to support inputs
+
+## PCF8574 configuration
+
+PCF8574 can be configured from Tasmota web GUI in "Configure" => "Configure PCF8574"
+![PCF8574 configuration screen](_media/pcf8574_configure.png)
+
+* Each IO port can be configured as Input or Output in a similar way as an native GPIO of the ESP.
+* If you are using outputs to drive relays, it is possible to choose if the relay is activated by a 
+  HIGH signal (checkbox "Invert Ports" unchecked) or a LOW signal (checkbox checked). The selection 
+  applies to all output ports. This checkbox can also be controlled by [SetOption81](Commands#setoption81).
+
+Once configuration is complete. It must be saved by clicking on the green "Save" button. Like for 
+general ESP GPIO configuration, this will trigger a reboot of the ESP.
+
+!!! note
+    It is not possible to change pin definition at run-time.
+
+## PCF8574 Ouputs
+
+A PCF8574 pin configured as an output support all features of a Tasmora `Relay` component.
+
+* It is assigned a Power index and can be controlled by [Power](Commands#power) command (on, off, toggle).
+  Power indexes of PCF8574 outputs are assigned after the ESP GPIO configured as `Relay`. For example,
+  if you have Relay 1 (Power1) to Relay 4 (Power4) configured on the ESP's GPIO, PCF8574 outputs will start at Power5.
+* A state text and an on/off button is automatically created on the Web GUI and syncs with the pin state.
+* All `Power` features are supported including `PowerOnState`, `PulseTime`, `Blink`, `SetOption0`, ...
+
+![PCF8574 power GUI](_media/pcf8574_powergui.png)
+
+## PCF8574 Inputs
+
+In order to use PCF8574 inputs, you must add at least one of the following build-time option in
+your `user_config_override.h`:
+
+``` c++
+#define USE_PCF8574_SENSOR                   // enable PCF8574 inputs and outputs in SENSOR message
+#define USE_PCF8574_DISPLAYINPUT             // enable PCF8574 inputs display in Web page
+#define USE_PCF8574_MQTTINPUT                // enable MQTT message & rule process on input change detection : stat/%topic%/PCF8574_INP = {"Time":"2021-03-07T16:19:23+01:00","PCF8574-1_INP":{"D1":1}}
+```
+
+### PCF8574 in SENSOR message
+
+Enabling `USE_PCF8574_SENSOR` adds a `PCF8574-xx` field into the JSON payload of the `tele/topic/SENSOR`
+message. The form of the message is:
+``` json
+{"Time":"2021-03-11T19:50:58+01:00","PCF8574-1":{"D0":1,"D1":1,"D2":1,"D3":1,"D4":0,"D5":0,"D6":0,"D7":0}}
+``` 
+
+As you can see, all pins are listed, including both inputs and outputs. The value reported is the
+digital level of the pin. If "Invert Ports" has been enabled, `Power ON` will be reported as 0 as
+the pin is at a LOW level.
+
+As for any sensor published in the `tele/topic/SENSOR` message, it is possible to use Rules triggers such as:
+```
+ON tele-PCF8574-1#D0 DO something_with %value% ENDON
+```
+Numerical operators such as `==` can be used to compare to 0 or 1. See also [change detection](#input-change-detection).
+
+### PCF8574 inputs pins in the Web GUI
+
+Enabling `USE_PCF8574_DISPLAYINPUT` will add the state of PCF8574 inpupts displayed as sensors
+in the Web GUI. Outputs are not represented here as they are already shown as Power.
+
+![PCF8574 inputs GUI](_media/pcf8574_inputgui.png)
+
+Value of pin is updated in almost "real-time".
+
+### Input change detection
+
+While reporting the pin level in SENSOR or on the GUI is interresting, it is more interresting to
+detect pin change. This is enabled by `USE_PCF8574_MQTTINPUT`. When this feature is enabled at
+build time, a test will be performed every 50ms to detect if an input pin has changed. In that case,
+Tasmota will publish on `stat/topic/PCF8574_INP` a JSON payload with the PCF8574 index
+and the pin level:
+``` json
+20:19:39.385 MQT: stat/topic/PCF8574_INP = {"Time":"2021-03-11T20:19:39+01:00","PCF8574-1_INP":{"D0":0}}
+20:19:39.584 MQT: stat/topic/PCF8574_INP = {"Time":"2021-03-11T20:19:39+01:00","PCF8574-1_INP":{"D0":1}}
+```
+
+This can be catched in rules such as:
+
+* Implementing a Power push "Button":
+``` haskel
+ON PCF8574-1_INP#D0=0 DO Power2 toggle ENDON
+```

docs/Supported-Peripherals.md

@@ -65,7 +65,7 @@ Name|Description
 [**PAJ7620**](PAJ7620) | Gesture & Proximity Detection Sensor
 [**PIR**](PIR-Motion-Sensors#am312) | Passive Infrared Sensor (gpio)
 [**PCA9685**](PCA9685) | 16-channel, 12-bit PWM LED controller (I^2^C)
-**PCF8574** | 8-port IO Expander (I^2^C) 
+[**PCF8574(A)**](PCF8574) 8-port IO Expander (I^2^C) 
 **PMS3003<BR>[PMS5003](https://www.superhouse.tv/38-diy-air-quality-Sensor-part-1-basic-model/)<BR>PMS7003** | Particle Concentration Sensor (serial)
 [**PN532**](PN532) | NFC/RFID controller
 [**PZEM-004<BR>PZEM-016**](PZEM-0XX) | Energy Monitor (serial)