Raspberry Pi Virtual Keyboard

The examples in this guide are no longer supported. Check out the MPR121 sensor guide for CircuitPython and Python usage: https://learn.adafruit.com/adafruit-mpr121-12-key-capacitive-touch-sensor-breakout-tutorial/overview

One great use for the MPR121 is as a capacitive touch keyboard, where pressing a touch input causes a key to be pressed on a Raspberry Pi.  This is kind of like a Makey Makey but built right into the Pi using just the MPR121 and some special software.  You could for example configure the MPR121 to act as a giant gamepad that controls games on the Raspberry Pi!


To use the MPR121 as a virtual keyboard you'll first want to make sure you've followed the earlier pages in this guide to connect the MPR121 to the Raspberry Pi and install the software.

Next you'll need to add one additional wire to the MPR121 setup.  This is to connect the MPR121 IRQ line to an input on the Raspberry Pi so the software can quickly detect when an input has been touched without having to continually poll the MPR121 (which takes a lot of CPU!).

By default the virtual keyboard example assumes input #26 (only exposed on the Pi Model A+ or B+!) is connected to the IRQ line.  If you're using an earlier Pi, connect the IRQ line to any free digital input on the Pi, such as input #18.


Now open a terminal on the Raspberry Pi using SSH and execute the following commands to install a few dependencies required by the virtual keyboard script:

Download: file
sudo apt-get update
sudo apt-get install libudev-dev
sudo pip install python-uinput


After the dependencies are installed navigate to the MPR121 library examples folder again.  Open the keyboard.py script in a text editor such as nano by executing:

Download: file
nano keyboard.py

Now scroll down to the key configuration near the top of the file:

Download: file
# Define mapping of capacitive touch pin presses to keyboard button presses.
                0: uinput.KEY_UP,    # Each line here should define a dict entry
                1: uinput.KEY_DOWN,  # that maps the capacitive touch input number
                2: uinput.KEY_LEFT,  # to an appropriate key press.
                3: uinput.KEY_RIGHT, #
                4: uinput.KEY_B,     # For reference the list of possible uinput.KEY_*
                5: uinput.KEY_A,     # values you can specify is defined in linux/input.h:
                6: uinput.KEY_ENTER, # http://www.cs.fsu.edu/~baker/devices/lxr/http/source/linux/include/linux/input.h?v=
                7: uinput.KEY_SPACE, #
              }                      # Make sure a cap touch input is defined only
                                     # once or else the program will fail to run!

# Input pin connected to the capacitive touch sensor's IRQ output.
# For the capacitive touch HAT this should be pin 26!
IRQ_PIN = 26

The KEY_MAPPING variable is a dictionary that maps an input number on the MPR121 to a keyboard button that will be sent when the input is pressed.  

For example the code above configures input 0 to the UP key, input 1 to the DOWN key, input 2 to the LEFT key, etc.

Adjust the inputs and key codes depending on your needs.  Most of the key codes are self explanatory (i.e. the key code for the letter Q is uinput.KEY_Q), but if you are unsure of an input you can find the name of a keycode in the Linux input header here.  Take the key name and add uinput. to the front of it to get the key code that should be in the configuration above.

If you need to add more inputs you can add them as new lines after input 7 above.  Be careful to make sure each new line ends in a comma so the python dictionary is defined correctly.

Also if you had to connect the IRQ line to a different input than #26, be sure to set the IRQ_PIN value to the input number you are using.

After you've configured your key mapping save the file by pressing Ctrl-O and Enter, then quit by pressing Ctrl-X.


Now run the program by executing:

Download: file
sudo python keyboard.py

After a moment you should see a message displayed that tells you to press Ctrl-C to quit the program.  If you press inputs to the MPR121 they should send the keys you've configured to the Raspberry Pi!  

Note that you won't see any output from the program when keys are pressed.  

Quit the program by pressing Ctrl-C.

Launch In Background

Running the program by itself is great, but you probably want to run the program in the background while a game or other application runs and takes input from the MPR121 key presses.  To do this you can launch the program into the background by executing at the terminal:

Download: file
sudo python keyboard.py &

You should see a response such as:

Download: file
[1] 2251

This tells you the program is launched in the background and is currently running under the process ID 2251.  Try to remember the process ID as it will help you shut down the program later (but don't worry, I'll show you how to shut down the program even if you forget the ID).

Now run a game or other program that relies on keyboard input.  Try pressing inputs on the MPR121 and you should see them register as keyboard presses!

Stop Background Process

To stop the background process you'll need to tell Linux to kill the python keyboard.py process that was launched in the background earlier.  If you remember the process ID number you can skip below to the kill command.  However if you forgot the process ID number you can find it by executing a command like this to search all running processes for the keyboard.py script:

Download: file
ps aux | grep keyboard.py

You should see a list of processes such as:

Download: file
root      2251  0.5  0.3   5136  1488 pts/0    S    09:13   0:00 sudo python keyboard.py
root      2252 13.2  1.4  18700  5524 pts/0    Sl   09:13   0:00 python keyboard.py
pi        2294  0.0  0.2   4096   804 pts/0    S+   09:13   0:00 grep --color=auto keyboard.py

The first line with 'sudo python keyboard.py' is the background process that was launched earlier.  You can kill this process by running:

Download: file
sudo kill 2251

If you run the ps command above again you should now see the python keyboard.py processes have terminated.

That's all there is to using the MPR121 virtual keyboard on a Raspberry Pi.  Have fun using the capacitive touch buttons to control your own games and programs!

This guide was first published on Dec 23, 2014. It was last updated on Dec 23, 2014.
This page (Raspberry Pi Virtual Keyboard) was last updated on Aug 06, 2020.