📅 February 15, 2016
With hardware and basic EmulationStation configuration complete, we are ready for further adjustments.
- EmulationStation and RetroArch Controls
- RetroArch Controller Configuration
- Dual Shock 4 Controller Configuration File
- Sony Computer Entertainment Wireless Controller.cfg Listing
- Confusing Four Buttons
- Analog Buttons, Touchpad, and the PS Button
- Share / Options
- Mapping HotKeys
- RetroArch Configuration
- Video Settings
- Configuring Individual Games
- Setting Render Resolution
- Setting Core-Specific Options
- Saving the Button Mapping
- Digital to Analog Stick
- Saving/Loading State
- Scraping Game Metadata
- Manually Editing Metadata
- System-Specific retroarch.cfg
- Editing es_systems.cfg
- Important Files and Directories
- Shutting Down RetroPie
- More Information
EmulationStation and RetroArch Controls
EmulationStation and RetroArch are two separate programs. EmulationStation does not play games. It only allows you to select them. Once you pick a game you want to play, control passes to RetroArch (or a standalone emulator), which starts the actual playing.
These two programs require individual controller set up. The controller setup first performed by EmulationStation only affects EmulationStation. RetroPie 3.5 tries to duplicate the EmulationStation controller settings to RetroArch for you automatically, but I have found that it is not perfect. RetroArch still needs its own fine-tuning.
RetroArch Controller Configuration
A keyboard is recommended, so be sure to connect a USB keyboard to the Pi since we will be configuring RetroPie locally, not remotely through SSH.
In EmulationStation, go to the Retropie menu and choose “Configure RetroArch / Launch RetroArch RGUI.”
This launches RetroArch without a game so you can configure the general settings that apply to all emulator cores.
Any settings made are saved in /opt/retropie/config/all/retroarch.cfg. The settings here are applied to all cores, which, in addition, can have have their own settings that override these.
To configure the controller, select “Settings.”
This opens the Input menu where controller configuration is made. The settings we make here will apply to the RetroArch menu. Yes, RetroArch will try to apply the same controller mapping to the various emulator cores, but a single controller mapping feels awkward across various emulators that are based upon systems with different controllers. I would recommend thinking of this as the “RetroArch Menu Mapping” for now. We can assign different mappings to individual emulator cores later.
Go to “Input User 1 Binds.”
This is the menu where you map controller buttons to specific functions. To get started, choose “User 1 Bind All.” Press a controller button at each prompt that appears to map a button to a specific function.
On the Dual Shock 4 controller, lightly–LIGHTLY— press the L2 and R2 trigger buttons or else they will double map or skip. If you make a mistake, you can always re-run the button mapping.
Map the buttons so that their actions match those of EmulationStation as much as possible. For example, if the DS4 X button means “Select” and Square button means “Back” in EmulationStation, then use X and Square for Select and Back in RetroArch as well. This is for consistency. It makes it easier to navigate RetroArch and EmulationStation without having to rethink different button mappings for both programs.
Dual Shock 4 Controller Configuration File
A special configuration file associates button numbers with their intended functions. Each type of controller connected should have its own configuration file located in /opt/retropie/configs/all/retroarch-joypads. This file is created automatically. For the Dual Shock 4, this file is,
/opt/retropie/configs/all/retroarch-joypads/Sony Computer Entertainment Wireless Controller.cfg
If you need to find out “What is the button number for L3?” then looking at this file will help. You will see input_l3_btn = “10” that says, “the DS4 L3 button is identified as button 10.” In RetroArch, you would then use the value “10” to specify to map L3 to a function.
Sony Computer Entertainment Wireless Controller.cfg Listing
Here is what the DS4 controller configuration file looks like. The L3 button, identified as input_l3_btn is assigned the value 10. RetroArch then uses input_l3_btn.
input_driver = "udev" input_device = "Sony Computer Entertainment Wireless Controller" input_vendor_id = "1356" input_product_id = "1476" input_b_btn = "0" input_y_btn = "3" input_select_btn = "8" input_start_btn = "9" input_up_btn = "h0up" input_down_btn = "h0down" input_left_btn = "h0left" input_right_btn = "h0right" input_a_btn = "1" input_x_btn = "2" input_l_btn = "4" input_r_btn = "5" input_l2_btn = "6" input_r2_btn = "7" input_l3_btn = "10" input_r3_btn = "11" input_l_x_plus_axis = "+0" input_l_x_minus_axis = "-0" input_l_y_plus_axis = "+1" input_l_y_minus_axis = "-1" input_r_x_plus_axis = "+2" input_r_x_minus_axis = "-2" input_r_y_plus_axis = "+5" input_r_y_minus_axis = "-5"
Here is an image showing the DS4 button numbers.
Confusing Four Buttons
The X, O, Square, and Triangle buttons can be confusing to map because they are referred to as buttons A, Y, Triangle, and Square by RetroArch.
DS4 RetroArch --------------------------------- X A (input_a_btn = "1") O X (input_y_btn = "2") Square B (input_b_btn = "0") Triangle Y (input_x_btn = "3")
This is confusing when RetroArch prompts for the X button. RetroArch is not referring to the bottom “X” button on the DS4 controller. RetroArch has its own version of an X button located in a different location.
During the binding prompts, RetroArch will hint at the intended button with “top,” “bottom,” “left,” and “right.” However, you are always free to map the buttons to your preference, so experiment with what is best for you. I have foudn that the default mapping as RetroArch intends does not always match the mapping previously set by EmulationStation, so inconsistencies can arise.
Analog Buttons, Touchpad, and the PS Button
Both analog sticks function properly. However, the touch pad is nothing more than a single, big button (useful for opening the RetroArch menu if mapped to do so), and the L2 and R2 triggers only act as buttons. You cannot use the motion movements of the touchpad or the analog features of the trigger buttons.
The PS button is an extra button to use as you see fit.
Share / Options
These buttons on the DS4 are mapped to select and start and behave like any other buttons.
RetroArch supports hotkeys. This allows button press combinations in order to activate RetroArch features. You hold one button set as the hotkey button on the controller, and then press a secondary button simultaneously.
For example, if L1 is mapped as the hotkey button for RetroArch and the Start/Options button is set to quit RetroArch, then pressing L1 + Options will quit and close Retroarch instantly. However, pressing Options by itself will not terminate the program.
This is useful because it avoids accidentally closing RetroArch…something that is easy to do during high-intensity, button-mashing games.
To map a hotkey, select “Input Hotkey Binds” from the Input menu in RetroArch. Then, select the “Enable Hotkeys” options to set a button.
Many of the existing mappings require a keyboard, but controllers are allowed as a secondary input.
You can map a number of functions to hotkeys, but here are two essentials:
You need a way to open the RetroArch menu in order to perform functions and configure the a game. In the Input Hotkey Binds menu, map a button to “Menu toggle.” The touchpad is a good choice if used without hotkeys.
You also want a way to exit RetroArch and return to EmulationStation without resetting the Raspberry Pi. In the same hotkey bind menu, assign a controller button to “Quit RetroArch.”
With the PS button mapped as the hotkey button, for example, we would have:
PS + Touchpad Open RetroArch Menu PS + Options Quit RetroArch
Choose an unaccidental hotkey combination in order to close RetroArch in order to prevent accidental exits.
Note that if you use a different controller with RetroArch, then you might need to reassign buttons if the new controller is not identical to your previous button mappings. For example, if you use the PS button as the hotkey and then plug in a controller lacking the PS button, then hotkeys will not work until the buttons are remapped.
From the RetroArch Settings menu, co to the Configuration menu. We want to enable all of these settings, so set them to ON.
This performs features such as saving the RetroArch configuration when RetroArch exits. You want this…unless you want to reconfigure everything each time you run a game.
Other features, like “Configuration Per-Core” and “Use per-game core options if available” will allow you individually configure games and cores — something that provides fine-tuning for games.
Also, make sure RetroArch is set to load the override and remap files. These files allow remapping of the controller layout, which is needed many times for various systems and games.
From the RetroArch Settings menu, select Video. There are five settings here that improve the video output.
Aspect Ratio Index
If using a widescreen 16:9 display, set this to 16:9. This tells RetroArch what aspect ratio to use. It does not have to match your display, but the option is here.
Custom Viewport Width/Height
Set this to match your display’s native resolution. It is usually faster to edit this setting in /opt/retropie/configs/all/retroarch.cfg. For an HDTV that supports 1080, use 1920×1080.
I cannot notice any different with this, so I set it to 1.0x.
You might need to set this to OFF in order to adjust the resolution to 1920×1080.
HW Bilinear Filtering
This tries to make pixels appear smoother. If you prefer sharp pixel edges, then set this to OFF.
There are many, many settings for RetroArch, but this should be enough to get you started. You can always return to the RetroArch configuration anytime during a game or from EmulationStation to make further adjustments. For now, exit RetroArch either with the hotkey binding or through the RetroArch menu.
Configuring Individual Games
When you load a game to play, a short message will display. This gives you a chance to make changes for the individual game or the current Libretro core running the game.
Press a button on the controller, and you will see a new menu.
While you can navigate using the controller, a keyboard is easier. The numbers and letters to the left of each menu item are keyboard shortcuts.
Setting Render Resolution
By default, most cores render at 640×480. If you ever wonder why the picture seems blurry even though you set 1920×1080 in RetroArch for an HDTV, this is why. You must change the render resolution to match the native resolution of your display.
Choose “8 Select RetroArch render res for xyz (640×480).” “xyz” will be the name of the current core. The (640×480) is the current resolution, and this is why the screen appears blurry. On the next menu, select “5 Use video output resolution.”
Upon returning to the previous menu, you will see that (640×480) has changed to (output).
RetroArch will render at the video output resolution. In most cases, this will be the same as the display’s native resolution. Choose “Launch” to play the game at the new resolution.
You must do this for each emulated system, not each game. Changes made to one core will not affect another core. However, this is usually a one-time setup. RetroArch will save the new resolution change and use it each time you play using that core.
Setting Core-Specific Options
When the game is playing, go to the RetroArch menu by pressing the hotkey assignment on the controller (suppose it is PS + Touchad in this case). Go to the RetroArch Main Menu, and choose “Quick Menu.”
The Quick Menu appears.
There are two important settings in the Quick Menu: Core Options and Core Input Options.
Core Options is for core-specific settings that apply to the system being emulated. What appears here can vary by the core. Some cores have no options, so it will be empty.
Core Input Options allows you to remap controller buttons to those of the emulated system. Each emulator core is different, so this is extremely useful.
These setting will not override the RetroArch Menu input settings. They are specific to the core, not RetroArch as a whole.
On the left side of the menu is a listing of system-specific button names, such as “User 1 2,” and “User 1 Up.” These are the names of the buttons as found on the original system.
On the right side of the menu is the corresponding list of RetroPad controller names. You want to map the DS4 buttons to the emulated system buttons to your liking by highlighting the line and then pressing left and right on the controller to cycle through possible buttons.
The tricky part is figuring out which DS4 button is “RetroPad A Button,” for example, so consult the Dual Shock 4 button mapping image above or the DS4 config file in /opt/retropie/configs/all/retroarch-joypads if needed.
RetroArch will try to map default buttons automatically, but this can be inaccurate for the given core.
Saving the Button Mapping
You can save the new button mapping per game or for the entire core. The next time you play the same game, the new button mappings will be loaded. This saves the trouble of remapping each time you wish to play a specific game.
Choose “Save Core Remap File” to save the button mapping for the entire core. Choose “Save Game Remap File” to save the button mapping for the individual game. Loading a different game will use the core’s default mapping, not this one.
In practice, I find little difference between these two save options, so I save them both. You can even load a specific remap file.
Digital to Analog Stick
If your controller has an used analog stick (not mapped to anything for the core), you can map the digital directional buttons to a stick by choosing “User 1 Analog To Digital Type” and setting it to Left Analog, Right Analog, or None (default). This allows you to use either the digital D-pad or the analog stick for control.
Make sure to save your changes.
RetroArch lets you save and reload anywhere by using saves states. From the Quick Menu, choose a State Slot (0 is default), and then choose “Save State.” The entire emulation state is saved, and you can reload that point anytime until overwritten by another state.
Press the hotkey combination to return to the game.
Scraping Game Metadata
By default, EmulationStation shows a list of game titles similar to this:
You can add cover art and information about the game to make viewing them more fun and to provide information. This information is obtained from web sites on the Internet.
Go to the EmulationStation Main Menu.
Then, choose “Scrape Now.”
You can choose which systems to scrape data and whether to intervene or not upon conflicts or duplicate names.
It is also possible to scrape metadata for individual games instead of all games per system. You might need to do this to get specific information on a game with a confusing title.
Highlight the game and go to the Options Menu for the game.
Choose “Edit This Game’s Metadata.”
Choose the “Scrape” button. EmulationStation looks for game information based upon the given name. However, this is spotty and will not work if the name varies even slightly from the name stored in the database of the web site. you will need to use a keyboard to manually input the game’s name. Choose the correct game from the menu.
The default scraping works, but it needs improvement. Other scrapers can be installed from RetroPie Setup.
Manually Editing Metadata
If the web site is down or unresponsive, then EmulationStation will hang. Scraping is a slow, unreliable endeavor that largely depends upon filenames will certain names, but you can edit metadata manually and provide your own images.
The directory /opt/retropie/configs/all/emulationstation/downloaded_images stores downloaded images used for cover art. Each system has its own directory. Then, /opt/retropie/configs/all/emulationstation/gamelists stores metadata text in gamelist.xml. Each system has a unique gamelist.xml file in its own directory.
A gamelist.xml file is an .XML file that can be edited in any text editor. You will need to restart EmulationStation to see any changes made.
The general format looks like this:
<?xml version="1.0"?> <gameList> <game> <path>./Robotron 2084 (1983) (Atari)/Robotron 2084 (1983) (Atari).bin</path> <name>Robotron: 2084</name> <desc>You are a mutant human, who by some freak of nature has the ability to shoot energy pulses from his body in eight different directions! Your job is simple: save humanity from their own creation -- the ROBOTRONS! The gameplay is pretty unique for the time. You can move and fire in any of eight directions. You get thrown in a room with various evil baddies strewn about, you've got to kill all the robots while at the same time finding some way to grab humans and avoid death.</desc> <image>/home/pi/.emulationstation/downloaded_images/atari5200/Robotron 2084 (1983) (Atari)-image.jpg</image> <developer>Williams</developer> <publisher>Atari</publisher> <genre></genre> <players>1</players> </game> </gamelist>
Within the gamelist tags are a series of games, each within its own <game></game> tags. The data is scraped from game web sites, but you can manually edit the information as you like.
The retroarch.cfg file located in /opt/retropie/configs/all applies to all emulator cores. In addition, each emulated core can have its own retroarch.cfg located in /opt/retropie/configs.
Changes must be applied at the top of the file, and they will override the general retroarch.cfg settings. Each system has its own directory.
This file, /etc/emulationstation/ex_systems.cfg, determines what systems appear in the EmulationStation main menu and in what order.
<system> <name>ports</name> <fullname>Ports</fullname> <path>/home/pi/RetroPie/roms/ports</path> <extension>.sh .SH</extension> <command>%ROM%</command> <platform>pc</platform> <theme>ports</theme> <directlaunch/> </system>
Each system is defined within <system></system> tags. Usually, a system will not appear unless at least one game exists for it, but you can comment out any system you want by using HTML comments <!– –>. You can also delete the system entirely.
The <theme> element determines what graphics to display for that system. This makes a difference for identical systems with different names.
Important Files and Directories
When configuring files manually, here is a list of common directories in which to locate those files quickly.
/etc/emulationstation/themes EmulationStation Themes
/etc/emulationstation/es_systems.cfg Configures which systems to show in the EmulationStation main menu and in what order
/opt/retropie/config/all General RetroArch Configuration (retroarch.cfg)
/home/pi/retropie/BIOS BIOS files needed by emulators
/home/pi/retropie/roms Games. Games. Games! Each system has its own directory
/opt/retropie/config/<system>/retroarch.cfg Specific RetroArch configuration for system
/opt/retropie/config/<system>/emulators.cfg List of emulators available for the system and which is the default
/opt/retropie/configs/all/emulationstation/downloaded_images/<system> Cover art for EmulationStation metadata
Shutting Down RetroPie
“How should I turn off the Pi?”
There is no power button. While you could yank out the power cable, it is usually best to shut down the system from software first, and then unplug the power cable. The Pi is a computer like any other, and this ensures the operating system tidies up.
From the EmulationStation main menu, select Quit and then choose “Shutdown System.”
After the prompt to “Really Shutdown?” choose “Yes.”
RetroPie will shutdown to a blank screen. After the green LED in the Raspberry Pi stops flashing, unplug the cable.
RetroPie offers so many tweaks that it could fill a book to cover them all. The RetroPie online documentation offers in-depth configuration for individual cores in addition to details not mentioned here.
If you encounter issues or your setup is not functioning properly, then this is a good place to start.
Hopefully, this brief two-part tutorial has piqued your interest into what is possible with the Raspberry Pi 2 running RetroPie and offered enough help to get you started.
RetroPie is rather difficult to break, but issues can arise. Backup important configuration files before editing them to be safe, and you should be fine.
Much more configuration can be performed from the command line. RetroPie is a Linux distribution, after all. Need htop and uprecords? Then, install then using apt-get. Whatever you know about Linux can be applied to RetroPie — aside from the hardware limitations.