Before assembling anything, let’s get some software installed and tested on the Raspberry Pi board. Doing this early (rather than when everything’s buried inside a case) makes troubleshooting easier.

SD Card Setup

Start by downloading an SD card image for RetroPie, a nice game emulation package. You’ll find this on the RetroPie download page. Note there are two versions:

  • One version for single-core Raspberry Pi boards like the Pi Zero or Pi 1 B+.
  • Another for multi-core boards like the Pi 2 and 3.

Download the correct one for your chosen Cupcade hardware…they are not cross-compatible.

After downloading you’ll need to “burn” this software to a microSD card. We really like Etcher for this purpose.

While that’s downloading and burning, let’s get some things together…

  • During setup, the Raspberry Pi will be connected to an HDMI monitor. You’ll need a cable for that. Pi Zero boards require a mini HDMI cable. Once everything’s working, the monitor and cable are no longer needed.
  • You will also need a USB keyboard during setup. Again the Pi Zero presents a special situation…you’ll probably need an “on the go” adapter cable for this.
  • The Pi will need to be connected to the internet. This is easiest on the Pi 2 and 3 if you have an Ethernet drop. Otherwise, WiFi is an option, though there are some gotchas. A Pi 2 or Pi 1 B+ needs a USB WiFi adapter. Pi 3 and Pi Zero W have built-in WiFi, but only for 2.4 GHz networks. Another Pi Zero option is called an “Ethernet gadget” over USB, explained in this guide.

While you can type all the installation commands that will follow. It’s vastly easier if you have ssh enabled on the Pi and a terminal program that handles ssh remote logins. Then you can copy-and-paste commands from this guide to the terminal window.

Depending on your Etcher preferences, it may automatically unmount the SD card filesystem after writing, in which case remove the card and re-insert it in the card reader.

You should see a small WIN32 filesystem called “boot”. Create a new file called “ssh” in the root level of this disk — this can be created with a text editor, or just copy any small file there and rename it “ssh”. Then unmount the card and insert it in the Pi.

First Boot

The extra parts (PiTFT, joystick, etc.) should NOT be connected yet. Just the Pi, USB keyboard and HDMI monitor  (and a network adapter, if your Pi needs it).

When power is first connected, the Pi will go through a quick boot and re-boot as it expands the filesystem to make use of the full SD card. Then you’ll see the RetroPie splash screen and after about a minute this welcome screen:

We need to set up the system to accept keyboard input for navigating the RetroPie menus. Later we’ll make this work with the Cupcade controls, but for now we need keyboard control…

Hold down any key for a few seconds so the system acknowledges the keyboard for input, then you’ll get to a configuration screen starting with the D-pad directions. Tap a key corresponding to the control that’s highlighted.

Here’s the recommended key mapping for Cupcade:

RetroPie Control/Button


D-pad Up

Up arrow

D-pad Down

Down arrow

D-pad Left

Left arrow

D-pad Right

Right arrow





“A” Button

Left “Control” key

“B” Button

Left “Alt” key

Keep track of what you set up here, because you’ll need to use these keys later for navigating menus.

You’ll be prompted for about a dozen more controls (“X” and “Y” buttons and so forth), but none of these are necessary for navigating RetroPie menus nor does the Cupcade cabinet we’ll build later have enough buttons for all these. So…for everything after the “B” button, just hold down any key on the keyboard for a couple seconds, until the Configuration screen says “Not Defined” and skips ahead to the next item. Repeat this through the whole end of the list. At the end you’ll be asked about an undefined hotkey enable button. Just select the default “Yes” here — meaning you’ll press the Start+Select buttons together to exit a game and return to the RetroPie menus. (You click “Yes” by pressing the “A” button you set up during this process — e.g. left Control key in the example key mapping above.)

Enable WiFi (if needed)

Now that the controls are enabled, you can access RetroPie menus to set up WiFi (if using wired Ethernet, you can skip ahead to “Download and Install…” below).

With no games installed on the card yet (more on that later), the only RetroPie menu option should be “Configuration.” (If not, move left or right until that item’s active), then press your “A” button (e.g. left Control key) to select it.

Highlight the “WiFi” option at the bottom of this list and press the A button again. This runs a WiFi configuration utility, which is all text-based…so this works with the keyboard’s arrow keys, tab and enter keys to select menu items, and when asked for the network password just use the keyboard as normal.

When finished, WiFi networking should be enabled. If not, you might need a reboot. Press the B button (e.g. left Alt key) to exit the Configuration menu, then from the main RetroPie screen press the Start button (e.g. 1 key), navigate down to “Quit” and restart the system.

Gen 1 & 2 Cupcade users: there’s also an option in the RetroPie menu to run the raspi-config program, which includes an option for overclocking…very helpful on these early Pi systems. Most can handle the “Medium” overclock setting with no ill effects. Gen 3 Cupcades don’t require this…newer Pi boards already use dynamic overclocking automatically.

Download and Install Cupcade Software

With networking enabled on the Pi (either WiFi or Ethernet), now we can install the extra software bits to support the Cupcade hardware. There’s two ways to do this…

One option is to type commands directly on the Pi. From the RetroPie main screen, press “F4” to exit the GUI and get a command line prompt. From here, you could test the network connection by typing:


(Press Control+C to exit)

Or, if you didn’t already set up ssh as explained in the “SD Card Setup” section of this page, you could type:

sudo raspi-config

In the “Interfacing Options” menu you’ll find an option to enable ssh, then use the second option…

Second option, generally better, is to log in remotely using an ssh-capable terminal program and copy-and-paste later commands directly from this web page into the terminal window. Some of the commands are cryptic and very specific about spelling, so this is best.

The Pi system should appear on your network as retropie.local, e.g. from Linux or a Mac Terminal window you’d type:

ssh [email protected]

and enter the password for the pi user (“raspberry” by default).

If using a Windows system and it doesn’t recognize the “retropie.local” system on the network, you may need to install the Zeroconf software as explained in this guide.

To install software for the PiTFT display, enter the following lines exactly:

cd ~
sudo apt-get install -y git python3-pip
sudo pip3 install --upgrade adafruit-python-shell click
git clone
cd Raspberry-Pi-Installer-Scripts

If your cupcade display will be in horizontal (wider than taller) mode, enter:

sudo python3 --display=28r --rotation=90 --install-type=fbcp

If your cupcade display will be in vertical (wider than taller) mode, enter:

sudo python3 --display=28r --rotation=180 --install-type=fbcp

It will take several minutes to update your Pi software and install packages

After the script runs it will ask if you want to reboot. Since we have more things to install, select “no.”

Additional Steps for GEN 3 KITS ONLY

Skip these steps if building an earlier kit…different directions are provided below.

To install software for I2S audio used by Cupcade Gen 3, enter this line exactly:

curl -sS | bash

When asked if you want /dev/zero playback, say N(retropie does this already)


This script does its job quickly. At the end it will ask whether to test the speaker, answer “no” since we haven’t assembled any hardware yet.

Finally, to enable the Arcade Bonnet’s joystick and button features, enter:

curl >
sudo bash

Note: copy-and-paste these as two separate commands. “Copy Code,” for whatever reason, causes the installer script to cancel.

You’ll be asked if you want to disable overscan. Yes! Disable overscan!


Install GPIO-halt utility? No.


This script takes a little longer to run. When it’s finished, you’ll be asked whether to reboot. Answer “no” again

Additional Steps for GEN 1 & 2 KITS ONLY

Skip these steps if building a Gen 3 kit…use the directions above.

Audio in these Cupcades requires no extra software, but does need a little volume adjustment. Type:


Press the up arrow until the volume level is at the maximum. Then press the Escape key to save and exit.

Joystick and button features rely on our retrogame software, installed with:

curl >
sudo bash

This script supports several Adafruit gaming projects, and you’ll see Cupcade among the listed options — select that one.

After the script runs it will ask if you want to reboot. Select “no.”

Last Steps for ALL Cupcade Versions

Now shut the system down manually:

sudo shutdown -h now

Give it about 20 seconds before disconnecting power (watch the status LED on the Pi board — when it makes a steady blink a few times and then turns off, it’s safe to disconnect).

The software’s all ready to test now, but we need to solder up a few bits first…

This guide was first published on Apr 04, 2014. It was last updated on Feb 21, 2014.

This page (Raspberry Pi Setup) was last updated on Mar 18, 2018.

Text editor powered by tinymce.