Skip to content

Instantly share code, notes, and snippets.

@eib

eib/0_README.md

Last active March 21, 2026 01:48
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save eib/c37629389a284c998cdb9a3878c2f467 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save eib/c37629389a284c998cdb9a3878c2f467 to your computer and use it in GitHub Desktop.
Download ZIP
Raspberry Pi Gaming Intro
Raw
0_README.md

Using a Raspberry Pi as a Retro Gaming Console

"Raspberry Pi"s are credit card-sized (or smaller) computers. Modern versions are powerful enough to emulate a bunch of gaming consoles. They're tiny, cheap, and energy efficient. They're also a great way to get started with other fun projects: home automation, media centers, robot cars, and more.

Potential Issues

Don't say I didn't warn you

The majority of my issues are actually with the OS. I have "some" experience with Linux, but I still bump into issues from time to time. Most end up being solvable, but might involve (at its worst) re-imaging your SD card ... after wasting N hours/days trying a bunch of commands you don't fully understsand. At best, you need to learn a little bit more about Linux each time you solve an issue.

The next cluster of issues is configuration: if you use RetroPie to kick-start EmulationStation front end, with RetroArch backends.... that's still a bunch of configs. Getting the controllers recognized, setup, and properly tuned (per game? per console?) is ... frustrating. It's gotten easier over time (software improvements) but not always easy.

Minimum Viable Product

  • a Raspberry Pi: my recommendation is RPi 5 (~4GB RAM) for greatest emulation options

    • RPi 5: handles N64 just fine, can barely emulate GameCube!
    • RPi 4B: can almost emulate Nintendo 64 (a dream for years)
    • RPi Zero (Zero, Zero W, Zero 2 W): can handle NES, SNES, and Genesis -- it's cheaper and even smaller. "Zero" is a bad choice: no wireless or bluetooth. "Zero W" (or "Zero 2 W") is a better choice since it comes with wireless and bluetooth built in.

  • Quality power supply: the RPi 5 wants a 5V/5A USB-C power supply; it will turn itself off otherwise. I usually buy an "officially-compatible" power supply at the same time I'm buying an RPi (specific to the new model). Check specific RPi model requirements: some are micro-USB, they have different Ampere requirements, etc.

  • microSD card: This holds the OS, the games, extra software, etc.

    • I recommend 32GB minimum, but usually bump into issues (depending on my usage).
    • ~200GB is usually perfect
    • I have a 1TB microSD card, but that's also my "media center" card (with all my movies, music, ROMs, etc)... not "cheap" and imaging takes forever.

  • Video cable: RPi 5 has micro-HDMI (older models have different video outputs, so check your model). I prefer a "micro-HDMI to HDMI" cable (less parts, but choose a length that works for your setup). You can also get a "micro-HDMI to HDMI" adapter is fine (plug into a regular HDMI cable) for starters.

  • "spare" mouse and keyboard:

    • I prefer to pre-configure my RPi OS to auto-connect to my home wifi network and automatically use my own SSH keys (so I don't need either if I always remote in from a separate laptop).
    • For beginners: you want a mouse and keyboard. You will need them for setup. You will want to slide a chair up beside the TV while you're figuring things out.

Operating System

You can pick the operating system! The Raspberry Pi Imager gives an easy way to pick your starter OS (compatible with your model). Or download a (compatible) image directly and flash it with Balena Etcher.

Most common choices:

  • Rasbpian (now called "Raspberry Pi OS"). Official/default OS. Based on Debian Linux.

    • Can come with or without a desktop.
    • I usually avoid the desktop because I remote in and use a custom "frontend" like EmulationStation (for gaming), Kodi (for media center), or moonraker (for 3D printing).

  • RetroPie: a popular OS for gaming. It comes with EmulationStation (front-end) and RetroArch (back-end). Based on Raspbian, but pre-configured for gaming. For example: comes with network shared folders for managing ROMs, BIOS, save files, etc. If you're gaming... I recommend this.

  • Moonraker/Klipper: if you 3D print, gives Klipper a look. I absolutely love it, but it takes work (tons of work) to get it fully configured. (Documentation incoming elsewhere...)

Emulators, ROMs, and BIOS

  • Emulators: these are software programs that emulate specific gaming console(s). These include consoles (NES, SNES, Genesis, N64, PlayStation, etc), arcade machines, specific games, and even DOS.

    • RetroPie gets you started with most of the common ones
    • You can add more (PPSSPP for PSP, Dolphin for GameCube/Wii, etc): If you want custom emulators, start with the software website (they'll usually have setup steps for RPis).

  • ROMs: the game files; akin to old game cartridges. Typically, you'll need to drop each file into the appropriate folder on the RPi and then re-scan the library or restart the RPi to be able to play it.

    • NOTE: There are "laws" and "ethics" over downloading ROMs you "don't own", but I've bought classic games on so many different platforms over the years it doesn't make sense to buy them yet again for the next version of PlayStation/Switch/Xbox/whatever. (My Wii ownership of Super Metroid purchased via Wii arcade died with that particular Wii; I "own" Chrono Trigger on Steam and PS4, but the original cartridge version is long gone; etc.)
    • If there was a legal way to buy the originals, support the original developers, and play them on a modern TV... I would do that (or already have).
    • That being said: you can find all the NES, all the Sega, all the SNES ROMs in archive.org (plus a few games from a few other consoles).
    • Sites like Vimm's Lair or EmuParadise can be used for one-off games (but they throttle downloads and sometimes the archives seem to be busted).
    • See also: myabandonware.com/

  • BIOS files are required for some "modern" consoles (PlayStation, XBox, etc). Think of them as "Operating System" files. These are not bundled with the game emulators (for "legal" reasons). You should own an existing console and then magically extract the appropriate BIOS files from it.

    • That being said: archive.org

Controllers

Notes:

  • I prefer wireless controllers (TV-to-couch distance), but wired controllers are fine.
  • New/young players might get confused if your "generic modern wifi controller" doesn't have the same exact button labels as is displayed in game (games might say "Press A for attack" or "Press square for reload").

My controllers:

  • NES: I have unbranded wireless NES-style controllers; they don't have the exact same feel as the originals, but they're better for playing NES games (hand angle changes if you're playing with a SNES-style controller).

  • SNES: wired iNNEXT controllers: OK. Very "classic" feel

  • PS4 DualShock 4: I can never remember how to put these into pairing mode, but they work great as Bluetooth controllers. You need a micro-USB cable to re-pair them with your PlayStation.

  • 8BitDo Pro 2 wireless: good. Essentially a PS1 controller. The extra handle/grip area is nice for longer gaming sessions

    • I think it came with (or I bought separately) an adapter to use this on the Switch; good, but it doesn't include the feature to turn on the console like the Switch controllers have

  • wireless Retro-Bit: same style "PS1" controller as 8BitDo, but SNES-shaped.

    • Not as comfortable as the 8BitDo (missing the handle area so my hand cramps).
    • Can probably play on a bunch of consoles
    • I usually end up swapping the trigger-vs-bumper buttons in the emulator configs, but I don't remember why off-hand.

  • original XBox: these are actually USB controllers -- with an extract (yellow, I think) wire and a custom plug. I've taken the breakaway cable and soldered/heat-shrink-wrapped a couple onto USB-A cables. Works great!

  • I own lots of adapters for original controllers (NES, SNES, and GameCube). Controllers with thumbsticks are often busted due to stick drift, though (thanks, Smash Bros!). But these aren't wireless, so I don't use them much to begin with.

  • various generic USB wired controllers: nothing to write home about. Typically used for Steam games.

  • you can try to configure your keyboard as a controller. Recommend against it -- I usually only try that for testing new games/systems.

RPi Cases

RPi cases aren't actually necessary. But useful for keeping things safe (from drooling kids/pets), may include a cooling fan or heat sink, or make it easier to carry around. Lots of room for "cool points".

  • If you start with the RPi500, the keyboard is the case (RPi and keyboard are both included). And it's a cool form factor for blowing peoples minds. (I got an RPi500 for one of my younger kids for Christmas: he only needs to carry the "keyboard" and a ontroller or two between upstairs/downstairs TVs and re-uses the HDMI and power cables already lying around.)

  • My first "official" case was built from spare legos: I left gaps in the walls for cables and SDCard, I added a "raspberry" lego logo on top, and used transparent legos beside the LEDs. 🤘

  • You can usually buy a case from the same place as the RPi; I don't usually grab those but you can sometimes find out-of-stock RPis in-stock as part of a "RPi starter kit". (YMMV)

  • You can also 3D print your own case. e.g. I've seen a couple of those with VESA mounts (to simply attach to the back of the TV).

  • MEGA BONUS POINTS: Look into "SNESPi" or "NESPi" for console-styled RPi cases. Check for RPi model compatibility. (I've think one of mine is RPi 4 and another is RPi 3 compatible.) Some come with extras like SSD expansion packs or cooling fans.

Initial Setup

Typically:

  • Plug SD card into computer (using slot or USB-adapter)
  • Use RPi Imager to select OS, configure "extras", and flash SD card
  • Insert SD card into RPi, connect video cable & keyboard, power it on
  • Run the Raspbian setup wizard to finish setup, restart a couple times, actually finish setup
  • SSH in and start downloading/copying over ROMs
  • Plug in a controller
  • Give it a go

Best-case: doesn't take much work.

Worst-case: ask me for help.

Raw
1_Raspbian_Setup.md

Raspbian Setup Initial Guide

NOTE: this was last checked for accuracy as of ~2018

Update packages

Linux package management commands -- you typically apt update before apt installing anything. Best practice is maintaining up-to-date packages (via apt upgrade).

You'll see package managers like apt, apt-get, yum, etc -- depending on the Linux distribution you're using.

# Download latest version metadata
sudo apt-get update
# Update installed packages
sudo apt-get upgrade
# Do a MAJOR software upgrade (do infrequently)
sudo apt-get dist-upgrade

Common Setup

These are expected configuration changes. These days, Raspberry Pi Imager can do many of these steps before booting up.

Expand file-system

sudo raspi-config # Top-level "Expand Filesystem"

Change locale and fix keyboard

sudo raspi-config # "Localisation Options" > "Change Locale" > uncheck "en_GB.whatever", check "en_US.UTF-8"

Sanity check:

sudo nano /etc/default/locale # Expecting LANG=en_US.UTF-8
sudo reboot

Change keyboard:

sudo raspi-config # "Localisation Options" > "Change Keyboard"
echo "export LC_ALL=C" >> ~/.bashrc # I had some locale trouble, so I added this. (Rebooting might have fixed it, instead.)

Sanity checks:

sudo nano /etc/default/keyboard # Expecting XKBMODEL="pc104" and XKBLAYOUT="us"
sudo reboot

SSH auto-login

Append your thumbprint to ~/.ssh/authorized_keys

mkdir ~/.ssh
touch ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Install screen

sudo apt-get install screen

Configuring Wifi

  • Easiest to setup via Raspberry Pi Imager
  • If you have the Desktop OS, use the Settings app
  • Otherwise.... check the docs
Raw
2_EmulationStation_Setup.md

EmulationState setup

NOTE: this was last checked for accuracy as of ~2022

EmulationStation Configuration

Inside Emulation Station...

  • EmulationStation: configure a controller
  • EmulationStation: configure a keyboard:
    • D-pad = arrow keys
    • Start = Esc
    • Select = Tab
    • A = Enter
    • B = Space
  • Wifi
  • Runcommand:
    • Launch menu: Disabled
    • Launch menu art: Enabled

Updates

From command-line:

  • sudo apt update -y # for errors: "InRelease' changed its 'Suite' value from 'testing' to 'stable'"
  • sudo apt-get update
  • sudo apt-get dist-upgrade

Raspi-config

raspi-config...

  • Advanced Options:
    • Expand Filesystem
    • Memory split: not necessary (per docs)
    • Resolution: try 720p-1080p @ 60Hz, since some games have issues with 30Hz (default for 4K displays)
    • Audio: force either HDMI or 3.5mm jack, if necessary
  • Localisation Options...
    • Change Locale: en_US.UTF-8
    • Change Timezone: Pacific
    • Change Keyboard Layout: pc104 / US
    • Change Wi-fi Country: US
  • Change Network Options...
    • Hostname: something unique
  • Interfacing Options...
    • SSH (enable)

RetroPie

Run sudo ~/RetroPie-Setup/retropie_setup.sh (can be done from inside ES)

  • Configuration / tools > samba > Enable samba
  • esthemes > pick a custom theme (Carbon/Simple Dark/etc)

Misc

  • Configure SSH keys (password-less SSH)
  • Install SafeShutdown scripts
  • Copy ROMs via \\<ip address>\roms
  • Use sselph scraper
    • RetroPie-Setup > Manage packages > Manage optional packages > scraper
    • Install
    • Then configure...
      • Thumbnails only: Disabled
      • Prefer screenshots: Disabled
      • Download Videos: Enabled??
      • Download Marquees: Enabled??
      • Max image width: 1000?
      • Max image height: 1000?
  • [Optional] Configure rclone_script to backup savefiles:
    • Had to generate rclone config via desktop, then copy to remote
      • Use rclone config file to find output filename(s)
    • Retry if "Compile PNGVIEW" step fails
    • Chose destination dir Personal/Games/Saves/$hostname
    • ... Enables \\<address>\saves SAMBA share (at ~/RetroPie/saves/)
    • Re-configures systems to use new savefile directory
    • Copy previous saves (*.srm, *.state*) from ~/RetroPie/roms/$SYS/ to ~/RetroPie/saves/$SYS/
      • for SYS in nes snes gba; do echo $SYS; cp roms/$SYS/*.srm roms/$SYS/*.state* saves/$SYS/; done
    • In EmulationStation, go to "RetroPie > RCLONE_SCRIPT > Full Synchronization" to upload pre-existing savefiles/savestates.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment