The RetroPie FAQ that I wish had existed when I started down this road

Inspired by Nintendo’s upcoming NES Classic Edition, I spent some time last week setting up a Raspberry Pi-based emulation station.

For about $100 all-in, this smaller-than-my-wallet computer plays thousands of games from the Atari 2600 all the way through the PlayStation 1/N64 era, and just about everything in-between.

I’m very happy. My kids like it too, which I never thought would happen.

Despite its claims of being “easy to use” and “wonderful”, RetroPie is definitely not those things out-of-the-box. Once you’re up and running, things are great! It’s the setup that’s the problem.

I spent a few hours tracking down solutions to quirky problems, and these were the big ones. I hope this helps somebody! I’ll be adding to this as I run into other cases of dumb stuff.

---

[expand title=”I’m getting a black border on the screen or things are disappearing off the edges!“]

This one seems like an easy fix! Just override the Raspberry Pi’s default overscan settings, right? They’re in /boot/config.txt.

So you set values for overscan_left, overscan_right, etc in there. That’s great. It works!

…for the command line only. Once you launch anything that uses more than text mode, you’re back to square one.

To fix:
Add in a newish, not-very-well-documented variable to /boot/config.txt: overscan_scale=1. THEN work on those overscan settings to get a perfect fit on your screen. Try new values, save, “sudo reboot“, and repeat until you’ve got it perfect.

On my Samsung, the ideal values were -9, -9, -25, -25 (LRTB) but yours could be anything!
[/expand]

[expand title=”My controller works in the Emulation Station launcher, but partially (or not at all) within emulators.“]
If your controller is physically connected or is Bluetooth paired (and wirelessly connected) the issue is improperly mapped joypad buttons. The good news is it’s not your fault.

Pair and connect your controller with Bluetooth from the Bluetooth menu.

Now configure its buttons within Emulation Station.

This does two things – it lets you control Emulation Station with this controller, and also sets up a default config for the Retroarch emulators (within /opt/retropie/configs/all/retroarch-joypads/), so your controller should work automatically in all of them.

Except this second part? It often screws it up pretty badly. Some controllers get set up fine, and some are all kinds of wrong. The Emulation Station setup process will assign buttons that don’t even exist on the controllers to their profiles within Retroarch emulators. What that means is that some (or none) of the buttons will work within emulators.

To fix:
open up /opt/retropie/configs/all/retroarch-joypads
Find the name of the joypad you want to fix, and edit its .cfg file. (Remember, these CFGs aren’t created until you first set them up within Emulation Station. Just pairing with Bluetooth isn’t enough.)

Every action in the cfg is assigned to a button. Every button on the controller has a number. Most or all of these numbers are probably wrong in this cfg if you’re having trouble.

To find out the correct button numbers, run
jstest /dev/input/js0
(or js1 for player 2, etc)
Tap every button and write down their values. Then control-C outta there, and put the proper ones in your cfg file.

I’ve got two controllers (from the excellent 8Bitdo) and I had to do this for both of them. Feel free to steal these configs:

[expandsub1 title=”8BitdoNES30Pro.cfg“]
input_device = “8Bitdo NES30 Pro”
input_driver = “udev”
input_up_btn = “h0up”
input_left_btn = “h0left”
input_right_btn = “h0right”
input_down_btn = “h0down”
input_select_btn = “10”
input_start_btn = “11”
input_l_y_plus_axis = “+1”
input_l_y_minus_axis = “-1”
input_l_x_plus_axis = “+0”
input_l_x_minus_axis = “-0”
input_r_y_plus_axis = “+3”
input_r_y_minus_axis = “-3”
input_r_x_plus_axis = “+2”
input_r_x_minus_axis = “-2”
input_l_btn = “6”
input_l2_btn = “8”
input_l3_btn = “13”
input_r_btn = “7”
input_r2_btn = “9”
input_r3_btn = “14”
input_a_btn = “0”
input_b_btn = “1”
input_x_btn = “3”
input_y_btn = “4”
input_enable_hotkey_btn = “10”
input_state_slot_increase_btn = “h0right”
input_state_slot_decrease_btn = “h0left”
input_save_state_btn = “7”
input_load_state_btn = “6”
input_menu_toggle_btn = “3”
input_reset_btn = “1”
input_exit_emulator_btn = “11”
[/expandsub1]

[expandsub1 title=”8BitdoSNES30GamePad.cfg“]
input_device = “8Bitdo SNES30 GamePad”
input_driver = “udev”
input_up_axis = “-1”
input_left_axis = “-0”
input_right_axis = “+0”
input_down_axis = “+1”
input_select_btn = “10”
input_start_btn = “11”
input_l_btn = “6”
input_r_btn = “7”
input_a_btn = “0”
input_b_btn = “1”
input_x_btn = “3”
input_y_btn = “4”
input_enable_hotkey_btn = “10”
input_state_slot_increase_axis = “+0”
input_state_slot_decrease_axis = “-0”
input_save_state_btn = “7”
input_load_state_btn = “6”
input_menu_toggle_btn = “3”
input_reset_btn = “1”
input_exit_emulator_btn = “11”
[/expandsub1]

[/expand]

[expand title=”My analog sticks work great in everything, but I can’t get PSX to recognize them.“]
This one made no sense. The stick worked fine with N64 titles with no extra configuration. When it came to PlayStation titles, I’d change the RGUI controller setting to “RetroPad w/ Analog” for P1 and it made no difference. That setting doesn’t do anything at all. Don’t even bother changing it.

To fix:
Launch a PSX game. Open up the RGUI menu using your hotkey.

Go to Options / Core Options / Pad 1 Type (and/or Pad 2) / Change Digital to Analog

Games will think you’ve got an old-school, digital-only, stickless pre-1998 controller attached by default until you switch this to analog. That option is the equivalent of toggling the recessed “analog” button on a real PS1 Dual Shock controller.

A little more backstory on why this is appears here.
[/expand]

[expand title=”I have no freaking idea how to connect more than one controller.“]
There’s no explicit documentation on how to do this. But it’s pretty easy.

To fix:
Once you’ve configured your first controller, go into Emulation Station’s settings to configure your controls. It’ll say something like “configure second gamepad,” so hold down a button on that second gamepad to get it recognized. Go through the whole process and you’ll be all set for controlling the UI with all your controllers.

Of course once you get into an emulator you’ll probably have button issues. You’d then just need to do what we did in the last step to properly map those buttons in a .cfg file.
[/expand]

[expand title=”Atari Lynx roms won’t launch!“]

I’d select a game, get a black screen, then be taken back to the EmulationStation Lynx menu. /tmp/runcommand.log would tell me all of my roms were invalid, and they would not boot at all. This wasn’t a BIOS issue.

I was using no-intro Lynx roms. These “clean” roms do NOT have a header, and the version of lr-handy included with the 4.0 beta would not play them because of that.

Here’s the problem – the lr-handy binary that comes with 4.0 (beta2) is way old. Newer Handy releases are able to work with “no header” roms.

To fix:

Go into the RetroPie setup script menus, and rebuild lr-handy from source. It takes a few minutes to complete. When it’s done, you’re golden.
[/expand]

[expand title=”I’m from America! I want Mega Drive to be Genesis and PC Engine to be TurboGrafx-16!“]
I feel your pain. In theory it’s a simple text fix within /etc/emulationstation/es_systems.cfg. Just find the ‘theme’ field where you see ‘megadrive’ and change it to ‘genesis’. Wouldn’t hurt to change the ‘fullname’ and ‘platform’ fields, too.

The problem here is that not every theme supports all systems. Some only support views for ‘megadrive’, and will only show a shitty unstyled menu if you pick something they don’t support.

To fix:
Good luck with that. Just stick with the original names.
[/expand]

[expand title=”Why are there two included scrapers? Why does it take so damned long?“]
Emulation Station needs two things to look its best: boxart for each game, and a ‘gamelist.xml’ full of metadata for each system. ES has a built-in-scraper, but that uses your roms’ filenames to identify them. That method can be pretty unpredictable.

It’s a better idea to use the included “Steven Selph” scraper in the Retropie textual menus, as it uses rom hashes to provide much more accurate results.

But it takes forever.

To fix:
Note that you can’t use the Selph scraper if Emulation Station is open, or its work will be overwritten. Quit from ES before scraping (If you’re logged in remotely: “killall emulationstation“) then get busy:
sudo ~/RetroPie-Setup/retropie_setup.sh
setup/tools
scraper

The scraper will first download all your images in one big queue, and you can watch as things happen in the terminal. This takes about five minutes. Then, at the end of your queue, everything will freeze…or will appear to. For HOURS. Don’t break out of it. Let it sit and ‘do nothing’. Even though there is no visual feedback, the current system’s gamelist.xml is being generated. A recent scrape of ~120 Genesis roms took about three fucking hours, conservatively.

The only setting I’d really change from the defaults is to disable “Thumbnails Only”. When I left that enabled I ended up with a bunch of low-res blurry upscales.

I agree, this slow scraping thing sucks because it’s probably one of the first things you’ll do when you set up your RetroPie install, and during this whole time you can’t play anything. Let it run overnight.

As nice as it is to look at and use, Emulation Station seems to have been abandoned by its author with no updates in over a year. The reliance on huge, slow-to-process XML files was one of the things he had hoped to have fixed before he eventually lost interest in the project. This might get fixed someday, but for now it’s best to limit your romsets to a couple hundred, rather than a couple thousand, just to keep EmulationStation running smoothly.
[/expand]

[expand title=”I don’t like my Raspberry Pi case. What’s the best one you’ve found?“]
I don’t have it, but it’s clearly this one:

It’s 3d printed, so you’ll have to put up with those telltale print lines, but heee-ooo! What a beaut. You can have the parts printed for about $30, but I think you then need to paint it in the correct colors.
[/expand]

[expand title=”When I select a rom, the screen goes dark and I get spit back to the menu.“]
Could be anything.

To fix:
Check /tmp/runcommand.log to see what happened.

Most times the log will tell you that you’ve got invalid/corrupt roms. Unzip them and they will work fine. I have no idea why.

PlayStation images in particular suffer from this. The non-libretro version of the N64 emulator can’t open zipped roms, period. There’s no clear idea as to when this will get fixed (or if anyone’s even working to fix it,) so it makes sense to invest in a large SD card for this reason alone.

If the log is totally empty, you’re probably missing the proper bios files in the bios dir.
[/expand]

---

Anyhoo

I think that’s it. Everything else I ran into was covered in the official wiki, the forums, or on the RetroPie subreddit.

I’m kind of amazed that a $35 Raspberry Pi 3 has enough horsepower to handle PS1 and N64 games. A small-form-factor Windows HTPC that I built just two years ago (for considerably more money) can barely handle either one of those. Now’s a good time to get into this stuff!