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.