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 >
sudo bash

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:

/usr/local/bin/fbcp &

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

sudo nano /boot/config.txt

and comment out or delete these lines:

hdmi_cvt=320 240 60 1 0 0 0

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

This guide was first published on Mar 12, 2015. It was last updated on Mar 12, 2015.

This page (PiTFT Setup) was last updated on Mar 10, 2015.

Text editor powered by tinymce.