Setting Up RetroPie 4.2

Introduction

So I've been trying to get my Raspberry Pi 3B set up to run some old N64 games using the RetroPie setup.  My true goal was to get The Legend of Zelda Majora's Mask running with the hi-resolution textures.  I ran into a few problems along the way and thought I would share how I got everything to run smoothly from start to finish, as I found there wasn't a really good guide on the web to go from start to finish, especially for those not so tech savvy.  This tutorial assumes you know some basic linux shell commands (i.e. ls, cd, etc.) and are generally familiar with what an emulator is, and what SSH is.  I tried to make this as foolproof as possible, since I spent a lot of time struggling to get this set up correctly, and I am very new to the Raspberry Pi, Linux, and Emulators.

What you need:

• Raspberry Pi (3B works great)
• Micro SD Card (8 GB minimum, but 32GB is a good choice)
• USB Controller (I recommend the Logitech F310)
• USB Keyboard
• Computer (Mac, Windows, Linux)

Here is a summary of the basic steps:

1. Flash Retropie Image to micro SD Card

2. Configure Raspberry Pi, Retropie, EmulationStation

   A. WiFi Setup

   B. Raspberry Pi Keyboard & Timezone Setup

   C. RetroPie Setup

3. Adding ROMS

   A. Transfer ROM

   B. Determine Internal ROM Name
4. Adding Hi-Res Texture packs

5. Configure Mupen64plus
6. Configure Controller

1. Flash Retropie Image to micro SD Card

Download the latest RetroPie image. At the time of this post, v4.2 was the latest.  Once the img.gz file is downloaded, it will then need to be uncompressed (unzipped) and then flashed to a Micro SD card.  Since I am using a MacBook Pro to download and write the image to set up the SD card, the .img.gz file can be unzipped simply by double clicking on the file, resulting in a .img file.  If you have a windows based computer, you can use WinZip to unzip the .gz file.

The .img file cannot be copied to the SD card, since the .img file simply contains the instructions and data necessary to write the completed image.  In order to get the RetroPie image onto the Micro SD card, you will need to flash the image from your computer to the SD card.  This can be done through a variety of ways, and these methods can be found on the Raspberry Pi Website. Once the image was flashed to the card, place it into your Raspberry Pi to allow it to run the initial boot.  Since I will be using a controller to play the games, I made sure to have my USB controller plugged in for the initial setup, as well as my USB keyboard to get everything configured.  The RetroPie will guide you through setting up your controller on initial boot, so make sure to use this to navigate Emulationstation.

2. Configure Raspberry Pi, Retropie, EmulationStation

Eventually, the Pi should boot into Emulationstation.  This is a program that acts to help guide you through to all the emulators and settings.  Think of it as a visual way (GUI) of navigating through all of your games, and launching them with the correct controller settings and emulators.  EmulationStation is really just a way to conveniently browse and launch your games, without having to remember all the pathways to the emulators, commands for plugins that you would (or still can) type into the raspberry pi console itself.  Emulationstation is great though, as it allows you to set just about everything up from the WiFi, Keyboard, Controllers, etc.  Of course you can do this all manually if you choose, they both have the exact same end result in terms of how the files on the pi look when you are done.  It's just a little more convenient to do it through Emulationstation.

If you ever want to exit the Emulationstation and access the Pi command line, just hit F4.  To get back to Emulationstation, just type "emulationstation" into the pi console (without quotes) and it should boot right back up.  While I was writing this, when going back and forth this way, the console would occasionally "freeze" with only the blinking cursor and directory visible.  I couldn't type anything however, and so I frequently pulled the power cord on the pi to get it "reset".  Alternatively, its possible to SSH into the pi from another computer and perform a reboot, however, I was often pretty lazy.

A. WiFi Setup

Once inside EmulationStation, since no ROMS are installed, you will only see the RetroPie Icon.  Open this up.  This should bring you to a screen with several settings you can change.  First, go to WiFi on the bottom, find your WiFi network, and type in the password.  That's it!

If you want to setup WiFi from the command line instead, here is a great guide.

B. Raspberry Pi Timezone and Keyboard Setup

Then, go back to the RetroPie setup and choose Raspi-Config.  Opening this will bring you to the raspi-config menu (same as typing "sudo raspi-config" into the pi console).  Here, there are several options you can change, including the password (Option 1) and the hostname or name of your raspberry pi (Option 2).

Run the update (Option 8) to make sure the raspi-config tool (the screen you are on currently) is fully updated.  Once that's done, it's important to configure the localisation options (Option 4) to get the time zone correct and keyboard layout correct.  These are pretty straightforward, however, if you are in a country other than the UK (which is default) you will have to change these.  For those in the US, choose the "en_US.UTF-8 UTF-8" by scrolling down, hitting space to select, and then enter to move to the next page where you should use the arrows to again choose "en_US.UTF-8 UTF-8".  For the keyboard, most likely you have a 104 key, keyboard (if you have the 2 window keys and the menu key on the bottom, its a 104 key.  If not, then you have a 101 key).  Being in the USA, we choose the English (US) layout, which does not have AltGr or Compose keys.

If you want to have to ability to SSH into your Pi remotely through another computer, make sure to enable SSH (Option 5).

You can overclock from this screen if you want to, however, I've had decent success without doing so on the Raspberry Pi 3B, even when running the hi-res textures on Majora's Mask (MM).

C. RetroPie Setup

Once the raspberry pi is set up go ahead and exit back to Emulationstation.  Then go to RetroPie setup now.  In this setup screen there are several options.  First, update the RetroPie-Setup script, which simply updates this script itself.  Additionally, its good to update all the installed packages as well to make sure the RetroPie is up to date.  Under Configuration/Tool I enabled Dispmanx by hitting enter on that option, although nothing really appeared to happen.  We'll see what happens later...

From this menu you can also manage what other emulators you would like installed (or uninstalled).  It's good to navigate this a little bit to see what options you have.  Not really too much needs to be done here, however.

3. Adding ROMS

Once this is done, the pi is pretty much set up to run some games (although there might still be some controller key mismatches).  As far as acquiring the ROMS, you legally are supposed to have these, and are not supposed to download them from third parties, however, they can be found.  Since I am interested in getting some N64 ROMS started, I will demonstrate how to load these, although the process is identical for other emulator systems.  N64 ROMS typically have a .n64, .v64 file formats, although there are several.

A. Transfer ROM

Once you do have your ROMS, they are usually pretty small files, and so are conveniently transferred to the Pi using WiFi.  This is accomplished using SSH File Transfer Protocol (SFTP) which is just like using SSH to get into your pi (both use port:22) but it allows you to transfer files.  I use Cyberduck, as you can open up the raspberry pi folder directly and drag and drop the ROM files into the proper folder.  To do this, open Cyberduck on another computer where your ROM is located.  In Cyberduck, click "Open Connection" type in the local IP address of the Raspberry Pi where RetroPie is installed (usually 192.168.1.x, where x is another number), username of the Pi (default for RetroPie Image = pi), password (default = raspberry), and port (use port 22) open up a SFTP to allow me to transfer some N64 ROMs to the Pi.  Since they are small and the WiFi is set up now, it doesn't take to long to transfer this way.  Once you are connected to the Pi, you can simply drag and drop the ROMS into the n64 folder located at ~/RetroPie/roms/n64.  Once they are in this folder, Emulationstation search all the folders under ~/RetroPie/roms and will recognize that there is a game present and will update accordingly (Pretty nice!).  Since I'm really interested in playing The Legend of Zelda Majora's Mask, I elected to use this as a test game, and so I dragged the rom file for this game which I renamed to "The Legend of Zelda Majora's Mask.n64" into this folder.

B. Determine Internal ROM Name

Now there is a really important piece of information to understand here.  The name of the file I transferred above is "The Legend of Zelda Majora's Mask.n64", however, the N64 emulator that we need to use to recognize the hi-resolution textures we are going to add in, recognizes the game by an internal ROM name included within the .n64 file itself.  It is important to determine what this internal ROM name is, as that name will need to be used exactly in order to add in the texture packs.

The easiest way to find the name is to start the emulator and load the rom from the command line of the raspberry pi.  This can be done by navigating to the directory where your n64 ROM is located

cd ~/RetroPie/roms/n64

and then manually booting the emulator

/opt/retropie/emulators/mupen64plus/bin/mupen64plus.sh mupen64plus-video-rice The\ Legend\ of\ Zelda\ Majora\'s\ Mask.n64

This will trigger a several lines of text to come across the screen, followed by the emulator booting over the top of this text.  Exit out of the video emulator on the keyboard by hitting escape, and near the top of the screen you should see the following:

...
Core: Goodname: Legend of Zelda, The - Majora's Mask (U) [!]
Core: Name: ZELDA MAJORA'S MASK
...

The title in all capital letters is the internal ROM name.

4. Adding Hi-Res Texture Pack for Majora's Mask

The texture pack is a series of .png images that replace the textures of the original game to give it a different look.  These are made by members of the community who have a lot of time and creativity to make some really amazing texture re-works.  When the texture pack is downloaded, it is usually in the form of a .dat file or .htc file.  These will need to be extracted to produce the final set of 1000's of .png images.

The texture packs can be found here under the downloads section.  For The Legend of Zelda Majora's Mask, I want to utilize is the Cellpack 2011 created by Djipi.  I had some trouble extracting the 3rd zip from this site, so instead I found another site that had 1 .zip file that worked much better (located here).  Make sure to download the one for "rice".  The two options (rice vs. Glide) are different graphics rendering engines that can be chosen for the mupen64plus emulator.  Some games work better with Rice, others with Glide.  Majora's Mask and other Zelda games work better with the Rice video plugin.  Navigate to the website on your computer, download the .zip file and extract the contents.  You should have 2 .dat files (ZELDA MAJORA'S MASK_HIRESTEXTURE.dat and ZELDA MAJORA'S MASK_MEMORYCACHE.dat).  Go ahead and move these files to your home directory (~/) using Cyberduck.  You may have to use the mv command to get them there.

Our next step is to download the programs necessary to unpack these .dat files.  An amazing post by jax3rir on reddit gives a wonderful walkthrough of this process here, but I will type it below to make it convenient as well.  This is literally the hardest part of the whole process, and it's really not too bad.

On your raspberry pi, navigate to your home directory by typing:

cd

then, perform the following:

sudo apt-get install git
sudo apt-get install tar
sudo apt-get install imagemagick
sudo mkdir /.local/share/mupen64plus/hires_texture
git clone https://github.com/ecsv/glide64-cache-extract
cd glide64-cache-extract
make
chmod +x glide64_cache_extract
sudo cp glide64_cache_extract /usr/local/bin
sudo chown root /usr/local/bin/glide64_cache_extract
mkdir textures
cd textures
zcat "ZELDA MAJORA'S MASK_HIRESTEXTURE.dat" | glide64_cache_extract -b -p "ZELDA MAJORA'S MASK" | tar x
zcat "ZELDA MAJORA'S MASK_MEMORYCACHE.dat" | glide64_cache_extract -b -p "ZELDA MAJORA'S MASK" | tar x
for i in *.bmp; do convert -strip -define png:format=png32 -define png:compression-level=9 "${i}" "${i%.bmp}.png"; done
rm *.bmp
mkdir ZELDA MAJORA'S MASK
mv *.png "ZELDA MAJORA'S MASK"
mv ZELDA\ MAJORA\'S\ MASK ~/.local/share/mupen64plus/hires_texture

So what did we just do?  Well, we installed some necessary packages first to accomplish what we wanted to achieve.  We then made a folder named hires_texture.  This folder is where the folder containing all the .png images of the textures go.  It is crucial that the name of this folder be exact, as the emulator will search for the folder with this name.

After this, a program named "glide64_cache_extract" was installed and the permissions to modify this program was given to the root user.  Then, the .dat files were extracted, the contents passed to the glide64_cache_extract program which performs its task and add's "ZELDA MAJORA'S MASK" to the beginning of each image name.  This is then passed to a another extraction, the tar x.  What results is a series of 1000's of .bmp image files.  These need to be converted to .png files, and that's what the next command does, specifying the type of .png and its compression level (The "convert" function is defined by the ImageMagick app you installed earlier).  Then all the .bmp files are removed, and the contents placed into a folder named "ZELDA MAJORA'S MASK".  Your final results is a series of .png images located under:

/home/pi/.local/share/mupen64plus/hires_texture/ZELDA\ MAJORA\'S\ MASK

The name of the folder and the name in front of all the images is CRUCIAL!  They all MUST match the name of the internal ROM name.

5. Configure Mupen64Plus

Ok, quick summary, what have we done?  We've installed and configured RetroPie, Emulationstation, and the Raspberry Pi, loaded our ROM, and placed the Hi-res textures in the correct path.  The last step is to configure the emulator (mupen64plus) to ensure that it will load the high-res textures.  This is an easy step.  We just need to add/modify some text in the mupen64plus.cfg file.  Type:

cd /opt/retropie/configs/n64
nano mupen64plus.cfg

Within this file there are plenty of configurations, which you can certainly spend some time getting used to.  Since Majora's Mask will be run using the rice video plugin, we don't need to modify the Glide64 section although we will anyway in case you want to run other ROMS on the glide plugin.  If you don't see a glide or rice section, you can try to run the ROM via emulationstation and specify the emulator and plugins by pressing any button on your controller as soon as you select the game.  For me, running the game and then rechecking this file did not change anything.

In this file you can modify the following found under the [Video-GLideN64] heading.  Under this heading look for the following and make sure the variable reads "True"

# Use high-resolution texture packs if available.
txHiResTextures = True

Then, at the bottom of the file add the following:

[Video-Rice]
LoadHiResTextures = True

press ctrl+x to trigger the exit dialogue, press y to save, and enter to confirm.  At this point, you are pretty much all set up, minus the controller configuration.

To test if the texture packs load, you need to make sure you are running the proper emulator and plugins that enable the hi-res textures.  I navigated to the N64 section within emulationstation and selected Majora's Mask.  A brief dialogue appears that says to press any button to configure.  Once you enter this dialogue you will find options to set the default emulator plugins for the system (the Nintendo 64 in this case) or for an individual ROM.  The more specific you get, the higher precedence the configurations.  In this case, ROM configs beat out the emulator configs.  Make sure to select the mupen64plus-gles2rice-hires, and launch the game.  You should see changes already just by looking at the main title or start screen when the game is loaded.  If this works, you are pretty much done!  You just need to configure the controller next!

6. Controller Configuration

For most emulators in the RetroPie, a kind or organizer known as Retroarch is able to manage a lot of the configurations for emulators ranging from SNES, to N64, to Amiga.  Retroarch is great because it will supply some default controls for every system, avoiding the need to configure each emulator individually.  It's a nice organizer, and is used for all the emulators.  For the N64, however, Retroarch only provides controls when the lr-mupen64plus is chosen as the emulator.  And it appears to run pretty pixelated.

For our hi-res textures, we actually need to individually configure the mupen64plus emulator (kind of a bummer).  First, map the buttons on your controller to their values that the system recognized by typing the following into the console:

jstest /dev/input/js0

You can test out all the buttons and see what button triggers the values to change.  When you have mapped them all out, hit ctrl+c to exit.

Here are my Controller Mappings:

Axis:

0 = Left Joystick X

1 = Left Joystick Y

2 = Right Joystick X

3 = Right Joystick Y

4 = D Pad X

5 = D Pad Y

Buttons:

0 = A

1 = B

2 = X

3 = Y

4 = Left Button

5 = Right Button

6 = Left Trigger

7 = Right Trigger

8 = Select

9 = Start

10 = Logitech (Home)

11 = Left Joystick Button

12 = Right Joystick Button

First, lets make sure that the controller configuration (yes there is a controller configuration file too!) is how we want it.  For example, to save games, I would like to use a hotkey (The home button, button 10) to use as a toggle so that I can hold this button and press, the A button to save the game, or hold home and press left trigger to load a game.

Each controller has its own configuration profile located at:

/opt/retropie/config/all/retroarch-joypad

Within this file, which for me is named "Logitech Gamepad F310.cfg".

Modify the file by typing:

nano Logitech\ Gamepad\ F310.cfg

From the default emulationstation configuration (which is what created this file in the first place), I want to change the "input_enable_hotkey_btn = "8" to "10".

From here I also modified the buttons for saving a loading states of the game which are:

input_load_state_btn = "6" (for me this is the L trigger)

input_save_state_btn = "0" (for me this is the A button)

There are a lot of parameters to play with, so go ahead, spend some time and use the syntax within the file to customize it how you want.

Now, we need the mupen64plus emulator to recognize what these controller keys map to in the game.  We must go back to the mupen64plus.cfg file located at:

/opt/retropie/configs/n64

The controller configuration (for player 1) is under the heading [Input-DSL-Control1].  Under here you will see a different way to map the controllers than you did previously in the gamepad.cfg file.  Copy this syntax and map the controls. Additionally, these changes should be made into the InputAutoCfg.ini file within the same subfolder as well.  You may need to test it out a few times to get it how you want.

Keep in mind that these other emulators do not run off of the retroarch configuration and so don't utilize the same interface.  Because of this, the save states work very differently.  Additionally, the configuration files also have a different format than the retroarch configurations.

Changing these to the correct button values maps the buttons better.  The shortcuts are still all correct, however as these were defined within the global retroarch config file.  Apparently retroarch configurations do not transfer over to the mupen64plus based emulator.

At this point, you should have the game working pretty well.  If you are having trouble with the controller configuration (like I did at first) check out this link to get a little more help.

Hope you found this helpful, it took me a long time to write and an even longer time to figure out.

Feel free to leave a comment!