Skip to content

MPR121

Works with

Any CircuitPython board with I2C

What it does

The MPR121 detects capacitive touch on up to 12 pads simultaneously. Any conductive material works as a touch pad — wire, copper tape, aluminum foil, fruit, plants, water in a container, or a bare PCB trace. Up to four MPR121 chips can share one I2C bus by setting address pins, giving up to 48 touch inputs. Common uses include musical instruments, custom keyboards, interactive installations, and any project that needs physical input without mechanical switches.

Installing the library

Download adafruit_mpr121.mpy and the adafruit_bus_device/ folder from the Adafruit CircuitPython Bundle and copy both to the lib/ folder on your board.

Quick start

import board
import busio
import adafruit_mpr121

i2c = busio.I2C(board.SCL, board.SDA)
mpr121 = adafruit_mpr121.MPR121(i2c)

while True:
    for i in range(12):
        if mpr121[i].value:
            print(f"Pad {i} touched")

Key things you can do

What you want How to do it
Check if a pad is currently touched mpr121[i].value — True if touched
Read all pads as a bitmask mpr121.touched() — bit 0 = pad 0, bit 11 = pad 11
Detect touch events (not held state) Track previous state: if mpr121[i].value and not last[i]
Use multiple chips on one bus Add address pins: second chip at 0x5B, third at 0x5C, fourth at 0x5D
Initialize a second chip mpr121b = adafruit_mpr121.MPR121(i2c, address=0x5B)
Adjust touch/release thresholds mpr121.set_thresholds(touch, release) — lower values = more sensitive

Reading the official docs

Full API reference: https://docs.circuitpython.org/projects/mpr121/en/latest/

Key things to look up:

  • For musical instruments, check mpr121[i].value each loop iteration — this gives the held state, which is what you want for sustained notes
  • For keyboards or button-style inputs, track transitions using a last_touched variable so an action fires once per press rather than every loop iteration
  • touched() returns a 12-bit integer; use bitwise AND to check individual pads: if mpr121.touched() & (1 << i)
  • Autoconfig recalibrates the baseline automatically — if your pads are picking up noise, check wiring length and whether pads are too close together

Projects using this library

  • Adafruit MPR121 guide — wiring, sensitivity tuning, and multi-chip setup
  • This wiki's Touch Keyboard project — uses MPR121 pads mapped to notes with audio output