Getting Started with the RetroPie GPIO Adapter


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 as following:

[tabs type="horizontal"]
[tab_title]PCB Revision 1.5[/tab_title]
[tab_title]PCB Revisions 1.0 to 1.4[/tab_title]

  1. Make sure that you have all components: 2x5 pins male header, 2x13 pins female header, polyfuse, button, PCB:IMG_1990_small
  2. In contrast to revisions 1.0 to 1.4 of the adapter, you do not need to solder the SMD parts (74HC125 and 10K resistor) yourself.IMG_1996_small
  3. 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:IMG_1991_small
  4. Solder the 2x13 pins female header. Again, you might want to put something under the adapter to ease the soldering in this step:IMG_1992_small
  5. Solder the fuse and the button:IMG_1994_small
  6. Visually check for unintentional solder bridges. We also recommend to check with a multimeter at least for a short circuit between VCC and GND:IMG_1995_small


  1. Make sure that you have all components: Resistor, IC74HC125, 2x5 pins male header, 2x13 pins female header, polyfuse, button, PCB:a1
  2. Solder the resistor and the 74HC125. Take care for correct orientation: Pin 1 must be directed towards the fuse holes:a2
  3. 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:a3
  4. Solder the 2x13 pins female header. Again, you might want to put something under the adapter to ease the soldering in this step:a4
  5. Solder the fuse and the button:a5
  6. Visually check for unintentional solder bridges. We also recommend to check with a multimeter at least for a short circuit between VCC and GND:a6


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.

The ribbon cable is used to connect the SNES sockets with the 2x5 pin header of the RetroPie GPIO Adapter, which is shown in this picture:

One end of the ribbon cable get a crimp connector. To make the description easier in the following take care for the salient on the crimp connector so that the pin out looks like this:


With the assumption that the salient faces upward, the pin out of the 2x5 header on the GPIO Adapter look as shown in this figure:

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:ImageUploadedByTapatalk1368677420.984039

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/input/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/input/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.

Video Guide

Here is a short video that should also support you with the installation:

[lightbox full="" title="RetroPie GPIO Adapter: Software Installation Guide"][/lightbox]


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!

  • mattg8

    wish my brother would have read the description of the item as i can solder to save my self lol hopefully i dont stuff it up 2 bad

  • Hugh

    Is the button a standard momentary switch? Could you wire any switch to the same terminals? I ask because I am putting a rpi in an old broken NES, and I want to use the reset button on the nes as the "esc" key to exit games. Would I be able to wire it to the adapter? Because a switch on the rpi itself is not very useful for my purposes. Also, can it be changed so that it doesn't need to be 3 presses? I would rather it responded to a single press.

  • smartroad

    Does anyone know where you can buy the SNES sockets in the UK/Europe? I can only find US suppliers and it costs more in postage than the sockets cost!

    • petRockBlog

      So far, the easiest way I found is to buy one or two extension cables for SNES controllers. You can get these at eBay, Amazon, and many other electronic distributors.

  • Tyler Hampson

    could you wire the SNES controller directly into the GPIO adapter instead of having an extension socket?

    • petRockBlog

      Yes - you could wire up to two SNES controllers directly into the GPIO adapter.

  • Mace

    Got this last wick and soldering it wasn't bad at all! I was having issues getting SNESDev to autostart at boot though with the part of the guide on Github. So instead I made a executable script and added it the root crontab "@reboot bash /home/pi/scripts/" and all the script says is '#!/bin/bash /usr/local/bin/SNESDev', Works great!

  • adammhaile

    Maybe you could add hookup diagrams for NES controllers and not just SNES?

    • petRockBlog

      Good idea! I will add the diagram in the next days.

      • adammhaile

        Awesome! Thanks! Just wanted to make sure NES controllers would work :) And now I think I'll buy one of the adapters :)

      • petRockBlog

        Until the diagram is added, you can find a description and a diagram for hooking up NES controllers at

  • Bessel

    what is the IC74HC125? And my PCB I received is slightly different than the one shown

    • petRockBlog

      There has been a minor change in the PCB layout lately. This change added two additional pull-up resistors to enhance the SNES connector interface in case of unconnected gamepads. All resistors are combined within a single SMD component, a resistor network. The adapters with this change have the revision number 1.5 and I would guess that you also have such an adapter. If you are interested, the updated schematics can be found at

      Also the assembly guide for the most recent adapter was just updated here.

      I hope that helps!?

  • Ashley Leary

    Hi mate. No luck with trying to get the SNES pads working. I've got as far as installing retorpi, installing SNESDev (starting from boot with keyboards and pads polling) but when I get to the white screen where it says press button for player 1, nothing is picked up. Can you suggest any troubleshooting tips? Also just to double check, does the 2x5 pin face into the pi board or away from it (ive tried both ways to no avaial but I wanted to be sure which one was right!!!) Thanks.

    • petRockBlog

      The 2x5 pin header has to point into the pi board.

      Did you try and test the button of the adapter (described above in the section "Software: A tool for testing the button").

      Double check, if all pin connection to the SNES connectors are soldered correctly.

      Did you follow the steps described in section "Software: SNESDev for polling the game pads"? Does the jstest command give you any further hints?

      • Ashley Leary

        I'll give it all a try. Thanks for the reply.

      • Ashley Leary

        Still no further with it mate, doing my nut in now. Can't get the jtest to work, just says no such location or something along those lines (currently doing a full reload....) Could you check my board to see if the ribbon is right? Header facing down and black on the far side. Desperate to get this working...

      • petRockBlog

        The orientation of the ribbon cable matches that of the description in this article.

        There was a typo in the js command in the article that I just fixed. It should be jstest /dev/input/js0

        Maybe a video would be helpful here that would show the steps for installing and configuring SNESDev. Which information/content would be helpful for you? I could try and generate such a video within the next few days ...

        Alternatively, you could also post your question in the forum at

      • Ashley Leary

        Thanks for offering to make a video mate. If i'm honest, a video from start to finish would really help. I'll try the jstest without the s on the end of input tonight. One other thing, I'm using a 3rd party replica pad as opposed to an official nintendo SNES pad - do you think that would affect if or have you used/heard of people using the replica pads and them working.

        Once again, thanks for your help.

      • petRockBlog

        A replica should work as well - in the end it has to use the same protocol as the original pads for polling the button states.

        I cannot make any promises, but there is a slight chance that I can make that video within the upcoming weekend.

      • Ashley Leary

        No worries. I'm very grateful for all your help. Anything you can make and whenever you can make it will be greatly appreciated. I've got a bit of spare time this weekend so going to give it another go, looking at everyone elses comments and the guides you've made - maybe it will work!!

      • Ashley Leary

        Hi mate, quick update. I got the jtest working. It said off off for all but every now and then the axis ones would flash a number up and off for a split second.

      • petRockBlog

        This might indicate a broken solder connection on the connectors site.

      • Ashley Leary

        How would I test/fix that?

      • petRockBlog

        I mean the connection between the ribbon cable and the SNES connectors. Just a guess, though.

      • Ashley Leary

        I think they're all fine mate. Checked them :-S

      • petRockBlog