Raspberry Pi Zero GPIO Control Buttons

*I’m making a few changes to this guide to simplify the software installation.*

The Raspberry Pi Zero at $5 is a perfect starting point for many projects. We need a way to interface with it though, and it doesn’t make much sense to double or triple that cost with a USB controller. There is a better way using GPIO controls and Adafruit’s Retrogame.

A complete guide was posted on Adafruit.com and shows the basic installation process. Adafruit made this program and they get 100% of the credit for their hard work. This guide was created to simplify the installation and configuration process and help others avoid some of the difficulties I experienced when setting this up.

Part 1 of 2: Hardware

The Pi GPIO pins have the ability to enable built-in resistors to set the GPIO to one of two states, pulling the voltage up to 3.3 volts or pulling the voltage down to ground. Retrogame enables the pullup resistors of the specified pins, and brings the pins to 3.3v. One side of a switch or button is connected to the GPIO pin and the other side is connected to a ground pin (or a ground pad or the ground from the power input since they are all interconnected). Pushing the button causes a sudden drop in the GPIO pin voltage that is detected by Retrogame. This signals the program to issue a keypress to the operating system, which is seen by programs like RetroPie just like a normal keyboard keypress.

Part 2 of 2: Software

Before you do anything else, start by downloading and installing Notepad++. You will need it to edit the config files.
Download the Retrogame zip file here. Download the 10-retrogame.rules input rule file here (right-click and save). Again, most of this is on Adafruit’s Retrogame tutorial. They deserve all the recognition for their hard work.
Extract the Retrogame file using your favorite zip file extractor and then copy the entire Adafruit-Retrogame-master folder to the your MicroSD Card. Copy the 10-retrogame.rules file into the same Adafruit-Retrogame-master folder.
Next you want to customize Retrogame. There are now 6 files in the folder you copied to your MicroSD card. We need to open the one called retrogame.c using Notepad++. Right-clicking the file in Windows will give the option “Edit with Notepad++”. Once opened, scroll to line 111, and you will see the same code that is posted below.


Lines 116 to 121 above show the GPIO pins that are being used for buttons, and it shows what keypress is outputted. For example, line 116 has 25 as the input and KEY_LEFT is set as output, which means that when GPIO pin 25 is connected to ground the software will output a KEY_LEFT output (and make your character move left in a game). One important note is that the GPIO pin number used for input is from the GPIO numbering map and pin numbers are all over the place. The image posted at the top of the page shows the correct GPIO numbering. Pins that are good for button mapping are the ones shown in the image with GPIO numbers next to them and no color shading around the pin. The keypress name comes from a file called input.h on the and is attached here for reference. The green description after the command is not needed and is only shown for clarification. This list can be customized and increased in size to match the number of buttons you need.

retrogame custom

As you can see, my customized retrogame.c file (download and save it to the Adafruit-Retrogame-master folder if you want to use it) shown above is much longer than the original. I added the four other standard buttons and also start, select, and triggers. I avoided using pins 13 and 18 because they are used for audio output in my projects.

Once you are happy with your retrogame.c file, save the changes. It’s time to boot the Pi and finish the setup. A keyboard needs to be connected to the Pi for the next steps. When your system finishes booting, you need to exit to the command prompt. If you’re using RetroPie, just tap F4 on the keyboard. You will be put into folder /home/pi. From here we can create a folder for all the GPIO software, then move the Retrogame program to that folder. Use the commands shown below, and make sure you type them exactly as shown. Capitalization matters. The green text is for information only, and shouldn’t be typed.

mkdir GPIO //Creates a new folder called GPIO
cd GPIO //Switches to the GPIO folder
sudo mv /boot/Adafruit-Retrogame-master .  //Moves the Retrogame folder to the larger OS partition
cd Adafruit-Retrogame-master . //Switches to the Retrogame folder

You’re now in the Adafruit-Retrogame-master folder, and the retrogame.c source code that you edited earlier needs to be compiled.

sudo make retrogame //Compiles the retrogame.c into an executable
sudo mv 10-retrogame.rules /etc/udev/rules.d/ //Moves the input rules file to the appropriate folder

Now it’s time to give this program a try. We want to test Retrogame to be sure it works before we add it to startup, so we run the following command.

sudo ./retrogame //Runs Retrogame

The program should now be running. You should see a blank line, so try pushing some of the buttons to see whether keypresses show up. When you’re satisfied that it works, press Ctrl+C to close the program. Now that it works, let’s move on to the last task of adding the program to startup.

sudo nano /etc/rc.local //Opens rc.local using the text editor called nano

Using your keyboard, move to the end of rc.local and type the following command on its own line at the very end, just before the line “exit 0”

sudo /home/pi/GPIO/AdafruitRetrogame-master/retrogame &

Now press Ctrl+O to save the file and then Ctrl+X to exit nano. Just reboot the system by typing sudo reboot, and you’re all done.

Questions? Comments? Leave a reply.

Leave a Reply