# CircuitPython Hardware: MPR121 Capacitive Touch Breakout ## Overview Danger: https://www.youtube.com/watch?v=MUQBCyGYky0 ![](https://cdn-learn.adafruit.com/assets/assets/000/040/213/medium800/sensors_IMG_5750.jpg?1489554984) Reach out and touch somebody or some _thing_ with capacitive touch sensing and the [MPR121 capacitive touch breakout board](../../../adafruit-mpr121-12-key-capacitive-touch-sensor-breakout-tutorial/overview).  Capacitive touch sensing means detecting when something conductive is touched by a large object or person.  For example detecting when a person touches a piece of foil, conductive ink, or even a piece of fruit or a vegetable.  It almost seems like magic but capacitive touch sensing is based on a very simple principle--by touching an object your body slightly changes the capacitance of it and that change can be detected with special circuitry. The MPR121 board is a dedicated capacitive touch sensing chip that can check up to 12 inputs independently for touches.  Since the MPR121 uses a simple I2C interface you can use it with almost any development board like an Arduino, MicroPython or CircuitPython board.  This guide shows how to use the MPR121 capacitive touch sensing breakout with a CircuitPython board. Before you follow this guide it will help to familiarize yourself with the following other guides: - [MicroPython Basics: What is MicroPython?](../../../micropython-basics-what-is-micropython) - [MicroPython Basics: How to Load MicroPython on a Board](../../../micropython-basics-how-to-load-micropython-on-a-board) - [MicroPython Basics: Load Files & Run Code](../../../micropython-basics-load-files-and-run-code) - [Adafruit MPR121 Capacitive Touch Sensor Breakout](../../../adafruit-mpr121-12-key-capacitive-touch-sensor-breakout-tutorial/overview) Continue on to learn about the hardware needed to follow this guide. # CircuitPython Hardware: MPR121 Capacitive Touch Breakout ## CircuitPython Wiring Danger: # Parts You'll need the following hardware to follow this guide: - **Board running CircuitPython.**  Currently ESP8266 or SAMD21-based boards are supported by CircuitPython.  The [Feather HUZZAH ESP8266](https://www.adafruit.com/product/2821) or [Feather M0 boards](https://www.adafruit.com/products/2772) are great options that can easily be connected to an accelerometer.  See the [guide on loading MicroPython & CircuitPython firmware](../../../../micropython-basics-how-to-load-micropython-on-a-board/) on a board for details on loading CircuitPython. - **[MPR121 capacitive touch breakout board](https://www.adafruit.com/product/1982) or [MPR121 capacitive touch Arduino shield](https://www.adafruit.com/product/2024).** - **[Breadboard](https://www.adafruit.com/product/64), [hookup wires](https://www.adafruit.com/products/153), and [soldering tools](https://www.adafruit.com/product/136).**  You'll need to solder headers to the accelerometer breakout, be sure to [see the guide to excellent soldering](../../../../adafruit-guide-excellent-soldering/tools) if you're new to it. - **[Alligator clip wires](https://www.adafruit.com/products/1008)** or **[alligator clip to male jumper wires](https://www.adafruit.com/products/3255)**, these are useful for connecting conductive objects to the MPR121 breakout inputs.  For example you can connect the inputs to pieces of fruit to make a funky, fruity musical instrument! Start by [following the MPR121 breakout guide](../../../../adafruit-mpr121-12-key-capacitive-touch-sensor-breakout-tutorial/overview) to assemble and test the board.  Then continue on below to learn how to wire it to a Feather for use with CircuitPython. For the MPR121 Arduino shield just solder headers to the shield (don't forget to solder the 2x3 SPI header in the center of the board too) and connect it to a compatible Arduino (like the Arduino Zero flashed with CircuitPython firmware). # Wiring Connect the MPR121 to your board using its I2C interface as follows: ![](https://cdn-learn.adafruit.com/assets/assets/000/040/209/medium800/sensors_circuitpython-mpr121_bb.png?1489551376) - **MPR121 VIN**  to **board 3V (or 5V) output** - red wire. - **MPR121 GND** to **board GND/ground** - black wire. - **MPR121 SCL** to **board SCL (I2C clock)** - orange wire. - **MPR121 SDA** to **board SDA (I2C data)** - yellow wire. Continue on to learn how to install a CircuitPython module to control the MPR121 board. # CircuitPython Hardware: MPR121 Capacitive Touch Breakout ## CircuitPython Software Danger: # Adafruit CircuitPython Module Install To use the MPR121 with your [Adafruit CircuitPython](https://blog.adafruit.com/2017/01/09/welcome-to-the-adafruit-circuitpython-beta/) board you'll need to install the [Adafruit\_CircuitPython\_MPR121](https://github.com/adafruit/Adafruit_CircuitPython_MPR121) module on your board. First make sure you are running the [latest version of Adafruit CircuitPython](https://github.com/adafruit/circuitpython/releases) for your board. Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).  For example the Circuit Playground Express guide has [a great page on how to install the library bundle](../../../../adafruit-circuit-playground-express/installing-libraries) for both express and non-express boards. Remember for non-express boards like the Trinket M0, Gemma M0, and Feather/Metro M0 basic you'll need to manually install the necessary libraries from the bundle: - **adafruit\_mpr121** - **adafruit\_bus\_device** You can also download the  **adafruit\_mpr121.zip** which contains the **adafruit\_mpr121** folder from [its releases page on Github](https://github.com/adafruit/Adafruit_CircuitPython_MPR121/releases). If your board doesn't support USB mass storage, like the ESP8266, then [use a tool like ampy to copy the file to the board](../../../../micropython-basics-load-files-and-run-code). Before continuing make sure your board's lib folder or root filesystem has the  **adafruit\_mpr121, ** and ** adafruit\_bus\_device****   **folders**  **copied over. ![](https://cdn-learn.adafruit.com/assets/assets/000/040/211/medium800/sensors_Screen_Shot_2017-03-14_at_9.19.39_PM.png?1489551678) # Example To learn how to use the MPR121 module code you can look at the **[simpletest.py example](https://github.com/adafruit/Adafruit_CircuitPython_MPR121/blob/master/examples/mpr121_simpletest.py)** included in the library.  Save this as a **main.py** file on your board: https://github.com/adafruit/Adafruit_CircuitPython_MPR121/blob/main/examples/mpr121_simpletest.py Once the example is running open the serial REPL for your board.  With your finger try pressing any of the 0-11 input pins on the MPR121.  You should see a message printed every time an input is touched: ![](https://cdn-learn.adafruit.com/assets/assets/000/040/212/medium800/sensors_Screen_Shot_2017-03-14_at_9.34.15_PM.png?1489552707) If you don't see any messages when you touch the inputs you might need to ground yourself to the board by touching the GND pin on the board with one finger and then touching the input pads with another finger.   Also make sure nothing is touching the pins when you first run the script or else it might confuse the MPR121's touch detection (unmount the board's file system from your operating system, then press the board's reset button to reset the script and run it again with nothing touching the pins). # Usage Examine the [simpletest.py code](https://github.com/adafruit/Adafruit_CircuitPython_MPR121/blob/master/examples/mpr121_simpletest.py) to see how to use the MPR121 module. https://github.com/adafruit/Adafruit_CircuitPython_MPR121/blob/main/examples/mpr121_simpletest.py  First the module is imported with code like: ``` # Import MPR121 module. import adafruit_mpr121 ``` This code initializes the I2C bus: ``` # Create I2C bus. import board import busio i2c = busio.I2C(board.SCL, board.SDA) ``` Remember for boards without hardware I2C like the ESP8266 you might need to use the **bitbangio** module to create the I2C bus: ``` # Create I2C bus for software I2C boards (ESP8266) import board import bitbangio i2c = bitbangio.I2C(board.SCL, board.SDA) ``` Once the I2C bus is intialized the MPR121 class can be created by passing it an instance of the I2C bus: ``` # Create MPR121 class. mpr121 = adafruit_mpr121.MPR121(i2c) # Note you can optionally change the address of the device: #mpr121 = adafruit_mpr121.MPR121(i2c, address=0x91) ``` Notice the MPR121 class initializer takes an optional **address** parameter if you changed the board's I2C address. Now you're ready to start checking if inputs are touched.  Notice the main loop for the example calls the MPR121 class **is\_touched** function for every input: ``` # Loop forever testing each input and printing when they're touched. while True: # Loop through all 12 inputs (0-11). for i in range(12): # Call is_touched and pass it then number of the input. If it's touched # it will return True, otherwise it will return False. if mpr121.is_touched(i): print('Input {} touched!'.format(i)) time.sleep(0.25) # Small delay to keep from spamming output messages. ``` Just pass a value 0 to 11 to the **is\_touched** function and it will return a boolean **True** or **False** value depending on if the input is currently being touched or not.  In the example it prints a small message when an input is touched. The example doesn't show its usage but if you want to check all of the inputs at once you can call the **touched** function.  This function returns a 12-bit value where each bit represents the touch state of an input.  So bit 0 is input 0 and will be 1 if it's touched and 0 if it's not touched, bit 1 would be input 1, etc.  For example to test if input 0 and 11 are being touched with one call you could run code like: ``` # Call touched to get a 12-bit value with the state of each MPR121 input. touch = mpr121.touched() # Test if exactly bit 0 and 11 are set to 1, i.e. input 0 and 11 are touched. if touch == 0b100000000001: print('Input 0 and 11 touched!') # Or test if either bit 0 or 11 are set to 1, i.e. input 0 or 11 are touched: if touch & 0b100000000000 > 0 or touch & 0b000000000001 > 0: print('Input 0 or 11 touched!') ``` That's all there is to using the MPR121 module with CircuitPython! ## Featured Products ### Adafruit 12-Key Capacitive Touch Sensor Breakout - MPR121 [Adafruit 12-Key Capacitive Touch Sensor Breakout - MPR121](https://www.adafruit.com/product/1982) Add lots of touch sensors to your next microcontroller project with this easy-to-use 12-channel capacitive touch sensor breakout board, starring the MPR121. This chip can handle up to 12 individual touchpads. The MPR121 has support for only I2C, which can be implemented with nearly... In Stock [Buy Now](https://www.adafruit.com/product/1982) [Related Guides to the Product](https://learn.adafruit.com/products/1982/guides) ### Adafruit 12 x Capacitive Touch Shield for Arduino - MPR121 [Adafruit 12 x Capacitive Touch Shield for Arduino - MPR121](https://www.adafruit.com/product/2024) This touch-able add on shield for Arduinos will inspire your next interactive project with 12 capacitive touch sensors. Capacitive touch sensing works by detecting when a person (or animal) has touched one of the sensor electrodes. Capacitive touch sensing used for stuff like touch-reactive... In Stock [Buy Now](https://www.adafruit.com/product/2024) [Related Guides to the Product](https://learn.adafruit.com/products/2024/guides) ### Adafruit Feather M0 Basic Proto - ATSAMD21 Cortex M0 [Adafruit Feather M0 Basic Proto - ATSAMD21 Cortex M0](https://www.adafruit.com/product/2772) Feather is the new development board from Adafruit, and like its namesake it is thin, light, and lets you fly! We designed Feather to be a new standard for portable microcontroller cores. This is the  **Feather M0 Basic Proto** , it has a bunch of prototyping space... In Stock [Buy Now](https://www.adafruit.com/product/2772) [Related Guides to the Product](https://learn.adafruit.com/products/2772/guides) ### Adafruit Feather HUZZAH with ESP8266 - Loose Headers [Adafruit Feather HUZZAH with ESP8266 - Loose Headers](https://www.adafruit.com/product/2821) Feather is the new development board from Adafruit, and like its namesake, it is thin, light, and lets you fly! We designed Feather to be a new standard for portable microcontroller cores. This is the  **Adafruit Feather HUZZAH ESP8266**  - our take on an... Out of Stock [Buy Now](https://www.adafruit.com/product/2821) [Related Guides to the Product](https://learn.adafruit.com/products/2821/guides) ### Adafruit HUZZAH ESP8266 Breakout [Adafruit HUZZAH ESP8266 Breakout](https://www.adafruit.com/product/2471) Add Internet to your next project with an adorable, bite-sized WiFi microcontroller, at a price you like! The ESP8266 processor from Espressif is an 80 MHz microcontroller with a full WiFi front-end (both as client and access point) and TCP/IP stack with DNS support as well. While this chip... In Stock [Buy Now](https://www.adafruit.com/product/2471) [Related Guides to the Product](https://learn.adafruit.com/products/2471/guides) ### Arduino Zero - 32 bit Cortex M0 Arduino with Debug Interface [Arduino Zero - 32 bit Cortex M0 Arduino with Debug Interface](https://www.adafruit.com/product/2843) With the new **Arduino Zero** , the more creative individual will have the potential to create one’s most imaginative and new ideas for IoT devices, wearable technologies, high tech automation, wild robotics and other not yet thinkable adventures in the world of... No Longer Stocked [Buy Now](https://www.adafruit.com/product/2843) [Related Guides to the Product](https://learn.adafruit.com/products/2843/guides) ### Small Alligator Clip Test Lead (set of 12) [Small Alligator Clip Test Lead (set of 12)](https://www.adafruit.com/product/1008) Connect this to that without soldering using these handy mini alligator clip test leads. 15" cables with alligator clip on each end, color coded. You get 12 pieces in 6 colors. Strong and grippy, these always come in handy! We often use these in conjunction with a multimeter so we... Out of Stock [Buy Now](https://www.adafruit.com/product/1008) [Related Guides to the Product](https://learn.adafruit.com/products/1008/guides) ### Small Alligator Clip to Male Jumper Wire Bundle - 12 Pieces [Small Alligator Clip to Male Jumper Wire Bundle - 12 Pieces](https://www.adafruit.com/product/3255) For bread-boarding with unusual non-header-friendly surfaces, these cables will be your best friends! No longer will you have long strands of alligator clips that are grabbing little wires. These compact jumper cables have a premium male header on one end, and a grippy mini alligator clip on... Out of Stock [Buy Now](https://www.adafruit.com/product/3255) [Related Guides to the Product](https://learn.adafruit.com/products/3255/guides) ## Related Guides - [Adafruit Feather HUZZAH ESP8266](https://learn.adafruit.com/adafruit-feather-huzzah-esp8266.md) - [Introducing Adafruit Feather](https://learn.adafruit.com/adafruit-feather.md) - [MicroPython Hardware: I2C Devices](https://learn.adafruit.com/micropython-hardware-i2c-devices.md) - [MicroPython Hardware: Digital I/O](https://learn.adafruit.com/micropython-hardware-digital-i-slash-o.md) - [MicroPython Basics: How to Load MicroPython on a Board](https://learn.adafruit.com/micropython-basics-how-to-load-micropython-on-a-board.md) - [Mini Commodore PET with Charlieplexed LED Matrix](https://learn.adafruit.com/mini-commodore-pet-with-charlieplexed-led-matrix.md) - [Metal Inlay Capacitive Touch Buttons](https://learn.adafruit.com/metal-inlay-capacitive-touch-buttons.md) - [Overwatch Prop Gun: Lucio's Blaster Pt. 3](https://learn.adafruit.com/overwatch-prop-gun-lucios-blaster-pt-3.md) - [Mini Smart Home with Huzzah, HASSio and Crickit](https://learn.adafruit.com/mini-smart-home-with-esp8266-huzzah-feather-raspberry-pi-hassio-crickit.md) - [MicroPython Basics: Loading Modules](https://learn.adafruit.com/micropython-basics-loading-modules.md) - [Installing CircuitPython on SAMD21 Boards](https://learn.adafruit.com/installing-circuitpython-on-samd21-boards.md) - [Level Shifting 3.3V microcontrollers and NeoPixels](https://learn.adafruit.com/neopixel-levelshifter.md) - [Remote Control with the Huzzah + Adafruit.io](https://learn.adafruit.com/remote-control-with-the-huzzah-plus-adafruit-io.md) - [Remote controlled door lock using a fingerprint sensor & Adafruit IO](https://learn.adafruit.com/remote-controlled-door-lock-using-a-fingerprint-sensor-and-adafruit-io.md) - [CircuitPython Hardware: PCA9685 DC Motor & Stepper Driver](https://learn.adafruit.com/micropython-hardware-pca9685-dc-motor-and-stepper-driver.md) - [NAU7802 Pet Food Scale](https://learn.adafruit.com/nau7802-pet-food-scale.md)