1. technology and computing
2. operating systems
3. linux

Running OpenGL-based Games & Emulators on Adafruit PiTFT
Displays
Created by Phillip Burgess
Last updated on 2015-03-12 03:45:05 PM EDT
Guide Contents
Guide Contents
Overview
The Plan
Current Cupcade or PiGRRL users…
RetroPie Setup
Initial Setup…
Networking
Install Emulators
Install ROMs
Test It!
PiTFT Setup
Tuning & Tweaking
Overclocking
Bigger Text
Configuring Individual Emulators
Adding Controls
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
2
3
3
4
5
5
7
8
8
9
11
16
16
17
18
19
Page 2 of 22
Overview
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 rely 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 much more potent Raspberry Pi 2 board open the doors
to many more gaming options. Existing emulator packages (such as RetroPie, with dozens of highperformance emulators and ports) — previously off-limits to the PiTFT — can run quite effectively
now!
The Plan
You’ll need:
Any model of Raspberry Pi computer (Model A, B, A+, B+ or Pi 2).
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 3 of 22
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 full-size SD 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. RetroPie includes Pi-native ports of
Doom, Duke Nukem 3D, Quake and Quake 3 that work without additional software.
Steps will include:
Download and setup RetroPie using the temporary HDMI monitor.
Download and setup additional Adafruit software “over” RetroPie.
Configuration to redirect game output to the PiTFT screen; HDMI screen is no longer needed
then.
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.
Two important things to know:
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 changed
along the way. You may need to convert or acquire new ones.
You’ll need to configure the controls repeatedly — once for EmulationStation (the
graphical front-end for selecting different emulators), then again for each game or emulator
(since these all operate independently, not using the same configuration files). That’s just how
it works for now. It’s explained a bit more on the EmulationStation web site…we’ll provide links
as we go along…
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 4 of 22
RetroPie Setup
Let’s begin our adventure on the Retropie downloads page (http://adafru.it/elt). Fetch the version
appropriate to your Raspberry Pi board type — there are separate SD card images optimized for
the Raspberry Pi Model A, B, A+ and B+ (http://adafru.it/eGW), and another for the Raspberry Pi
2 (http://adafru.it/eGX).
If you’ve used RetroPie before and think you might already have a card image, make sure you have
the latest version for this (2.6 or newer). The PiTFT package we’ll install later relies on
recent features of the underlying Linux distribution, and probably won’t work with older versions.
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 (http://adafru.it/evL).
Use the latest RetroPie image (2.6 or newer) optimized for your board type (Raspberry Pi 1 or
2).
Initial Setup…
Insert the SD card in the Raspberry Pi. Plug in an HDMI monitor, USB keyboard, then connect
power.
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 5 of 22
On first boot, you should see some Linux console messages scroll by, followed by a RetroPie splash
screen. It’ll go back to Linux messages for a moment, then the EmulationStation splash screen.
After a minute or so of booting, EmulationStation will prompt you to configure an input device. We
don’t need to do this right now…press F4 to exit EmulationStation and get a Linux prompt.
Then we’ll do some basic system configuration…
sudo raspi-config
The following raspi-config options are required:
Expand Filesystem
Under “Advanced Options,” disable Overscan, enable the Device Tree, SPI (load SPI kernel
module by default), and force audio through 3.5mm jack (since HDMI will be disconnected
later).
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 6 of 22
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.
Networking
After rebooting, you can then set up networking to your liking. “F4” again to exit EmulationStation for
a command-line prompt.
At the very least, you'll need an Ethernet cable connected. This will let you retrieve packages
needed for further installation. If you have a Model A or A+ with no Ethernet connection, it’s
easiest to set everything up on a Model B/B+ and then move the card over.
If you want wireless networking, set that up however you like it...either using ‘startx’ and the WiFi
Config tool on the desktop (requires a USB mouse), or manually by editing the wpa_supplicant
configuration file. Here’s a guide for basic network setup on Pi. (http://adafru.it/evM)
Personally I like to install netatalk, which can make it a little easier to access the system on the local
network. It’s explained a bit in this guide. (http://adafru.it/ehC)
sudo apt-get update
sudo apt-get install netatalk
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.
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.
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 7 of 22
Networking must be configured and operable before proceeding.
Install Emulators
RetroPie is a little bare by default…all the emulator packages need to be explicitly installed.
Press F4 to exit EmulationStation for a command line prompt (or log in with SSH), then type:
cd RetroPie-Setup
sudo ./retropie_setup.sh
The “Binaries-based INSTALLATION” option is selected by default, so you can just press the Return
key. Do not bother with the source-based installation…it can take an entire day for possibly
zero benefit!
The full complement of emulators is downloaded and installed by default. This may take about 30
minutes or so. Take a break, get some lunch or a shower or whatever. When you get back, there
will be a few pop-ups with notes for specific emulators.
Install ROMs
Emulators require ROM files. If you don’t want to do this step, that’s okay…there are a few self© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 8 of 22
contained games in the “Ports” section of EmulationStation, such as Doom and Quake.
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. Connect as user “pi” with the appropriate
password. 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 three different
SNES emulators, 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 (http://adafru.it/elu) and EmulationStation web site (http://adafru.it/eHt) are great
places to start to start, with forums, FAQs and wikis.
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 step just configures the EmulationStation input — it does NOT transfer to each emulator,
which must still be individually configured.
As an 80’s kid, I spend most of my time in MAME, so I configure EmulationStation’s input to closely
match the default MAME input (but your emulator of preference may be different):
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 9 of 22
Button
Key on Keyboard
Up/Down/Left/Right
Arrow keys
A
Left Control
B
Left Alt or Command
Start
1
Select
5
Page Up/Down
[ and ]
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.
We’ll set up the 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.
Don’t continue until you’re able to successfully launch one or more games, displayed on
the HDMI monitor.
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 10 of 22
PiTFT Setup
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, just solder up the pins if necessary!
The display will be blank for now, except for the backlight. 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.
First is to fetch the PiTFT configuration helper script:
cd
curl -SLs https://apt.adafruit.com/add | sudo bash
sudo apt-get install adafruit-pitft-helper
After downloading, run the configuration script with:
sudo adafruit-pitft-helper -t [screentype]
…where [screentype] is either 22 (2.2" HAT), 28r (2.8" resistive) or 28c (2.8" capacitive). (The 3.5"
PiTFT is not recommended for this project.)
For example, to install a 2.8" resistive-screen PiTFT, type:
sudo adafruit-pitft-helper -t 28r
When asked if you want the console on the PiTFT, enter ‘no’ — this is important! For this project,
we’re faking the Pi into thinking there’s still an HDMI display attached.
Whether to install the power-off button is up to you. It can be handy, but EmulationStation has a
menu option for the same thing.
Next we’ll install fbcp (a live framebuffer mirroring tool) following directions from
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 11 of 22
here (http://adafru.it/eHp):
sudo apt-get install cmake
git clone https://github.com/tasanakorn/rpi-fbcp
cd rpi-fbcp/
mkdir build
cd build/
cmake ..
make
sudo install fbcp /usr/local/bin/fbcp
(The guide linked above goes on to explain driver installation — you can ignore that, we’ve already
handled it with the adafruit-pitft-helper script.)
Then we’ll edit one file to launch fbcp fairly early in the startup sequence (feel free to substitute your
editor of preference in place of “nano”):
sudo nano /etc/init.d/asplashscreen
Look for a function called do_start(), then insert the following as the first line in that function:
/usr/local/bin/fbcp &
Looks like this:
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 12 of 22
Save the changes and exit.
This “asplashscreen” script is specific to RetroPie. If you’re working with a different OS
distribution, you might instead want to add this line to /etc/rc.local, just before the final “exit 0” line.
We won’t be seeing the console much, but for those rare occasions, let’s set it up for a font better
suited to the small PiTFT display:
sudo dpkg-reconfigure console-setup
Select “UTF-8”, “Guess optimal character set”, “Terminus” and “6x12 (framebuffer only).”
So close! Just a couple more things…
Edit the file /boot/config.txt, looking for the following lines. Most will already be there in various
places, but either commented out or with different values:
hdmi_force_hotplug=1
hdmi_cvt=320 240 60 1 0 0 0
hdmi_group=2
hdmi_mode=87
dtoverlay=pitft28r,rotate=90,speed=80000000,fps=60
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 13 of 22
The four “hdmi” lines set the HDMI output to 320x240 pixels, to exactly match the PiTFT resolution.
The “dtoverlay” line is related to the PiTFT driver. If this line is not present, don’t add it manually…
instead, double-check all the adafruit-pitft-helper installation steps above. If present, great…edit just
the numbers for speed (80000000) and fps (60), don’t touch the rest of the line. This sort of
“overclocks” the connection between the Pi and screen for faster frame rates…technically it’s out of
spec, so if you encounter glitches, you may need to back off a little (e.g. try 64000000).
Though the Pi has no trouble generating 320x240 video, not all HDMI monitors can display this. You
might see “no signal” on the monitor following the next reboot. That’s okay…with everything set up
right, it’ll all be routed to the PiTFT.
One last thing. We need to tell EmulationStation to not switch the HDMI resolution when launching
games. Otherwise fbcp stops dead in its tracks and will not come back…the PiTFT stops updating,
only solution then is to reboot.
sudo nano /opt/retropie/supplementary/runcommand/runcommand.sh
Scroll down a bit, looking for the function called get_mode(), and insert the following two lines at the
very start of the function:
mode_new = "DMT-87"
return
Like this:
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 14 of 22
Save the changes and reboot.
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.
Once the system is working satisfactoraly, you can disconnect the HDMI monitor. Everything’s now
done through the PiTFT (or remote login via SSH).
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 15 of 22
Tuning & Tweaking
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):
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 16 of 22
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 and color to help…
sudo nano /etc/emulationstation/themes/simple/simple.xml
Scroll down to the “gamelist” section and change the value of primaryColor to 000000 and
fontSize to 0.05.
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 17 of 22
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 (http://adafru.it/elu) and EmulationStation (http://adafru.it/eHv) 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.
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 18 of 22
Adding Controls
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!
This can be downloaded from the command line:
cd
git clone https://github.com/adafruit/Adafruit-Retrogame
cd Adafruit-Retrogame
Edit the file retrogame.c, looking for the table called ioStandard (not the ioTFT table — that’s for
other projects). Each line in brackets represents one pin on the GPIO header and a corresponding
key code.
The full list of available keycodes can be found in /usr/include/linux/input.h
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 19 of 22
The numbers in this table represent the GPIO number (see map below), not the position of the pin
along the header.
The top of the following diagram (the 3.3V and 5V pins) is at the end of the board closest to the SD
card slot; 5V along the outer row of pins, 3.3V along the inner row.
You’ll need to be careful in your GPIO pin selection…some are used by the PiTFT display, others
have certain reserved functions. Any green GPIO pin is free to use…yellow pins may be okay with
additional setup. If you’ve configured a tactile button on the PiTFT for shutdown, that pin is
unavailable for game controls.
One wire from each button connects to a GPIO pin, while the other wire connects to an available
ground pin (GND). The 2.8" PiTFT boards have an extra header breakout for the first 26 pins…for
the remaining pins, you’ll need to get clever with female jumper wires on the exposed part of the
Raspberry Pi GPIO header.
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 20 of 22
After editing, compile and install the code with:
make retrogame
sudo mv retrogame /usr/local/bin
To make retrogame start automatically when the system boots:
sudo nano /etc/rc.local
Before the final “exit 0” line, insert this one line:
/usr/local/bin/retrogame &
Just one more file needs editing, so that EmulationStation recognizes retrogame as a keyboard:
© Adafruit Industries
https://learn.adafruit.com/running-opengl-based-games-andemulators-on-adafruit-pitft-displays
Page 21 of 22
sudo nano /etc/udev/rules.d/10-retrogame.rules
Copy and paste this line exactly into the new file:
SUBSYSTEM=="input", ATTRS{name}=="retrogame", ENV{ID_INPUT_KEYBOARD}="1"
Reboot and you should now have “virtual” keys associated with GPIO buttons.
© Adafruit Industries
Last Updated: 2015-03-12 03:45:06 PM EDT
Page 22 of 22