Raspberry Pi Virtual Keyboard

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!

Wiring

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.

Dependencies

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 pip3 install python-uinput
sudo pip3 install adafruit-circuitpython-mpr121

Configuration

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

Download: file
nano pi_keyboard.py

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

Download: file
KEY_MAPPING = {                                                                                                                                                                                                                                                                
    0: uinput.KEY_UP,                                                                                                                                                                                                                                                          
    1: uinput.KEY_DOWN,                                                                                                                                                                                                                                                        
    2: uinput.KEY_LEFT,                                                                                                                                                                                                                                                        
    3: uinput.KEY_RIGHT,                                                                                                                                                                                                                                                       
    4: uinput.KEY_B,                                                                                                                                                                                                                                                           
    5: uinput.KEY_A,                                                                                                                                                                                                                                                           
    6: uinput.KEY_ENTER,                                                                                                                                                                                                                                                       
    7: uinput.KEY_SPACE,                                                                                                                                                                                                                                                       
}

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.

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

Usage

Now run the program by executing:

Download: file
sudo python3 pi_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, unless you first enable logging by un-commenting the following line:

Download: file
# Uncomment to enable debug message logging (might slow down key detection).                                                                                                                                                                                                   
logging.basicConfig(level=logging.DEBUG)

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 Jul 25, 2014. It was last updated on Jul 25, 2014. This page (Raspberry Pi Virtual Keyboard) was last updated on Jul 17, 2019.