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!

The Plan

You’ll need:

• 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) can work but 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:

1. Download and setup RetroPie using the temporary HDMI monitor.
2. Download and setup additional Adafruit software “on top of” RetroPie.
3. 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.

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.

Initial Setup…

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 System Options:
  • Audio: force 3.5mm headphone jack (since HDMI will be disconnected later). In earlier releases, this is under Advanced Options.
• Under Display Options:
  • Underscan: disable (earlier releases: Overscan in Advanced Options)
• Under Interface Options:
  • SPI: enable

If using an older version of RetroPie, also select Expand Filesystem (recent releases do this automatically on first boot), enable the Device Tree under Advanced Options, and when enabling SPI above, answer “yes” when prompted whether to enable the kernel module.

These steps are optional but recommended:

• Change 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.

Configure Input

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):

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.

Networking

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.

Install ROMs

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…

Test It!

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.

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:

When run, this presents a list of Adafruit projects that use the PiTFT display, plus an option for manual configuration.

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).

Restoring Original Behavior

If you want to return to using regular HDMI output without the PiTFT screen, there are a couple of options:

1. Do a fresh RetroPie install on the card — this is easiest if you haven’t customized a lot of settings or installed lots of emulators and games
2. …OR… disable the fbcp software and restore HDMI video settings.

To disable fbcp, edit the file /etc/rc.local as root, e.g.

sudo nano /etc/rc.local

and comment out (insert a ‘#’) or delete this line:

Then edit /boot/config.txt, a la:

sudo nano /boot/config.txt

and comment out or delete these lines:

That will restore the default HDMI resolution on next reboot. If you need different video settings, run raspi-config and explore the Display Options.

Overclocking

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.

Bigger Text

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…

(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:

Retro Gaming with Raspberry Pi: Adding Controls: Hardware

Retro Gaming with Raspberry Pi: Installing Retrogame

Retro Gaming with Raspberry Pi: Configuring Retrogame

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:

Look for this line, most likely near the bottom:

(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):

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.

There’s yet another option besides the kernel modules or our userspace code: fbcp-ili9341, developed by Jukka Jylänki, takes extreme measures to maximize TFT frame rates and minimize latency. It’s the best choice for fast “twitch” gaming.

Some things to be aware of before trying this approach:

• Any PiTFT-related kernel modules you may have previously installed need to be disabled, and SPI needs to be disabled as well. It’s probably easiest to begin with a fresh install of RetroPie or Raspbian!
• Getting the very best performance requires lots of tweaking and trial-and-error! If you just want to get games up and running on a PiTFT, other options are simpler and may perform well enough. Remember, non-optimal doesn’t necessarily mean pessimal.
• We’re not involved in the development of this third-party code. Any issues…like if something stops working with a new OS release…will need to be brought up with the developer.
• Touch is not supported.

Setting Up

Complete instructions are provided on the project’s Github page. Here’s an abbreviated walkthrough for getting things up and running quickly:

Prior Pi experience is required. These directions assume you already have the Pi booting and on the network, and with ssh enabled (makes it easier to copy-and-paste the commands that follow). You’ll want some games on there for testing, and have configured the controls if using RetroPie.

To begin, let’s set the HDMI resolution to match the PiTFT. This makes games more “pixel perfect” on the small display.

Edit the file /boot/config.txt (this requires a “sudo” command) and add the following lines:

For the larger 480x320 PiTFT, replace the values 320 and 240 on the hdmi_cvt line with 480 and 320.

Some newer games might not look good at these coarse resolutions, or menus may appear large and unusable. What you can do is set the HDMI resolution to exactly twice the PiTFT resolution and the software will provide nice 2x2 area sampling…so that’s “640 480” for a 320x240 PiTFT or “960 640” for 480x320.

Reboot the system after making this change. If an HDMI monitor is connected, it’s possible that it won’t sync to these unusually low settings. That’s okay, we’ll do the rest through ssh…

If playing vector games (e.g. Battlezone, Vectrex games, etc.), things look vastly better if antialiasing is enabled. Edit the file /opt/retropie/configs/all/retroarch.cfg and change this line:

to:

Download, Build, Test

If using a Raspberry Pi 3 or a late-model (v1.2) Pi 2 along with any of the 320x240 pixel PiTFT displays, enter the following commands:

For any Pi 1 or Pi Zero variant, replace:

with:

For early-model Pi 2 boards (pre-1.2), use:

If using a 480x320 pixel PiTFT, replace the options:

with:

Don’t forget the two periods at the end of the “cmake” line! If you get a “CMake Error:” message, that’s probably the reason.

You can then test the program with:

This should mirror the current contents of the HDMI display to the PiTFT. Press Control+C to exit, and we’ll continue with more setup…

Fine Tuning

The above commands should get you up and running with decent performance in most cases. If you’re seeing any graphic “glitches” on the display, or if you really want to fine-tune settings to their fullest, the project’s README explains every detail.

If working to improve the frame rate, you’ll want statistics enabled. These are overlaid on game graphics, so you’ll want to work everything out and then disable statistics afterward.

To enable statistics, on the cmake line, replace:

with:

(Or 2 if you want a frame rate graph as well.)

After making changes with cmake, rebuild the software and retest:

Test out your favorite games using various settings (with guidance from the README) to narrow in on the best performance, then build once more with statistics disabled.

Run on Startup

When everything looks good, let’s set up the system to run this automatically…

Edit the file /etc/rc.local (this requires a “sudo” command) and insert a line just above the final “exit 0”:

(Change the path if the software is situated elsewhere.)

Reboot and the software should run automatically. It may take up to a minute before it starts and shows anything on the PiTFT. This thread in the software’s repository talks about ways to get it started quicker at boot-time with a little extra work.