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:

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.

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…

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:

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

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

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

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:

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

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

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:

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

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:

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…