Skip to content

Latest commit

 

History

History
330 lines (232 loc) · 9.24 KB

README.md

File metadata and controls

330 lines (232 loc) · 9.24 KB
Raw

MicroPython MCP23017 16-bit I/O Expander

A MicroPython library for the MCP23017 16-bit I/O Expander with I2C Interface.

demo

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

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