Introduction

Documentation Status Discord Build Status

Adafruit CircuitPython module for the MPR121 capacitive touch breakout board.

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Usage Example

See usage in the examples/mpr121_simpletest.py file.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Building locally

To build this library locally you’ll need to install the circuitpython-build-tools package.

python3 -m venv .env
source .env/bin/activate
pip install circuitpython-build-tools

Once installed, make sure you are in the virtual environment:

source .env/bin/activate

Then run the build:

circuitpython-build-bundles --filename_prefix adafruit-circuitpython-mpr121 --library_location .

Sphinx documentation

Sphinx is used to build the documentation based on rST files and comments in the code. First, install dependencies (feel free to reuse the virtual environment from above):

python3 -m venv .env
source .env/bin/activate
pip install Sphinx sphinx-rtd-theme

Now, once you have the virtual environment activated:

cd docs
sphinx-build -E -W -b html . _build/html

This will output the documentation to docs/_build/html. Open the index.html in your browser to view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to locally verify it will pass.

Table of Contents

Simple test

Ensure your device works with this simple test.

examples/mpr121_simpletest.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Simple test of the MPR121 capacitive touch sensor library.
# Will print out a message when any of the 12 capacitive touch inputs of the
# board are touched.  Open the serial REPL after running to see the output.
# Author: Tony DiCola
import time
import board
import busio
# Import MPR121 module.
import adafruit_mpr121

# Create I2C bus.
i2c = busio.I2C(board.SCL, board.SDA)

# 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)

# 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[i].value:
            print('Input {} touched!'.format(i))
    time.sleep(0.25)  # Small delay to keep from spamming output messages.
examples/piano.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# MPR121 piano demo.
# Listens to the first 7 inputs of the MPR121 and plays a middle scale note
# when an input is touched.  Note only one note is played at a time!
# For use with microcontrollers or computers with PWM support only!
# Author: Tony DiCola
import time

import board
import busio
import pulseio

# Import MPR121 module.
import adafruit_mpr121


# Configure PWM buzzer and other state:
BUZZER_PIN = board.D9
TONE_ON_DUTY = 2**15   # Duty cycle of tone when turned on, a square wave.
TONE_OFF_DUTY = 0      # Duty cycle of tone when turned off, 0 or no signal.
NOTE_FREQS = [261,  # Input 0 = 261 hz = middle C
              294,  # Input 1 = middle D
              329,  # Input 2 = middle E
              349,  # Input 3 = middle F
              392,  # Input 4 = middle G
              440,  # Input 5 = middle A
              493,  # Input 6 = middle B
              0,    # Input 7 = nothing (set to a frequency in hertz!)
              0,    # Input 8
              0,    # Input 9
              0,    # Input 10
              0]    # Input 11


# Create I2C bus.
i2c = busio.I2C(board.SCL, board.SDA)

# 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)

# Setup buzzer PWM output.
buzzer = pulseio.PWMOut(BUZZER_PIN, duty_cycle=TONE_OFF_DUTY, frequency=440,
                        variable_frequency=True)

# Main loop.
# First grab an initial touch state for all of the inputs.  The touched()
# function can quickly get the state of all input pins and returns them as a
# 12-bit value with a bit set to 1 for each appropriate input (i.e. bit 0 is
# input 0, bit 1 is input 1, etc.)
last = mpr121.touched()
while True:
    # Every loop iteration get an updated touch state and look to see if it
    # changed since the last iteration.
    current = mpr121.touched()
    if last != current:
        # Some pin changed, turn off playback and look for any touched pins.
        buzzer.duty_cycle = TONE_OFF_DUTY
        # Loop through all 12 inputs (0-11) and look at their bits in the
        # current touch state.  A bit that's set is touched!
        for i in range(12):
            if (1 << i) & current > 0:
                print('Input {} touched!'.format(i))
                # Grab the frequency for the associated pin and check that it's
                # not zero (unused).
                freq = NOTE_FREQS[i]
                if freq != 0:
                    # Pin with a specified frequency was touched, play the tone!
                    buzzer.frequency = NOTE_FREQS[i]
                    buzzer.duty_cycle = TONE_ON_DUTY
    # Update touch state and delay a bit before next loop iteration.
    last = current
    time.sleep(0.01)

adafruit_mpr121

CircuitPython driver for the MPR121 capacitive touch breakout board.

See usage in the examples/simpletest.py file.

  • Author(s): Tony DiCola

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_mpr121.MPR121(i2c, address=90)[source]

Driver for the MPR121 capacitive touch breakout board.

baseline_data(pin)[source]

Return baseline data register value for the provided pin (0-11). Useful for debugging.

filtered_data(pin)[source]

Return filtered data register value for the provided pin (0-11). Useful for debugging.

is_touched(pin)[source]

Return True if the specified pin is being touched, otherwise returns False.

reset()[source]

Reset the MPR121 into a default state ready to detect touch inputs.

set_thresholds(touch, release)[source]

Set the touch and release threshold for all inputs to the provided values. Both touch and release should be a value between 0 to 255 (inclusive).

touched()[source]

Return touch state of all pins as a 12-bit value where each bit represents a pin, with a value of 1 being touched and 0 not being touched.

touched_pins

A tuple of touched state for all pins.

class adafruit_mpr121.MPR121_Channel(mpr121, channel)[source]

Helper class to represent a touch channel on the MPR121. Not meant to be used directly.

raw_value

The raw touch measurement.

value

Whether the touch pad is being touched or not.

Indices and tables