MCP23008 MCP23017 - RTurala/Sonoff-Tasmota GitHub Wiki

MCP230xx - Microchip MCP23008 / MCP23017 I2C GP INPUT

Technical Data from the manufacturer:

• 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:

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 visualised 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:

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 define the address you are using in the user_config.h or user_config_override.h (if you use that method) for the driver to know 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.

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 uncommenting the relevant lines in the user_config.h file (or added to the user_config_override.h file if you are using that option.)

#define USE_MCP230xx                 // Enable INPUT mode (pinmode 1 through 4)
#define USE_MCP230xx_OUTPUT          // Enable OUTPUT mode (pinmode 5)
#define USE_MCP230xx_DISPLAYOUTPUT   // Display state of OUTPUT pins on main Tasmota web interface

The ESP8266 will automatically detect whether you have connected an MCP23008 (8 input) or MCP23017 (16 input) and will provide telemetry data in accordance with how the device was configured from within the Tasmota firmware.

If OUTPUT is enabled, telemetry data for the current state of OUTPUT pins will also be provided by telemetry.

MCP23008 / MCP23017 Pin numbers in Tasmota compared to datasheets

The table below outlines how the pins of the MCP23008/MCP23017 are assigned:

Usage of the driver

The MCP230xx chip (or breakout board) must be connected to the ESP8266 and the I2C pins must be configured for the module similar to the following:

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.

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 uncomment the following two lines in your user_config.h or 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 behaviour 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)

The command will respond with confirmation as follows:

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 interal 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.

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:

sensor29 4,1,0 - Will enable D4 for INPUT without internal pull-up resistor

sensor29 3,1,1 - Will enable D3 for INPUT with the internal pull-up resistor ENABLED

sensor29 5,2,1 - Will enable D5 for INPUT and report on change state from LOW to HIGH and HIGH to LOW via MQTT

sensor29 6,3,1 - Will enable D6 for INPUT and report on change state from HIGH to LOW (note pull-up is also enabled)

sensor29 2,4,0 - Will enable D2 for INPUT and report on change state from LOW to HIGH (note pull-up is not enabled)

Pull-up resistor support is valid for all modes from 1 through 4

Default telemetry logging will occur for all pins as per the configured logging interval of the ESP8266 as configured in the Tasmota firmware options. The telemetry logging will push out to log and mqtt a JSON as follows:

tele/sonoff/SENSOR = {"Time":"2018-08-18T16:13:47","MCP230XX": "D0":0,"D1":0,"D2":1,"D3":0,"D4":0,"D5":0,"D6":0,"D7":1}}

Again, this will depend on whether an MCP23008 or MCP23017 is used insofar that the number of pins/bits reported will be 8 (0 to 7) or 16 (0 to 15) respectively.

INTERRUPT MODES AND USAGE

Interrupts will report for individual pins as and when the conditions which were configured are met and will look something like this:

Interrupt message on HIGH for input pin 0

MQT: stat/sonoff/RESULT = {"Time":"2018-08-19T16:04:50","MCP230XX_INT":{"D0":1,"MS":301}}

Interrupt message on LOW for input pin 1

MQT: stat/sonoff/RESULT = {"Time":"2018-08-19T16:04:50","MCP230XX_INT":{"D1":0,"MS":519}}

The state of the pin captured during the interrupt is reported as Dx=y where x is the pin number and y is the state of the pin. In addition the number of milliseconds since the last interrupt occured for the particular pin is also reported as MS=xx where xx is the number of milliseconds recorded.

In addition to the MQTT message the driver will also execute an event command in the following format:

event MCPINT_Dxx=y

Where xx = the pin number from 0 through 7 (MCP23008) or 0 through 15 (MCP23017) and y the state of the pin as it was captured by the interrupt register of the MCP23008/MCP23017 chip.

The complete output for an interrupt enabled pin would look like this:

MQT: stat/sonoff/RESULT = {"Time":"2018-08-19T16:08:28","MCP230XX_INT":{"D0":0,"MS":217353}}
SRC: Rule
RSL: Group 0, Index 1, Command EVENT, Data MCPINT_D0=0
MQT: stat/sonoff/RESULT = {"Event":"Done"}

MQT: stat/sonoff/RESULT = {"Time":"2018-08-19T16:08:46","MCP230XX_INT":{"D0":1,"MS":18101}}
SRC: Rule
RSL: Group 0, Index 1, Command EVENT, Data MCPINT_D0=1
MQT: stat/sonoff/RESULT = {"Event":"Done"}

The latter makes it possible to integrate interrupt responses with rules for example:

rule on event#MCPINT_D0=1 do power on endon on event#MCPINT_D0=0 do power off endon

In the example above the rule would respond to an interrupt of HIGH on pin 0 of the MCP by executing command "power on" and respond to an interrupt of LOW on pin 0 with the command "power off"

See the Wiki on Using Rules for more information on how this can be helpful to your requirements.

If you require only one of the two reporting methods you may use the sensor29 command to configure the interrupt behaviour according to your requirements using command:

sensor29 pin,pinmode,pullup,intmode

The intmode parameter is optional for pin modes 2 through 4 (those that support interrupts) and may be configured according to the table below depending on your requirements:

Keep in mind that the MCP23008/MCP23017 chip will only store the last interrupt registered in the interrupt register and capture register - Because the interrupt register is only checked every 50 milliseconds by the Tasmota firmware you may experience missed interrupts if your incoming signals fluctuate/change faster than 20 times per second.

ADVANCED FUNCTIONS

Several advanced functions have been added to extend the flexibility and interoperability of the MCP23008/MCP23017 with specific focus on adding functionality which is not present on the hardware's built-in GPIO pins and offloading some of the functionality that would normally be performed by rules or counters on the Tasmota device into the driver of the MCP23008/MCP23017.

These include the following

• INTPRI - Interrupt Priority, being able to control the rate at which the MCP23008/MCP23017 is polled to see if any interrupts has occurred since the previous poll.
• INTDEF - Interrupt Deffer, being able to control the number of interrupts that are ignored on a specific pin before reporting would occur via telemetry and/or EVENT.
• INTTIMER - Interrupt Timer which allows for time based counter reporting, specifically reporting the number of times an interrupt has occurred on interrupt enabled pins.
• INTCNT - Works with INTTIMER to enable/disable counting for a specific pin.

The above additions are described in further detail below.

ADVANCED FUNCTION #1 - INTERRUPT PRIORITY (INTPRI)

The maximum interrupt polling rate is once per approximately 50 milliseconds - This is what the Tasmota firmware allows as a maximum and how it is configured in the MCP23008/MCP23017 driver by default.

If you want to reduce the number of interrupt polls per second you may use the INTPRI command parameter as follows:

sensor29 intpri

Will give you the current setting via JSON response as follows:

MQT: stat/sonoff/RESULT = {"MCP230xx_INTPRI":{"D_99":0}}

To change the value you may use command as follows:

sensor29 intpri,x

Where x is the number of 50ms cycles (between 0 and 20) which will be skipped before the MCP23008/MCP23017 chip is polled for interrupt. The last interrupt recorded by the MCP23008/MCP23017 will be reported via the configured method.

For example, lets assume you only want the interrupt polling to occur every 500ms (i.e. twice per second) you could do command:

sensor29 intpri,10 // interrupt polled every 10*50 milliseconds, approximated

ADVANCED FUNCTION #2 - INTERRUPT DEFFER (INTDEF)

Syntax:

sensor29 intdef,pin         // Will provide current setting of pin
sensor29 intdef,pin,x       // Will set new deffer value to x (0-15)

ADVANCED FUNCTION #3 - INTERRUPT TIMER (INTTIMER)

Syntax:

sensor29 inttimer          // Will provide the current amount of seconds for timer
sensor29 inttimer,x        // Allows setting number of seconds (x) for timer interval

ADVANCED FUNCTION #4 - INTERRUPT COUNTER ENABLE (INTCNT)

Syntax:

sensor29 intcnt,pin       // Readback current setting of interrupt counting for pin (0=OFF/1=ON)
sensor29 intcnt,pin,x     // Enable/Disable interrupt counting for pin (x=0=OFF,x=1=ON)

---

OUTPUT FUNCTIONS (PIN MODES 5 AND 6)

Enable OUTPUT support by uncommenting the following compiler directive to your user_config.h

#define USE_MCP230xx_OUTPUT

This will extend the sensor29 command enabling pinmode 5 and 6 (inverted) for output, for example:

sensor29 0,5,0  // Configure pin 0 as OUTPUT and default to OFF on reset/power-up
sensor29 0,5,1  // Configure pin 0 as OUTPUT and default to ON on reset/power-up
sensor29 0,6,0  // Configure pin 0 as INVERTED OUTPUT and default to ON on reset/power-up
sensor29 0,6,1  // Configure pin 0 as INVERTED OUTPUT and default to OFF on reset/power-up

Confirmation will be sent using MQT, for example:

MQT: stat/sonoff/RESULT = {"Sensor29_D2":{"MODE":5,"PULL_UP":"OFF","INT_MODE":"DISABLED","STATE":"OFF"}}

The only difference between pinmode 5 and pinmode 6 is that pinmode 5 will result in normal output state, i.e. pin will be LOW when OFF whereas pinmode 6 will cause the pin to be HIGH when OFF. This is useful when using relays which have inverted inputs.

If SAVE_STATE / setoption0 is enabled in your firmware configuration then the last known state of the pin will be used on power-up/reset thereby ignoring the pull-up parameter in the commands above.

To change the state of an output pin you may use:

sensor29 0,ON   // Turn pin ON (HIGH if pinmode 5 or LOW if pinmode 6(inverted))
sensor29 0,OFF  // Turn pin OFF (LOW if pinmode 5 or HIGH if pinmode 6(inverted))
sensor29 0,T    // Toggle the current state of pin from ON to OFF, or OFF to ON

Telemetry response will be provided accordingly, for example:

MQT: stat/sonoff/RESULT = {"S29cmnd_D0":{"COMMAND":"ON","STATE":"ON"}}
MQT: stat/sonoff/RESULT = {"S29cmnd_D0":{"COMMAND":"OFF","STATE":"OFF"}}
MQT: stat/sonoff/RESULT = {"S29cmnd_D0":{"COMMAND":"TOGGLE","STATE":"ON"}}

COMMAND = Command which was sent

STATE = New state after execution of command

Telemetry data is provided for pins which are enabled for output. For example, if pin 0 was enabled for OUTPUT the following additional telemetry message will be sent by MQTT at the same time as the normal telemetry interval occurs which reports the current states of pins.

MQT: tele/sonoff/SENSOR = {"Time":"2018-08-18T16:41:20","MCP230XX":{"D0":0,"D1":0,"D2":1,"D3":0,"D4":0,"D5":0,"D6":0,"D7":0}}
MQT: tele/sonoff/SENSOR = {"Time":"2018-08-18T16:41:20","MCP230_OUT": {"OUT_D4":"OFF","END":1}}

Note the MCP230XX telemetry which provides the current logic state of all the pins and then the second MQT telemetry as MCP230_OUT which indicates the current state of pins configured for OUTPUT - In this case pin 4 or D4

Remember to adhere to the current limitations of OUTPUT pins when using the device for switching external devices such as LED's - Relay's will need additional circuitry as the MCP23008/MCP23017 cannot drive relays directly - That being said most readily available relay pc boards available from vendors are optically isolated from the input so these will work perfectly.