The Ideal: Adafruit’s PiTFT displays are razor sharp. Whereas small composite screens on the Raspberry Pi usually require some video scaling (resulting in blurriness), PiTFT uses the GPIO header, digitally controlled pixel-by-pixel for a rock steady image. Though not a lot of pixels, it works great for retro gaming (and the display neatly stacks above the board, no side protuberances for video cables).
The Downside: this GPIO link entirely bypasses the Pi’s video hardware, including the graphics accelerator. Many games and emulators depend on the GPU for performance gains. So the PiTFT has traditionally been limited to just a subset of specially-compiled emulators that can work and run well enough without the GPU.
The Solution: our latest PiTFT drivers, along with a tool called fbcp (framebuffer copy), careful system configuration, and (optionally) the more potent Raspberry Pi 2 board open the doors to many more gaming options. Existing emulator packages (such as RetroPie, with dozens of high-performance emulators and ports) — previously off-limits to the PiTFT — can run quite effectively now!
- Most any model of Raspberry Pi computer (Model A, B, A+, B+, Pi 2 or Zero).
- A 320x240 pixel PiTFT display (2.8" resistive, 2.8" capacitive, 2.2" HAT). For gaming we won’t be using the touchscreen features, but still need to distinguish among the various models. The 3.5" PiTFT (480x320) is NOT recommended for this project — more pixels means slower refresh.
- A 4GB or larger microSD card (or a full-size SD card for “classic” Model A or B).
- An HDMI monitor and USB keyboard are used temporarily during installation and setup.
Emulators require game ROM files. These are not included. Native, non-emulated ports of Doom, Duke Nukem 3D, Quake and Quake 3 are available (explained on next page) that don’t require additional ROM files.
Steps will include:
- Download and setup RetroPie using the temporary HDMI monitor.
- Download and setup additional Adafruit software “on top of” RetroPie.
- Configuration to redirect game output to the PiTFT screen; HDMI screen is then no longer needed.
Though we focus on RetroPie, some of these steps should be applicable to other software.
This is not a guide for first-timers. Some prior familiarity with Raspberry Pi (SD card prep, network configuration, etc.) is assumed.
Current Cupcade or PiGRRL users…
If you’d like to try this, we suggest using a separate SD card…don’t upset your working Cupcade installation. Set your original card aside for safekeeping! This guide is still experimental. If it all works out well, we’d like to make this our “official” method for gaming with the PiTFT, but not yet…it might not work for everyone, configuration may be troublesome, or the performance might not feel as snappy on some systems.
Any MAME ROMs you’re currently using with Cupcade or PiGRRL might not work with RetroPie — they’re based on different versions of MAME, and the ROM file format they used changed along the way. You may need to convert or acquire new ones.
Let’s begin our adventure on the Retropie downloads page. Fetch the version appropriate to your Raspberry Pi board type — there are separate SD card images optimized for the Raspberry Pi “1” (Models A, B, A+, B+ and Zero), and another for the Raspberry Pi 2 or 3.
If you’ve used RetroPie in the past, check if a newer release is available…it’s updated frequently! This guide requires version 3.6 or newer.
While that downloads, you can get started with formatting a 4GB or larger microSD card (or full-size SD if using a “classic” Model A or B).
After downloading and uncompressing the RetroPie image, you can write it to the SD card as you would any other operating system. It’s explained in this guide.
Use the latest RetroPie image (3.6 or newer) optimized for your board type (Raspberry Pi 1 or 2/3).
Insert the SD card in the Raspberry Pi. Plug in an HDMI monitor, USB keyboard, then connect power.
On first boot, you should see some Linux console messages scroll by, followed by a RetroPie splash screen. It will report that it’s resizing the SD card partition, then performs a reboot cycle. The second time around, you’ll get the RetroPie splash screen, followed by the EmulationStation splash screen, and then it will prompt you to configure an input device.
You do not need to configure inputs yet…instead, press F4 to exit EmulationStation and get a Linux prompt. Then we’ll do some basic system configuration…
The following raspi-config options are required:
- Under Advanced Options:
Device Tree: enable (not an option in newer releases; it’s always enabled)
SPI: enable and load kernel module by default.
Audio: force 3.5mm headphone jack (since HDMI will be disconnected later).
- If you are using an older version of RetroPie, select the “Expand Filesystem” option. Recent releases do this automatically on first boot.
These steps are optional but recommended:
Change User Password (since everyone knows the default).
- Under Internationalization Options, select Change Locale, Change Timezone and Change Keyboard Layout to your liking. If keys aren't producing the expected characters, this is why.
- Under Advanced Options, change Hostname if desired (default is “retropie”) and enable SSH (for remote administration).
DO NOT select:
- Overclock. We can enable this later, but there are some important details that need explaining with the PiTFT first! Start out at the default speed.
- Memory Split. In the past when using the PiTFT you'd want this as small as possible (16 MB). But now that we're actively using the GPU, we want some GPU memory, so don't touch this!
When you’re done, tab to “finish” and reboot when prompted.
After rebooting, the system will once again ask you to configure an input device. Let’s set it up for keyboard input for now (we can change this later). Hold down any key on the keyboard for a few seconds until it starts asking for keys to assign to certain controls.
There are a HUGE number of inputs (shoulder buttons, dual analog sticks, etc.)…but for any you don’t anticipate using you can just hold a key down for a few seconds and it will skip ahead to the next option. As an 80’s kid, I spend most of my time in MAME, so I configure EmulationStation’s input to be fairly minimal (but your emulator of preference might be different):
Key on Keyboard
Left Alt or Command
Remember — once configured, EmulationStation is navigated using these keys only. So, for example, the Return key won’t necessarily select an item, even though the same key may have the expected effect within some emulators.
You can set set up a more extensive combination of inputs for different emulators later…no need to get serious with the gameplay yet, just confirm that things launch as expected. Most emulators will exit and return to the EmulationStation menu with the Escape key.
Later, you can reconfigure it for a gamepad…you’ll need to access the EmulationStation settings menu with a keyboard still attached. Press the key you’d configured as “Start,” then select “Configure Input,” then proceed through each control as you did before with the keyboard, but using the gamepad now.
The control settings you select here don’t always carry through to some emulators. Others may have their own settings that overlap the keys you’ve chosen, causing mayhem. See the “Configuring Individual Emulators” section for tips on finding each emulator’s individual config file, so you can fine-tune these aspects.
If you don’t plan to use networking, skip ahead to the next section below: Install ROMs. You’ll need to use a USB flash drive and move files manually from the command-line.
Loading ROM files is most easily done on a wired Ethernet network. Recent RetroPie releases already have file sharing enabled; the system should appear on your network as “retropie.local” (unless you gave the system a different hostname during the initial setup).
If you plan to use wireless networking…the RetroPie menu includes an option for configuring WiFi, but I couldn’t get this to connect. If you have trouble with it, press F4 to exit EmulationStation for a command-line prompt and set up WiFi the old-fashioned way, by editing /etc/wpa_supplicant/wpa_supplicant.conf. Here’s a guide for basic network setup on Pi.
Once networking is all set up (it may require another reboot), you should be able to access the RetroPie system remotely…as a network share for transferring files, and (if you enabled SSH in raspi-config) for remote login to finish certain command-line tasks later.
You can always exit EmulationStation with the F4 key for a command line prompt, but remote login has the benefit that you can copy-and-paste some of the commands we’ll be using.
Networking must be configured and operable before proceeding.
Emulators require ROM files. If you don’t want to do this step, that’s okay…a few self-contained games can be installed in the “Ports” section of EmulationStation, such as Doom and Quake (explained in next section below).
With networking enabled, it’s possible to copy the ROM files across the network — the retropie system should be visible as an SMB or AFP share. Alternately, you can fill a USB stick with ROM files, mount this on the Raspberry Pi and move them to the appropriate locations.
ROM files are installed in specific subdirectories of /home/pi/RetroPie/roms — one for each different emulator package. For example, NES roms go in the “nes” directory.
Some systems are supported by multiple emulators (for example, there are different MAME implementations, each with its own directory). Each emulator has its own quirks — some may render or perform better than others, or some might not work with certain ROMs. Hunting down these quirks and determining your preference for one emulator over another is a process you’ll have to work through yourself…there are just too many emulators and far too many ROMs for us to know them all. There are entire sites and forums devoted to the various emulators, and you may need to Google around and do your own research on the best selections for different games. The RetroPie web site and EmulationStation web site are great places to start to start, with forums, FAQs and wikis.
Additional Emulators and Ports
Version 4 (and later) of RetroPie does not include games like Doom and Quake by default. If you’re patient and reasonably tech savvy, you can add these on after the fact…
An emulated system won’t show up in the EmulationStation menu until corresponding ROMs are installed…but it only scans for ROMs at startup. It’s easiest just to reboot…or you can exit to the command line (F4) and type “emulationstation” to restart the menu.
If you haven’t already configured the keyboard or a gamepad for input, do that now. Hold down a key or button and proceed through each button when prompted.
Do not continue until you’re able to successfully launch one or more games, displayed on the HDMI monitor.
This sequence requires RetroPie (3.6 or later) or Raspbian Jessie or Jessie Lite (2016-03-18 or later). “Native” PiTFT support like this is a recent addition…older Raspbian releases (Wheezy, etc.) are not compatible. The 3.5" PiTFT is supported as of RetroPie 4.1 or Raspbian 2016-11-25.
With the emulator(s) working, now we’ll re-route the graphics to the PiTFT. This is the cool part…as far as the Raspberry Pi is concerned, it thinks there’s still an HDMI display attached. This is a departure from how the Cupcade system worked, where the PiTFT was the only display.
If you don’t already have the PiTFT assembled and connected, do that now. Shut down the Raspberry Pi (in EmulationStation, select “Shutdown System” from the “Quit” menu, or type “shutdown” on the command line, wait for the “halted” message and then unplug), solder the socket to the PiTFT board, plug it into the GPIO header (making sure all the pins are aligned) then re-connect power. Don't install any software yet, just solder up the pins if necessary!
When first powered up, the display will be blank white. This is normal.
If you’ve enabled SSH, these next steps are most easily done with a remote login…commands can simply be copied and pasted from the web browser into a terminal window. If not, that’s okay…press F4 to exit EmulationStation and type these commands very carefully.
We’ve written a script to install all the PiTFT-related software and perform some related system configuration. From the command line:
curl -O https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/pitft-fbcp.sh
sudo bash pitft-fbcp.sh
curl -O https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/pitft-fbcp.sh
sudo bash pitft-fbcp.sh
When run, this presents a list of Adafruit projects that use the PiTFT display, plus an option for manual configuration. (As of this writing, only the PiGRRL2 project is on the list, but more will be added over time.)
If using a resistive-screen PiTFT (2.4, 2.8 or 3.2 inches), in most cases you can select the PiGRRL 2 option, this setup will do what you need. At worst, the screen might be rotated 180 degrees, in which case try it again with the “manual” option.
For the manual option: select your PiTFT screen type from the first list. For the second (HDMI rotation), you’ll almost always want option #1 (0 degrees rotation), unless you plan to use your display in a vertical “portrait” orientation. For the third selection, it depends which way you plan to orient the display when in use: PiGRRL 2 expects option #4 (270 degrees), or you might want it flipped the other way with option #2 (90 degrees).
Before continuing, the current selections will be displayed. When you proceed, the script automatically does the following:
- Updates the package index files used by apt-get
- Installs cmake, needed by the next step
- Downloads and installs fbcp, which mirrors HDMI output to the PiTFT display
- Configures miscellaneous system files to use the PiTFT display
On completion, you’ll be prompted to reboot the system. Unless you have other system configuration to perform, do this.
On startup, after a few seconds’ delay, you should see the RetroPie splash screen on the PiTFT, followed by the rest of the boot process and then EmulationStation. Go ahead and try launching something!
If an HDMI monitor is still attached, and if it supports 320x240 resolution, you should see the same content on both the monitor and PiTFT. Not all HDMI monitors can display this resolution — you might see “no signal” on the monitor after reboot. That’s okay…with everything set up right, it’ll all be routed to the PiTFT after a few seconds’ boot time.
Once the system is working satisfactoraly, you can disconnect the HDMI monitor. Everything’s now done through the PiTFT (or remote login via SSH).
Because the Raspberry Pi is more powerful than many vintage systems, most emulators run at an acceptable speed. A few (such as SNES) aren’t quite up to snuff. We can narrow this gap by overclocking the Pi, but there’s just one little gotcha to watch out for…
fbcp starts to misbehave if the core frequency exceeds 300 MHz.
Some of the higher overclock settings that raspi-config offers far exceed this…
Therefore, if you enable these faster settings, don’t immediately reboot…exit raspi-config to the command line and then edit the file /boot/config.txt to dial back the core frequency to an acceptable range (300 max):
After saving the changes, then reboot.
Moderate overclocking is usually trouble-free, but if you really push it, some systems won’t boot. Don’t panic! With an SD card reader, the /boot partition will mount normally on most computers, and you can edit the config.txt file there, dialing back the speed until you find a stable setting.
The EmulationStation UI looks nice on a high-resolution monitor, but on the PiTFT the game lists can be hard to read. We can adjust the font size to help…
sudo nano /etc/emulationstation/themes/carbon/carbon.xml
sudo nano /etc/emulationstation/themes/carbon/carbon.xml
(In earlier versions of EmulationStation, the file was called simple/simple.xml, and might change again in the future…you may need to poke around the “themes” directory to find the default settings file.)
Scroll down to the “gamelist” section and change any occurrence of the value of fontSize to 0.05.
After saving changes, you can either reboot, or (with USB keyboard attached) press F4 to exit followed by “emulationstation” to restart.
Configuring Individual Emulators
Settings for each emulator are stored in /opt/retropie/configs
Some are configured by editing text files…for example, /opt/retropie/configs/nes/retroarch.cfg
Others provide an interface in the emulator itself…for example, in MAME press the TAB key for a configuration menu that can be navigated with the keyboard.
Configuration for all the emulators is way beyond the scope of a single guide…but each emulator has its own web site and documentation, sometimes forums as well. A little Googling will reveal all the secrets. The RetroPie and EmulationStation web sites both have a ton of helpful information, including forums, FAQs and documentation.
Unfortunately the EmulationStation controls you previously configured are not automatically transferred to the emulators…each one will need work. This might be addressed in future versions of EmulationStation.
Adjusting GPU Memory
This tweak is mostly for the Model A or A+ and the very earliest Model B boards. With only 256 MB RAM available, one must split this carefully between CPU (which needs RAM for running emulators) and GPU (needing RAM for graphics). It’s a non-issue for later boards with ample RAM.
Edit the file /boot/config.txt
Search for any existing entries for gpu_mem_256, gpu_mem_512, or gpu_mem_1024. You may comment out or delete these lines.
Add a new line, or edit any existing entry for gpu_mem, setting its value to 44 megabytes:
Save the file and reboot.
Though the Pi can boot with as little at 16 megabytes of GPU memory, 44 MB is the bare minimum required for the EmulationStation menu to work.
With this modification, some parts of the EmulationStation UI might be more visually plain than before…solid colors instead of images, etc. This is normal. In exchange, most games will perform noticably better on these systems with limited RAM.
If you have a Model B, B+ or Pi 2 or 3, this adjustment isn’t necessary and won’t provide any benefit.
Half the fun of these PiTFT displays is making tiny portable projects. Having a giant USB keyboard attached runs counter to that. One more piece of software called retrogame lets you connect buttons directly to the Raspberry Pi’s GPIO header and simulates key presses. We use this in a lot of our gaming projects!
Retrogame is already covered extensively in its own guide:
Keep in mind you’ll want to steer clear of the GPIO pins used by the PiTFT display — they’re indicated in that guide.
The native resolution of the PiTFT screen works quite well for retro gaming — quite a few 1980s CRT-based arcade and home systems worked at or around this same resolution.
For certain projects though…emulating later systems, home computers with higher-resolution displays, or if you just want to run GUI-type X11 Linux applications on the PiTFT…there just aren’t enough pixels. Application windows and other elements may extend off the right or bottom edges of the screen.
The fbcp program (installed by our script on the PiTFT Setup page) has the ability to scale higher-resolution graphics down to the PiTFT’s limited size, with image interpolation so elements like text (unless extremely small) are often still quite legible at the reduced size. fbcp does all this automatically, we just need to change the HDMI output resolution, and on next boot we have a larger graphical canvas (the actual PiTFT resolution itself does not change).
Edit the file /boot/config.txt — use the “sudo” command for root access:
sudo nano /boot/config.txt
sudo nano /boot/config.txt
Look for this line, most likely near the bottom:
hdmi_cvt=320 240 60 1 0 0 0
hdmi_cvt=320 240 60 1 0 0 0
(On the 3.5" PiTFT, the first two numbers will be 480 and 320.)
Try doubling the values to 640 and 480 (or 960 and 640 for the 3.5" PiTFT):
hdmi_cvt=640 480 60 1 0 0 0
hdmi_cvt=640 480 60 1 0 0 0
Save changes to the file, then exit and reboot. When the system comes up, you’ll see everything is smaller, but antialiased and still generally legible.
You can use even higher resolution settings if needed (up to the Pi’s full HD resolution), but this 2X scale is optimal. The bilinear image interpolation algorithm may start to drop details if the HDMI resolution is more than 2X the PiTFT resolution. An exact 2X scale also maintains the same 4:3 aspect ratio as the PiTFT (3:2 for 3.5"), so the image isn’t “squashed” horizontally.
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.
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.
Some of my buttons/controls aren’t working!
- 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.
NONE of my buttons/controls are working!
- 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.
My controls only work if there’s also a USB keyboard plugged in!
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.
Retrogame doesn’t work with my optical buttons!
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).
I ran Adafruit’s retrogame installer script and rebooted, and now the keyboard and network are unresponsive!
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…
My controls work in the EmulationStation UI, but not in one or more specific emulators!
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).
The ROM files I have worked in a different emulator before, but aren’t working in RetroPie!
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.
Installing RetroPie Packages
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.
Accessing Alternate Emulators
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: