Awesome
MicroPython MCP23017 16-bit I/O Expander
A MicroPython library for the MCP23017 16-bit I/O Expander with I2C Interface.
Examples
from machine import Pin, I2C
import mcp23017
i2c = I2C(scl=Pin(22), sda=Pin(21))
mcp = mcp23017.MCP23017(i2c, 0x20)
# list interface
mcp[0].input()
mcp[1].input(pull=1)
mcp[1].value()
mcp[2].output(1)
mcp[3].output(0)
# method interface
mcp.pin(0, mode=1)
mcp.pin(1, mode=1, pullup=True)
mcp.pin(1)
mcp.pin(2, mode=0, value=1)
mcp.pin(3, mode=0, value=0)
mcp.config(interrupt_polarity=0, interrupt_mirror=1)
# property interface 16-bit
mcp.mode = 0xfffe
mcp.gpio = 0x0001
# property interface 8-bit
mcp.porta.mode = 0xfe
mcp.portb.mode = 0xff
mcp.porta.gpio = 0x01
mcp.portb.gpio = 0x02
For more detailed examples, see examples.
Pins
| Pin | Type | Description |
|---|---|---|
| A0 | I | Address select 1, connect to VCC or GND |
| A1 | I | Address select 2, connect to VCC or GND |
| A2 | I | Address select 3, connect to VCC or GND |
| INTA | O | Interrupt output for port A |
| INTB | O | Interrupt output for port B |
| RESET | I | Reset, active LOW |
| GPA0 | IO | Port A, Pin 0 |
| GPA1 | IO | Port A, Pin 1 |
| GPA2 | IO | Port A, Pin 2 |
| GPA3 | IO | Port A, Pin 3 |
| GPA4 | IO | Port A, Pin 4 |
| GPA5 | IO | Port A, Pin 5 |
| GPA6 | IO | Port A, Pin 6 |
| GPA7 | IO | Port A, Pin 7 |
| GPB0 | IO | Port B, Pin 0 |
| GPB1 | IO | Port B, Pin 1 |
| GPB2 | IO | Port B, Pin 2 |
| GPB3 | IO | Port B, Pin 3 |
| GPB4 | IO | Port B, Pin 4 |
| GPB5 | IO | Port B, Pin 5 |
| GPB6 | IO | Port B, Pin 6 |
| GPB7 | IO | Port B, Pin 7 |
| VDD | P | Power (3V3 or 5V) |
| VSS | P | Ground |
| CS | I | Not used - SPI Chip Select (CS) on the SPI version (MCP23S17) |
| SCK | I | I2C Serial Clock - SPI Serial Clock (SCK) on the SPI version |
| SI | I | I2C Serial Data - SPI Serial Data In (MOSI) on the SPI version |
| SO | O | Not used - SPI Serial Data Out (MISO) on the SPI version |
Methods
init(i2c, address=0x20)
Construct with a reference to I2C and set the device address (0x20-0x27).
If are you not sure what it is, run an i2c.scan().
init()
Initialises the device.
config(interrupt_polarity=None, interrupt_open_drain=None, sda_slew=None, sequential_operation=None, interrupt_mirror=None, bank=None)
Configures the device by writing to the iocon register.
pin(pin, mode=None, value=None, pullup=None, polarity=None, interrupt_enable=None, interrupt_compare_default=None, default_value=None)
Method for getting, setting or configuring a single pin. If no value is provided, the port will read the value from the GPIO register and return for the current pin. If a value is provided, the port will write the value to the GPIO register. Valid pin range 0-15. All of the other optional arguments are booleans.
interrupt_triggered_gpio(port)
After an interrupt fires, this method tells you which pin triggered it and clears the interrupt so it can fire again. It's port specific as there are port specific interrupts.
interrupt_captured_gpio(port)
This method tells you the state of the GPIO register at the time the interrupt fired.
_flip_bit(value, condition, bit)
Private method for toggling a bit in a value based on a condition.
getitem(pin)
Provides the list interface for interacting with "virtual pins".
Virtual pin methods
init(pin, port)
Constructed with a specific pin (0-7) and the port it belongs to.
_flip_bit(value, condition)
Private method for toggling a bit in a value based on a condition.
_get_bit(value)
Private method for getting a single bit from the given value based on the current pin
value(val=None)
Reads or writes the current pins value (0-1).
input(pull=None)
Configures the pin as input and optionally configures it to be pulled up.
output(val=None)
Configures the pin to be output and optionally sets it's value (0-1).
Port methods
init(port, mcp)
Constructed with the port number (0-1) and a reference to the main class.
_which_reg(reg)
Private method for calculating which register to write to as their address can change when configured to use different addressing scheme (iocon.bank).
_flip_property_bit(reg, condition, bit)
Private method for toggling a bit in a register based on a condition.
_read(reg)
Private method for reading the register over I2C.
_write(reg, val)
Private method for writing to the register over I2C.
Properties
There are two sets of properties, one on the main class and one on each port class.
Properties on the main class wrap the properties in each port.
You can get and set on the main class properties with a 16-bit integer and it splits it into two 8-bit integers and forwards to each port.
You can also get and set on the ports a and b directly with 8-bit integers.
The registers accessible using the property interface are:
| Property | Register | Type | Description |
|---|---|---|---|
| mode | iodir | R/W | Direction 0=output, 1=input |
| input_polarity | ipol | R/W | Input polarity 0=normal, 1=invert |
| interrupt_enable | gpinten | R/W | Interrupt enable 0=disabled, 1=enabled |
| default_value | defval | R/W | Interrupt default value |
| interrupt_compare_default | intcon | R/W | Interrupt config |
| io_config | iocon | R/W | IO config |
| pullup | gppu | R/W | Pull-up |
| interrupt_flag | intf | R | Interrupt flag 1=this pin triggered interrupt |
| interrupt_captured | intcap | R | Interrupt captured - state of pins at interrupt |
| gpio | gpio | R/W | General purpose IO |
| output_latch | olat | R/W | Output latch - which output pins are high |
Getter on the main class reads the GPIO register and returns a 16-bit integer. The lower 8 bits represent port a.
gpio
Getter on the nested port classes reads their GPIO registers and returns 8-bit integers.
porta.gpio
portb.gpio
Setter on the main class writes to the both of the GPIO registers in port a and b. The lower 8 bits represent port a.
gpio = 0xffee
Setter on the nested port classes writes to their GPIO registers.
porta.gpio = 0xee
portb.gpio = 0xff
You can use bitwise assignment operators to toggle specific pins, which performs a read, modify, write.
# set all pins low
porta.gpio = 0
# set the first 4 pins high
porta.gpio |= 0x0f
# set the first 2 pins low
porta.gpio &= ~0x03
# invert the first 4 pins
porta.gpio ^= 0x0f
Ports
Featuring a 16-bit bidirectional I/O port where each pin can be configured as active-high, active-low or open-drain. Polarity can be inverted on any of the pins. Work on both 3V3 or 5V logic.
- A0-A7
- B0-B7
Interrupts
Two independent interrupts, one for each 8-bit port, which can be linked/mirrored using interrupt_mirror config, so that any pin change triggers both.
Interrupt can be configured to watch any specific pins and fire on pin change or when the pin differs from the defaults you set.
- INTA - for pins A0-A7
- INTB - for pins B0-B7
Once an interrupt fires, you need to read either the interrupt_flag (INTCAP) or gpio (GPIO) registers to clear it.
I2C Interface
There are three address select pins (A0,A1,A2) providing addresses 0x20-0x27 for up to 8 of these devices on the I2C bus.
Requires 10k pull-up resistors on the SCL + SDA lines.
| A0 | A1 | A2 | I2C Address |
|---|---|---|---|
| GND | GND | GND | 0x20 |
| 3V3 | GND | GND | 0x21 |
| GND | 3V3 | GND | 0x22 |
| 3V3 | 3V3 | GND | 0x23 |
| GND | GND | 3V3 | 0x24 |
| 3V3 | GND | 3V3 | 0x25 |
| GND | 3V3 | 3V3 | 0x26 |
| 3V3 | 3V3 | 3V3 | 0x27 |
Parts
- MCP23017 black board $1.40 AUD
- MCP23017 green board $1.99 AUD
- MCP23017 char lcd board $2.16 AUD
- MCP23017 DIP-28 $1.58 AUD
- TinyPICO $20.00 USD
- Wemos D1 Mini $5.20 AUD
Connections
TinyPICO ESP32
from machine import Pin, I2C
import mcp23017
i2c = I2C(scl=Pin(22), sda=Pin(21))
mcp = mcp23017.MCP23017(i2c, 0x20)
| MCP23017 | TinyPICO (ESP32) |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SCL | 22 (SCL) |
| SDA | 21 (SDA) |
| INTA | 4 (Optional) |
Wemos D1 Mini (ESP8266)
from machine import Pin, I2C
import mcp23017
i2c = I2C(scl=Pin(5), sda=Pin(4))
mcp = mcp23017.MCP23017(i2c, 0x20)
| MCP23017 | Wemos D1 Mini (ESP8266) |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SCL | D1 (GPIO5) |
| SDA | D2 (GPIO4) |
| INTA | D5 (GPIO14 Optional) |
Links
License
Licensed under the MIT License.
Copyright (c) 2019 Mike Causer