diff --git a/MCP23008-MCP23017.md b/MCP23008-MCP23017.md index 89f364dd..adc0b216 100644 --- a/MCP23008-MCP23017.md +++ b/MCP23008-MCP23017.md @@ -1,8 +1,8 @@ -### MCP230xx - Microchip MCP23008 / MCP23017 I2C GP INPUT +### MCP230xx - Microchip MCP23008 / MCP23017 I2C GPIO Expander Technical Data from the manufacturer: -* Microchip MCP23008: [https://www.microchip.com/wwwproducts/en/MCP23008](https://www.microchip.com/wwwproducts/en/MCP23008) -* Microchip MCP23017: [https://www.microchip.com/wwwproducts/en/MCP23017](https://www.microchip.com/wwwproducts/en/MCP23017) +* Microchip [MCP23008](https://www.microchip.com/wwwproducts/en/MCP23008) +* Microchip [MCP23017](https://www.microchip.com/wwwproducts/en/MCP23017) Generally available breakout boards for the MCP23017 look similar to this: @@ -10,25 +10,23 @@ Generally available breakout boards for the MCP23017 look similar to this: The MCP23008 has 8 IO pins which the MCP230xx driver uses as D0 - D7. The MCP23017 has 16 IO pins which the MCP230xx driver uses as D0 - D15. This is visualized in the circuit diagram below but it's important to note that the MCP23017 actually differentiates between PORTA (being A0 to A7) and PORTB (being B0 to B7) - The MCP230xx driver combines the two ports in sequence to translate to pins represented as D0 through D15 for the MCP23017. -The chip, can however, be wired up quite easily especially if you can source the DIP version of the chip. Here's a basic outline of what a typical circuit would require to be functional: +The chip can be connected quite easily, especially if you can source the DIP version of the chip. Here's a basic outline of what a typical circuit would require to be functional: ![Manual Wiring for MCP23008 / MCP23017](https://github.com/andrethomas/images/blob/master/mcp230xx/mcp230xx_manual_wiring_v2.png) -You will need to pick an I2C address in either of the above scenario's using the address mapping according to pin A0,A1 and A2 as from the datasheet as follows: +You will need to pick an I2C address in either of the above scenario's using the address mapping according to pin A0, A1, and A2 as from the datasheet as follows: ![MCP23008 / MCP23017 I2C Address Map](https://github.com/andrethomas/images/blob/master/mcp230xx/i2c_address_map.png) -You will need to define the address you are using in user_config_override.h for the driver to know which address the MCP23008/MCP23017 is expected to be found. +You will need to define the address you are using in `user_config_override.h` for the driver to know on which address the MCP23008/MCP23017 is expected to be found. `#define USE_MCP230xx_ADDR 0x20` The MCP23008/MCP23017 chips allow for both INPUT and OUTPUT - Most of the functionality of the driver is focused on INPUT mode - especially since they allow interrupt reporting and are 5V tolerant. -OUTPUT functionality is however available as pinmode 5 (Documented later in this Wiki) as an additional option for those who want to use the OUTPUT functionality using the sensor29 command at the expense of ~1Kbyte of flash. +OUTPUT functionality is however available as pinmode 5 (Documented later in this Wiki) as an additional option for those who want to use the OUTPUT functionality using the `Sensor29` command which consumes ~1Kbyte of flash. The driver is disabled by default in the Tasmota firmware so the only way to gain its use would be to perform a manual compilation of your own firmware. -The driver is disabled by default in the Tasmota firmware so the only way to gain its use would be to perform a manual compilation of your own firmware. - -There are three different levels in which functionality may be enabled, in the following order, by removing the remove the comment (#) out the relevant lines in user_config_override.h.) +There are three different levels in which functionality may be enabled, in the following order, by adding these lines in `user_config_override.h`: ``` #define USE_MCP230xx // Enable INPUT mode (pinmode 1 through 4) #define USE_MCP230xx_OUTPUT // Enable OUTPUT mode (pinmode 5) @@ -51,122 +49,44 @@ The MCP230xx chip (or breakout board) must be connected to the ESP8266 and the I ![https://github.com/andrethomas/images/raw/master/mcp230xx/Generic_Config_Menu.PNG](https://github.com/andrethomas/images/raw/master/mcp230xx/Generic_Config_Menu.PNG) -One that is complete you may want to confirm that the Tasmota firmware is finding your MCP23008/MCP23017 chip by sending the command through serial or MQTT: - -``I2Cscan`` - -You should see a response giving you an address within the range of the MCP23008/MCP23017 chip (0x20 through 0x27) which may look as follows +One that is complete you may want to confirm that the Tasmota firmware is finding your MCP23008/MCP23017 chip by sending the command through serial or MQTT: +`I2Cscan` +You should see a response giving you an address within the range of the MCP23008/MCP23017 chip (0x20 through 0x27) which may look as follows `MQT: stat/sonoff/RESULT = {"I2CScan":"Device(s) found at 0x20"}` -If you do not find it, check your wiring and pin configuration. +If the extender is not detected, check your wiring and pin configuration. -The configuration of MCP23008/MCP23017 by using sensor29 commands via serial, web console or MQTT messages - -In order to use the MCP23008/MCP23017 in your build you need to remove the comment (#) for the following two lines in your user_config_override.h as the MCP chip support is not enabled by default +The configuration of MCP23008/MCP23017 by using `Sensor29` commands via the Console or MQTT messages. +In order to use the MCP23008/MCP23017, add the following two lines in your `user_config_override.h` as the MCP chip support is not enabled by default. ``` #define USE_MCP230xx #define USE_MCP230xx_ADDR 0x20 ``` -The MCP23008/MCP23017 supports I2C address range of 0x20 through 0x27 so be careful you are not using an address which is already used by another device (e.g. 0x27 is a known address for some I2C Liquid Crystal Displays) +The MCP23008/MCP23017 supports I2C address range of 0x20 through 0x27. Take care that you are not using an address which is already used by another device (e.g., 0x27 is a known address for some I2C Liquid Crystal Displays). -The behaviour of all pins on the MCP23008/MCP23017 can be reset to a specific setting/mode globally to simplify the initial configuration as follows +## Device Configuration +The behavior of all pins on the MCP23008/MCP23017 can be reset to a specific setting/mode globally to simplify the initial configuration as follows -``` -sensor29 reset // Reset all pins INPUT, no interrupt, no pull-up by default -sensor29 reset1 // Reset all pins INPUT, no interrupt, no pull-up by default -sensor29 reset2 // Reset all pins INT on CHANGE, with pull-up enabled by default -sensor29 reset3 // Reset all pins INT on LOW, with pull-up enabled by default -sensor29 reset4 // Reset all pins INT on HIGH, with pull-up enabled by default -sensor29 reset5 // Reset all pins to OUTPUT mode (if enabled by #define USE_MCP230xx_OUTPUT) -``` +Command|Parameters +-|- +Sensor29|MCP23008 / MCP23017 I2C GPIO Expander configuration
`Reset` = reset all pins
x = `1..5`
`1` = INPUT mode, no reporting, no pull-up
`2` = INPUT mode, report on CHANGE, pull-up enabled
`3` = INPUT mode, report on LOW, pull-up enabled
`4` = INPUT mode, report on HIGH, pull-up enabled
`5` = OUTPUT mode (if enabled by #define USE_MCP230xx_OUTPUT)

`pin,pinmode{,intpullup\|outstate{,repmode}}``pin` = the I/O pin on the MCP230xx chip`pinmode` = operational mode of the pin (`?, 0..5`)`intpullup` *(pinmode `1..4`)*. Pull-up resistors are disabled by default for pin mode `1` whilst enabled by default for pin modes `2..4` (because they are interrupt enabled pins and we do not want signal bounce). The internal pull-up on these pins may be disabled if necessary if you are biasing them externally.`outstate` *(pinmode `5..6`)* = set the default state of an OUTPUT pin on reset/power-up. If your device is configured to save state (`SetOption0 = 1`), the `outstate` setting will be ignored and the last known state of the pin will be applied during power-up/reset.`repmode` = reporting mode (optional). Interrupt mode is disabled for pinmode `1` and for output pinmodes (`5..6`) -The command will respond with confirmation as follows: +Examples: +`Sensor29 Reset1` +`MQT: stat/sonoff/RESULT = {"Sensor29_D99":{"MODE":1,"PULL_UP":"OFF","INT_MODE":"DISABLED","STATE":""}}` +Pin and State is reported as 99 because it is set across all pins. +Mode should correspond with the reset pinmode option used. -`MQT: stat/sonoff/RESULT = {"Sensor29_D99":{"MODE":1,"PULL_UP":"OFF","INT_MODE":"DISABLED","STATE":""}}` - -Pin and State is reported as 99 because it was implemented accross all pins. - -Mode should correspond with the reset pinmode option used. - -Internal pull-up resistors on the MCP23008/MCP23017 is disabled by default for pin mode 1 whilst enabled by default for pin modes 2 through 4 (because they are interrupt enabled pins and we do not want them bouncing up and down - you may disable the internal pull-up on these pins using the sensor29 commands described below if you are biasing them externally) - -INT_MODE is disabled for pin mode 1 and pinmodes 5 and 6 (OUTPUT modes) since interrupts are not available for these pin modes. - -If specific pins require specific configuration after this command has been issued the pins may individually be configured using: - -`sensor29 pin,pinmode,pullup` - -For pinmode's 2 through 4 you may also pass an additional optional parameter to set the required behaviour of interrupts on a particular pin, for example: - -`sensor29 pin,pinmode,pullup,intmode` - -Where intmode can be 0 through 3 - -If no parameter value for intmode is passed, it will default to intmode 0. - -The usage of the above is described in more detail further in this page. - -The configuration of a specific pin may be queried using command: - -`sensor29 0,?` - -Will report as follows: - -`MQT: stat/sonoff/RESULT = {"Sensor29_D0":{"MODE":1,"PULL_UP":"OFF","INT_MODE":"DISABLED","STATE":"ON"}}` - -Confirming that the pin is in pinmode 1 and that the pull-up resistor is not enabled. - -INT_MODE indicates the interrupt mode for pins which are interrupt enabled (pinmode 2 through 4) - In the example above it is disabled for pin mode 1 (INPUT without INTERRUPT) - -The current STATE of the pin as ON or OFF is reported as at the time the command is issued is also reported. - -The format for sending configuration messages for individual pins via serial, web console or MQTT messages are as follows: - -`sensor29 pin,pinmode,pullup` - -Or optionally specifying the desired interrupt mode for pin modes 2 through 4 using: - -`sensor29 pin,pinmode,pullup,intmode` - -Where: - -**pin** = The digital IO pin on the MCP230xx chip as a numeric e.g. 0 through 7 for MCP23008 and 0 through 15 for the MCP23017 - -**pinmode** = The operational mode of the pin as follows: - -**0** = Disabled (Deprecated, but will be default for previously unconfigured devices) - -**1** = INPUT (Floating - only telemetry data will be sent according to Tasmota firmware configuration intervals - -**2** = INPUT with INTERRUPT on CHANGE (Will send an MQTT output on state change from LOW to HIGH **and** HIGH to LOW) - -**3** = INPUT with INTERRUPT on CHANGE to **LOW** (Will send an MQTT output on state change **only** from HIGH to LOW) - -**4** = INPUT with INTERRUPT on CHANGE to **HIGH** (Will send an MQTT output on state change **only** from LOW to HIGH) - -**5** = OUTPUT (if enabled with #define USE_MCP230xx_OUTPUT) - -**pullup** = The operational mode of the pin as follows: - -**0** = Weak internal pull-up **DISABLED** - -**1** = Weak internal pull-up **ENABLED** - -**intmode** = Optionally specify the interrupt reporting mode as follows - defaults to 0 if not specified - -**0** = Immediate interrupt report using TELEMETRY and EVENT - -**1** = Immediate EVENT only (no telemetry reported) - -**2** = Immediate TELEMETRY only (no EVENT caused) - -Weak internal pull-up resistors are only enabled for pinmode 1 through 4 (being INPUT of nature) but the same parameter may also be used to set the default state of an OUTPUT pin on reset/power-up. If your device is configured to SAVE_STATE (setoption0 = 1) then this will be ignored during power-up/reset and the last known state of the pin will be applied during power-up/reset. +`Sensor29 0,?` +`MQT: stat/sonoff/RESULT = {"Sensor29_D0":{"MODE":1,"PULL_UP":"OFF","INT_MODE":"DISABLED","STATE":"ON"}}` +Confirming that the pin is in pinmode 1 and that the pull-up resistor is not enabled. +INT_MODE indicates the interrupt mode for pins which are interrupt enabled (pinmode 2 through 4) - In the example above it is disabled for pin mode 1 (INPUT without INTERRUPT) +The current STATE of the pin as ON or OFF is reported as at the time the command is issued is also reported. ### IMPORTANT NOTICE ON USE OF INTERRUPTS - **_Only use interrupts on pins which are either explicitly pulled down GND or up to VCC externally as floating pins may cause unintended MQTT responses for pins which are floating. So unless your connected wire/device explicitly pulls the pin to GND or VCC only when conditions of an interrupt would be met it is recommended that you either do not set a pin for an interrupt mode or at least enable pull-up resistors for the unused pins with pullup = 1 when you perform your sensor29 pin,pinmode,pullup command._** Examples of some pin configuration options: