# Adafruit GPIO Expander Bonnet for Raspberry Pi
## Overview
The Raspberry Pi is an amazing single board computer - and one of the best parts is that GPIO connector! 40 pins of digital goodness you can twiddle to control LEDs, sensors, buttons, radios, displays - just about any device you can imagine. This Adafruit GPIO Expander Bonnet will give you _even more_ digital deliciousness - 16 more digital input/output pins are yours for any desire you have. The outputs are grouped into two 16-pin connectors that have a matching ground pin. You can set each pin to be a digital output (high or low) or as an input, with an internal pull-up if you like!
Simply pop the Bonnet on top of your Pi, the circuitry connects to the SDA/SCL I2C pins for control. The MCP23017 chip converts our Python commands to pin instructions.
When used as an output, each pin can supply up to 20mA (current clamped) - so you can drive LEDs directly. The datasheet recommends you keep the total current draw to under 125mA for the whole chip. We set up the expander chip for 5V logic by default (the I2C is level shifted so that's 3V logic). We did that so you can drive white, blue or green LEDs that sometimes aren't too happy with 3.3V logic. Or, you can cut/solder a jumper to change it to 3.3V logic.
When used as an input, you can set up a pull-up resistor so buttons and switches don't need extra resistors - just wire the pin to one side and ground to the other! There's interrupt capabilities on the chip, and two IRQ pins (INTA and INTB) you can solder a wire to, if you want to have a quick way of telling if any of the GPIOs changed.
By soldering closed the address select jumpers, you can change the address from 0x20 up to 0x27. So, if you wanted to, you could have up to 8 bonnets for 128 total GPIO.
**As of October 31, 2023** - We've added an on-board Stemma QT port for easy plug-n-play of I2C sensors and devices. The board also now comes with the two IDC socket headers pre-soldered. Lastly, we've also updated it with [Adafruit Pinguin](https://github.com/adafruit/Adafruit_Pinguin) to make a lovely and legible silkscreen
# Adafruit GPIO Expander Bonnet for Raspberry Pi
## Pinouts
This Bonnet provides you with a number of options. Let's take a look!
## MCP23017 GPIO Expander Chip
The **MCP23017 GPIO expander chip** converts Python code into pin instructions.
## GPIO Expansion Headers
You can solder the included headers onto the Bonnet, or leave them off for a slimmer setup.
- The top section is **GPB0** - header B.
- The bottom set is **GPA0** - header A.
- The top row of each set of headers is **ground**.
- The bottom row, numbered 0-7, is the **8 IO pins**.
## STEMMA QT Connector
**As of October 31, 2023** - We've added an on-board Stemma QT port for easy plug-n-play of I2C sensors and devices. Use this port for connecting your I2C breakouts to the your Raspberry Pi.
## Address Select Jumpers
By soldering closed the **address select jumpers** , you can change the address from **0x20 to 0x27**. This allows up to 8 bonnets for 128 total GPIO.
Use the table below to help determine what address results from soldering various pads.
- Blank= unsoldered (default)
- **X** = soldered
## Interrupt Pins
The MCP23017 has interrupt capabilities. There are two **IRQ pins** ( **INTA** and **INTB** ) you can solder a wire to, if you want to have a quick way of telling if any of the GPIO's changed.
## 3V/5V Jumper
This Bonnet defaults to using 5V. There is a jumper to swap between 3V and 5V. If you want to change it to 3V, you can cut the trace between the top two pads, and solder the bottom two pads.
# Adafruit GPIO Expander Bonnet for Raspberry Pi
## Python Usage
Make sure you've installed the bonnet onto your single board Linux computer by plugging it in and then restarting.
[You will need to have I2C set up and activated - here's how to do it for Raspberry Pi.](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c)
Once that's done and the bonnet installed, board rebooted, you should be able to I2C scan to find the device with something like `sudo i2cdetect -y 1` (the number may be different on non-Raspi computers)
The default address for the bonnet is **0x20**
## Python Installation of MCP23017 Library
You can use this Bonnet with Python and Raspberry Pi [thanks to Adafruit\_Blinka, our CircuitPython-for-Python compatibility library](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux).
You'll need to install the Adafruit\_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. [Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux)!
Once that's done, from your command line run the following command:
- `sudo pip3 install adafruit-circuitpython-mcp230xx`
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
## Python Usage
To demonstrate the usage, we'll use Python code to read a button and light up an LED from the Python REPL.
Wire up the bonnet as follows:
- LED anode through a resistor (220 to 4.7Kohm) to **GPA0**
- LED cathode (short leg) to one of the **GND** pads (any)
- One side of switch to **GPA1**
- Other side of switch to one of the **GND** pads (any)
And start up Python3
First you'll need to import the necessary modules, initialize the I2C bus for your board, and create an instance of the class.
```
import time
import board
import busio
import digitalio
from adafruit_mcp230xx.mcp23017 import MCP23017
# Initialize the I2C bus:
i2c = busio.I2C(board.SCL, board.SDA)
mcp = MCP23017(i2c) # MCP23017
```
Now you have the device called `mcp`, you can use that to 'create' `DigitalInOut` pins, by calling `get_pin`. The pins are ordered 0-15. Pin #0 is **GPA0** , #1 is **GPA1** , #8 is **GPB0** , #15 is **GPB7**
```
pin0 = mcp.get_pin(0) # GPA0
pin1 = mcp.get_pin(1) # GPA1
```
Now you can treat these like regular digital inputs and outputs. Set GPA0 to be an output and level high voltage.
The LED should turn on!
```
# Setup pin0 as an output that's at a high logic level.
pin0.switch_to_output(value=True)
```
And set GPA1 to be an input with a pullup
```
# Setup pin1 as an input with a pull-up resistor enabled. Notice you can also
# use properties to change this state.
pin1.direction = digitalio.Direction.INPUT
pin1.pull = digitalio.Pull.UP
```
Finally we can have a loop where we read and write data to the pins
```
# Now loop blinking the pin 0 output and reading the state of pin 1 input.
while True:
# Blink pin 0 on and then off.
pin0.value = True
time.sleep(0.5)
pin0.value = False
time.sleep(0.5)
# Read pin 1 and print its state.
print('Pin 1 is at a high level: {0}'.format(pin1.value))
```
The LED should start blinking. You can also press the button to see the output change for the pin 1 value:
Type Control-C to quit. Then try this code that will light up the LED when the button is pressed:
```
# Now loop setting the LED when the button is pressed
while True:
pin0.value = not pin1.value
```
That's pretty much all you need to get started with the bonnet!
The fully commented example is here:
Warning:
https://github.com/adafruit/Adafruit_CircuitPython_MCP230xx/blob/main/examples/mcp230xx_simpletest.py
We have more examples, including interrupt detection so you don't have to constantly query the pin values for buttons. Visit [https://github.com/adafruit/Adafruit\_CircuitPython\_MCP230xx/tree/master/examples](https://github.com/adafruit/Adafruit_CircuitPython_MCP230xx/tree/master/examples) to see all the examples
**Some of the examples may be set up for an MCP23008 instead of MCP23017 so be sure to update the objection creation at the top!**
# Adafruit GPIO Expander Bonnet for Raspberry Pi
## Python Docs
# Adafruit GPIO Expander Bonnet for Raspberry Pi
## Downloads
## Files
- [MCP23017 GPIO Expander Datasheet](http://ww1.microchip.com/downloads/en/devicedoc/20001952c.pdf)
- [Adafruit GPIO Expander Bonnet EagleCAD files on GitHub](https://github.com/adafruit/Adafruit-GPIO-Expander-Bonnet-PCBs)
- [Rev B Fritzing object in our Fritzing repo](https://github.com/adafruit/Fritzing-Library/blob/master/parts/Adafruit%20GPIO%20Expander%20Bonnet.fzpz)
- [Rev C Fritzing object in our Fritzing repo](https://github.com/adafruit/Fritzing-Library/blob/master/parts/Adafruit%20GPIO%20Expander%20Bonnet%20with%20STEMMA%20QT.fzpz)
- [Rev C 3D model on GitHub](https://github.com/adafruit/Adafruit_CAD_Parts/tree/main/4132%20GPIO%20Expander%20Bonnet)
## Schematics and Fab Print
### Rev C
### Rev B
## Primary Products
### Adafruit GPIO Expander Bonnet - 16 Additional I/O over I2C
[Adafruit GPIO Expander Bonnet - 16 Additional I/O over I2C](https://www.adafruit.com/product/4132)
The Raspberry Pi is an amazing single board computer - and one of the best parts is that GPIO connector! 40 pins of digital goodness you can twiddle to control LEDs, sensors, buttons, radios, displays - just about any device you can imagine. This Adafruit GPIO Expander Bonnet will give you...
In Stock
[Buy Now](https://www.adafruit.com/product/4132)
[Related Guides to the Product](https://learn.adafruit.com/products/4132/guides)
## Featured Products
### GPIO Ribbon Cable 2x8 IDC Cable - 16 pins 12" long
[GPIO Ribbon Cable 2x8 IDC Cable - 16 pins 12" long](https://www.adafruit.com/product/4170)
Connect this to that! If you want to bridge those contacts out onto another PCB, you'll want this **GPIO Ribbon Cable**! Comes in a classic Adafruit Black, has a nice soft flexible 16-line 0.05" ribbon cable and keyed IDC connectors on both ends.
In Stock
[Buy Now](https://www.adafruit.com/product/4170)
[Related Guides to the Product](https://learn.adafruit.com/products/4170/guides)
### STEMMA QT / Qwiic JST SH 4-Pin Cable - 50mm Long
[STEMMA QT / Qwiic JST SH 4-Pin Cable - 50mm Long](https://www.adafruit.com/product/4399)
This 4-wire cable is 50mm / 1.9" long and fitted with JST SH female 4-pin connectors on both ends. Compared with the chunkier JST PH these are 1mm pitch instead of 2mm, but still have a nice latching feel, while being easy to insert and remove.
Out of Stock
[Buy Now](https://www.adafruit.com/product/4399)
[Related Guides to the Product](https://learn.adafruit.com/products/4399/guides)
### STEMMA QT / Qwiic JST SH 4-pin to Premium Male Headers Cable
[STEMMA QT / Qwiic JST SH 4-pin to Premium Male Headers Cable](https://www.adafruit.com/product/4209)
This 4-wire cable is a little over 150mm / 6" long and fitted with JST-SH female 4-pin connectors on one end and premium Dupont male headers on the other. Compared with the chunkier JST-PH these are 1mm pitch instead of 2mm, but still have a nice latching feel, while being easy to insert...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4209)
[Related Guides to the Product](https://learn.adafruit.com/products/4209/guides)
### STEMMA QT / Qwiic JST SH 4-pin Cable - 100mm Long
[STEMMA QT / Qwiic JST SH 4-pin Cable - 100mm Long](https://www.adafruit.com/product/4210)
This 4-wire cable is a little over 100mm / 4" long and fitted with JST-SH female 4-pin connectors on both ends. Compared with the chunkier JST-PH these are 1mm pitch instead of 2mm, but still have a nice latching feel, while being easy to insert and remove.
Out of Stock
[Buy Now](https://www.adafruit.com/product/4210)
[Related Guides to the Product](https://learn.adafruit.com/products/4210/guides)
### STEMMA QT / Qwiic JST SH 4-Pin Cable - 200mm Long
[STEMMA QT / Qwiic JST SH 4-Pin Cable - 200mm Long](https://www.adafruit.com/product/4401)
This 4-wire cable is a little over 200mm / 7.8" long and fitted with JST-SH female 4-pin connectors on both ends. Compared with the chunkier JST-PH these are 1mm pitch instead of 2mm, but still have a nice latching feel, while being easy to insert and remove.
In Stock
[Buy Now](https://www.adafruit.com/product/4401)
[Related Guides to the Product](https://learn.adafruit.com/products/4401/guides)
## Related Guides
- [Adafruit INA3221 Breakout](https://learn.adafruit.com/adafruit-ina3221-breakout.md)
- [World Clock](https://learn.adafruit.com/world-clock.md)
- [MCP4725 12-Bit DAC Tutorial](https://learn.adafruit.com/mcp4725-12-bit-dac-tutorial.md)
- [Adafruit ESP32-S3 Reverse TFT Feather](https://learn.adafruit.com/esp32-s3-reverse-tft-feather.md)
- [CLUE BLE MIDI Glove](https://learn.adafruit.com/clue-midi-glove.md)
- [Adafruit OPT4048 XYZ Color Sensor](https://learn.adafruit.com/adafruit-opt4048-xyz-color-sensor.md)
- [Adafruit MCP9601 I2C Thermocouple Amplifier](https://learn.adafruit.com/adafruit-mcp9601.md)
- [Adafruit DACx578 - 8 x Channel I2C DAC](https://learn.adafruit.com/adafruit-dac7578-8-x-channel-12-bit-i2c-dac.md)
- [Raspberry Pi Thermal Camera](https://learn.adafruit.com/raspberry-pi-thermal-camera.md)
- [Adafruit TMP117 High Accuracy I2C Temperature Monitor](https://learn.adafruit.com/adafruit-tmp117-high-accuracy-i2c-temperature-monitor.md)
- [Adafruit ADS7830 8-Channel 8-Bit ADC](https://learn.adafruit.com/adafruit-ads7830-8-channel-8-bit-adc.md)
- [CircuitPython Elgato WiFi Light Controller](https://learn.adafruit.com/circuitpython-elgato-wifi-light-controller.md)
- [Infinite Text Adventure](https://learn.adafruit.com/infinite-text-adventure.md)
- [ Faz-Wrench - Five Nights at Freddy's](https://learn.adafruit.com/faz-wrench.md)
- [Haiku Viewer for MagTag](https://learn.adafruit.com/haiku-viewer-for-magtag.md)