This is a guide that describes how to get started with the RetroPie GPIO Adapter. It is organized as a step-by-step guide: Starting with the sole components and the PCB the hardware assembly is described in the first part. The second part then guides you though the software topics by describing how to test the button and how to enable SNESDev for polling the controllers.
Hardware: Assembly of the RetroPie GPIO Adapter
The assembly of the RetroPie GPIO Adapter can be done in six steps:
- Make sure that you have all components: Resistor, IC74HC125, 2x5 pins male header, 2x13 pins female header, polyfuse, button, PCB:
- Solder the resistor and the 74HC125. Take care for correct orientation: Pin 1 must be directed towards the fuse holes:
- Solder the 2x5 pins male header. As you can see on the picture, you might want to use a tool as some sort of fixture during the soldering:
- Solder the 2x13 pins female header. Again, you might want to put something under the adapter to ease the soldering in this step:
- Solder the fuse and the button:
- Visually check for unintentional solder bridges. We also recommend to check with a multimeter at least for a short circuit between VCC and GND:
Hardware: Connecting the ribbon cable with the adapter
The RetroPie GPIO Adapter was constructed such that it is able to poll up to two game pads that make use of a shift-register for serializing the status of each component of the game pads. The SNES and NES controllers work in this way. In the following it is described how to connect two SNES sockets to the ten-wire ribbon cable.
Hardware: Connecting SNES sockets with the ribbon cable
Now, you need to solder the ten wires of the ribbon cable to the pins of the two SNES sockets. The two pictures above show the pin out of every single wire of the cable as well as the pin out of a SNES socket. You need to rip up the ribbon cable, dismantle the insulation and solder each wire to the according pin of the SNES sockets. The result might look similar to what is shown in this picture:
Hardware: connecting the RetroPie GPIO Adapter with the Raspberry Pi
During the design of the board I was not aware of the “safe mode” of the Raspberry Pi: Adding a jumper between pins 5 and 6 of P1 results in /boot/config.txt being ignored (except for avoid_safe_mode) and a default cmdline.txt is applied, followed by loading kernel_emergency.img. As stated in the official forum
if you connect external hardware to that pin, the worst that will happen is it falsely triggers safe mode.
To avoid this safe mode when the adapter is attached a setting has to be made in /boot/config.txt. This could be done, for example, by opening the config.txt with
sudo nano /boot/config.txt
and saving the changes with “Ctrl-X”, which has to be confirmed with “Y”.
The adapter must be put on the GPIO pins of the RPi such that the 2x5 pin header faces inwards the PCB of the RPi.
Software: A tool for testing the button
In order to check the correct assembly of the adapter, you can test the button first. A simple command line tool is contained in the SNESDev repository. You can install SNESDev either by using the RetroPie Setup Script or by following the instructions on the welcome site of the SNESDev repository. The command line tool testButton is contained in the subfolder supplementary/testButton/. While the tool is running it continuously prints the status of the button to the console. You can exit the program with "Ctrl-C".
Software: SNESDev for polling the game pads
SNESDev is a user-space device driver especially written for the RetroPie GPIO Adapter. It implements two (S)NES game controllers and a virtual keyboard for up to two (S)NES controllers and a button that are connected to the GPIO pins of the Raspberry Pivia the RetroPie GPIO Adapter.
SNESDev can be enabled from within the RetroPie Setup Script. You find the option for that in the when you select "Setup" in the main menu of the script. The RetroPie Setup Script can also be used to install a kernel-space driver for polling various game pads, which is also known as "gamecon driver". Do not enable the gamecon driver and SNESDev at the same time, because both access the GPIO pins and they do interfere with each other.
The RetroPie Setup Script installs SNESDev in the directory
/usr/local/bin. A binary and (optionally) the sources of SNESDev can also be found in
/home/pi/RetroPie/supplementary/SNESDev-RPi, but these are not used when SNESDev is enabled with the RetroPie Setup Script. SNESDev runs as a service such that it can be startet, e.g., with the command
sudo service SNESDev start. SNESDev counts the numbers of button presses and reacts differently to these: If you press the button 3 times, the press of the ESC key is simulated. If you press the button 5 times, the shutdown command is executed.
The correct connection with the game pads can be tested from command line with the tool jstest, which is installed with the command
sudo apt-get install joystick.
If you want to test your first game pad, you run
jstest /dev/inputs/js0 and get an output similar to this:
Axes: 0: 0 1: 0: Buttons: 0:off 1:off 2:off 3:off 4:off 5:off 6:off 7:off
To test your second game pad you can use the command
jstest /dev/inputs/js1. If you are using Emulation Station and want it to show the input configuration screen again, you need to delete the file /home/pi/.emulationstation/es_input.cfg to have Emulation Station show the configuration screen again.
This concludes the tutorial for getting started with the RetroPie Adapter. If you feel that any information is missing in this guide feel free to give comments!