This page documents the most common pitfalls encountered when making retro gaming projects, offering some solutions and where to turn for further help.
There are some things we can fix and some we can’t…we’re not involved in RetroPie’s development, for example…but we’ll try to point you in the right direction.
Most of the following troubleshooting steps will require a USB keyboard attached. Some require a network connection.
General Troubleshooting
There’s a lightning bolt icon in the upper right part of the screen!
- That icon means the Raspberry Pi isn’t receiving adequate power; most likely, you need a higher current power supply. Very occasionally this is caused by a flimsy USB cable with thin wires…try swapping out for something heftier.
retrogame Related Troubleshooting
retrogame is our software that converts GPIO button actions into keyboard events. These are the problems we’re best equipped to fix.
Some common things to check for any retrogame installation:
- Confirm button/joystick wires go to the correct pins and to ground. A multimeter with a continuity beep function is helpful for testing.
- The retrogame configuration file (/boot/retrogame.cfg) uses Broadcom pin numbers…these are not sequential along the GPIO header pins. This site has a nice reference chart (use the “BCM” numbers).
- Earlier versions of retrogame didn’t use a configuration file…you had to edit and compile the source code. That’s just horrible. If you’re running an early version like that, this would be a good time to upgrade. See the Installing Retrogame page.
- Check connections and configuration file pin numbers as explained above. (If some controls are responding, that’s an encouraging start…it at least means the code is running.)
- The key codes generated by retrogame might not be assigned to EmulationStation’s keyboard inputs; one or the other will need to be changed. Either edit /boot/retrogame.cfg, or, from the EmulationStation main screen, press Start to access the main menu, then select “Configure Input” and proceed through each of the controls.
- Confirm that retrogame is actually running…either exit to the command line (F4) or log in using ssh, then use “ps -ef | grep retrogame” to check. If you used our installer script or one of our ready-made SD card images, it should be started automatically on boot (added to /etc/rc.local).
- Confirm that the file “/etc/udev/rules.d/10-retrogame.rules” exists. Our installer script creates this file, but if you installed retrogame manually or from source, it may have been overlooked.
Confirm that the file “/etc/udev/rules.d/10-retrogame.rules” exists. Our installer script creates this file, but if you installed retrogame manually or from source, it may have been overlooked.
Unfortunately, yes. retrogame only works with “passive” switches between a GPIO pin and ground (logic low=pressed). It won’t work with switches that have the opposite logic level (high=pressed).
This can happen if you’re running an early Raspberry Pi (Model A or B) with the 26-pin GPIO header and select the “Six buttons + joystick” option in the retrogame installer. That particular configuration is set up for our Arcade Pack and newer (40 pin) Raspberry Pi boards. Some of the pin numbers referenced don’t exist on the older 26-pin header and lead to trouble.
If this happens to you, not to worry. Power off the Pi and insert the SD card in a reader on a PC or Mac. Look for a file called retrogame.cfg…edit this file and change the pin numbers to match your specific controller wiring.
RetroPie Related Troubleshooting
RetroPie provides the actual emulation software and a nice user interface. As this is third-party code, the “depth” of problems we can troubleshoot is more limited, but here are some of the common issues we’ve seen and how to resolve them…
This can happen with certain emulators (usually older or more esoteric ones) that don’t use the libretro library. Among other things, libretro allows the global controller configuration to be used everywhere. There are a couple of workarounds that might help, but no guarantees…
- You can rummage around in /opt/retropie/configs and look for a configuration file specific to the problem emulator, then edit its keyboard layout to match your controls. The format of this file, if one even exists, is likely specific to that one emulator, so you’ll need to do some research (Google search, etc.), it’s not something we can help out with.
- You can try hunting for an alternate emulator based on libretro, if there’s one available (see “Installing RetroPie Packages” below).
This can happen if the ROM file format changes between versions of an emulator, or if two emulators for the same system use different formats.
- Do some research (Google search, etc.) to see if this is the case. It’s possible there may be utilities to convert among different ROM formats.
- Try installing an alternate emulator, if there’s one available (see “Installing RetroPie Packages” below).
A few emulators may require a “BIOS file” in order to function, but it’s not included with the software for legal reasons. This is something you’ll have to research and track down.
To add support for a system not present in RetroPie by default, or to add an alternate emulator program for an existing system, select “RetroPie Setup” from the RetroPie menu. This brings up a text-menu-based interface and will require a USB keyboard to navigate.
Select “Manage packages” and then one of the core, main, optional or experimental selections…you’ll probably want to navigate through each of them to see what’s available, keeping in mind that each successive category might be a little rougher around the edges.
Your best bet are packages whose names begin with “lr-”. This means they’re built using libretro and the control inputs should already work with what you have! Other packages may require their own manual controller setup, which can be a real nuisance.
When asked, select “Install from binary.” The source option takes much longer and won’t provide any benefit for the average user…only attempt that if you know you need absolutely bleeding-edge code.
It’s totally valid to install multiple emulator packages that handle the same type of system. Each might have different performance or compatibility benefits, so it’s worth testing your options. See “Accessing Alternate Emulators” below.
When you launch a game, you’ll briefly see this nondescript launching message. You have a couple of seconds to hit a button or key…
The first option in this configuration menu lets you select a different emulator package for a given system type…or even on an individual ROM-by-ROM basis, if different games benefit from different emulation software.
Test it out with. If you don’t like the results, next time you launch that game you can access the configuration menu again and restore the original selection.
More RetroPie Help
For issues not covered above, the best sources for RetroPie-specific help are the official documentation and forum on the RetroPie web site:
Page last edited March 08, 2024
Text editor powered by tinymce.
