This tutorial is a step-by-step walk through on getting MAME running on a Raspberry Pi. This guide is from November 2012 and parts of it maybe out of date if you are reading it at a later time. As of writing, software, operating systems and drivers for the Pi is quite young and constantly evolving so some of the solutions used here I consider as hacks and are not best practise.
The goal of this tutorial is to run a cut down, bare bones operating system and to create an image thats sole purpose is to run MAME arcade ROMs. The tutorial is written with a Windows user in mind but would also be useful for new Raspberry Pi owners who are not familiar or comfortable with the Linux shell.
January 2013: About a month after publishing this article Shea Silverman released PiPlay (formerly PiMAME) an all-in-one MAME solution for the Raspberry Pi based on Raspbian. If you want a ready, out of the box solution I recommend it. If you prefer to hack and customise your own MAME setup or to learn about the Linux shell on your Pi then please read on.
Firstly some jargon used in this tutorial.
- MAME Is a piece of software that emulates the hardware of legacy arcade video games. http://en.wikipedia.org/wiki/MAME
- Image Is a copy of a computer’s file system that is kept in a single file for easy storage and duplication.
- ROM Is like an image but it is a copy of the software used to power arcade video games.
- SD card Is a memory card used as storage for portable devices such as cameras, phones and the Raspberry Pi.
- ARM Is the type of CPU used by the Raspberry Pi, it is incompatible with software written for x86 processors such as those used in most desktops and laptops.
- Shell Is a text only interface that allows you to run programs and interact with the computer.
The hardware I used.
- SD to USB card reader.
- Micro-USB to USB cable.
- Flat Ethernet cable.
- USB keyboard.
- USB arcade joystick or Xbox 360 controllers. I have an old Elecom JC-AS01BK Arcade Stick.
- Raspberry Pi Model B with 256MB RAM.
- SanDisk SDHC 4 MB/sec 8GB card. You will need at least a 1GB card SD card for this project.
The GitHub repository of the some of the keyboard entries used in this article https://github.com/bengarrett/devtidbits/tree/master/post_805.
Choosing a Minimal Raspberry Pi Operating System
As mentioned before I want a bare bones operating system. There is no need for a graphical user interface or unnecessary development bloat as our Pi image has a singular purpose.
On searching the internet I know of a few options. The official downloads http://www.raspberrypi.org offer Raspbian and Arch Linux. Raspbian has too much bloat for our purpose, while Arch Linux for the ARM processor lacks software support.
Fortunately there is the little known Moebius Linux, a minimal Raspbian based distribution targeted for the Raspberry Pi. The Moebius website is at http://moebiuslinux.sourceforge.net while the download page is http://sourceforge.net/projects/moebiuslinux/files/raspberry.stable.
If you’re familiar with your Raspberry Pi and know how to transfer images to SD cards. Download and transfer the Moebius
moebius.minimal.image.1.0.1 moebius-1.1.1 image to your SD card, use it to boot your Raspberry Pi and read on. If that makes little sense please follow my supplemental article.
First boot and hardware configuration
Make sure your Pi has a keyboard attached, a connection to a LCD monitor or TV and an Ethernet link to the internet. Power the device using the micro-USB cable.
In Moebius 1.1.1 you maybe prompted for a log-in. Use root as the user and raspi for the password as per the Moebius FAQ.
Once booted you should be taken to the Moebius Main Configuration program.
First thing you should always do is change the default password by selecting Password.
You will want to run the AutoResize tool as only 850 MB of your SD card is in use by Moebius, and you may run out of available space using MAME.
The MemorySetup should be changed to the lowest value of 16Mb for VideoCore. This will set 16 MB of system memory to your GPU (graphics processor unit) instead of the default 128 MB. MAME does not use 3D graphics or video hardware acceleration which are the main benefactors of GPU memory.
Also take note of the Overclock which will use hardware tweaks to speed up your Pi. The downside of overclocking is it could shorten the life the Pi’s chip components. This might be an issue if you have a first release Pi that could become a collectors’ item in the future.
Once done, select Finish. You maybe rebooted, if so re-login as root. If you need to bring back the Main Configuration menu you can run moebius.config.
Using Secure Shell you can remote login to your Pi from your PC. You can operate the Pi without the need for a plugged in keyboard or display. In addition it allows you copy and paste text from your PC to the Pi. Remote login is already active in Moebius so you just need a Windows SSH client to connect to the Pi.
I would recommend Putty for a quick and easy solution. You can download it from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. You only need Putty.exe from the Binaries download for Windows on Intel x86. It is a stand-alone portable application so you can copy and run it from to your Raspberry Pi directory on your PC.
We need the numeric ip or inet address of the Pi which is its unique identifier when connected to your home network.
hostname -I (note the capital i)
$ hostname -I 192.168.1.8
On your PC launch the Putty application. At the Startup configuration screen enter the Pi’s address as the Host Name (or IP address). Make sure the Port is a value of 22 and that the Connection Type is SSH. Under Saved Sessions give it a name such as Raspberry Pi. Press the Save button.
To connect to your Pi press the Open button. If prompted press Yes to automatically trust future connections to the Pi device and then login with your root account. You should be remotely connected to the Pi via your PC. If you want to copy clipboard text from the PC to the Pi just right-mouse click the Putty text window. To copy text from your Pi, left-mouse click and hold to select the text, it is then copied to your PC’s clipboard.
If you’re new to the Linux shell try out some of the commands below.
Some useful shell tools
df -h --total
Lists the Size, Used and Available disk space on your SD card.
Lists the system memory (RAM) usage.
Lists CPU processor usage and active memory usage. To quit press
ping -c 3 www.google.com
To check to see that the Pi has a working internet connection.
Takes you to your user home directory.
Takes you to the file system root.
Lists files and directories of the active directory.
Lists them in a detailed format.
ls -l -color
Lists them using colour coding.
Reboots your Pi.
shutdown -hP 0
Shuts down and turns off your Pi. Note the zero.
Displays the content for a file. Example
cat /etc/passwd displays the user list of the Pi. If you need to exit cat press
clear will clear the screen.
Don’t forget you can use auto-completion in Linux, so moe
Tab+Enter will finish the rest of the command moebius.config and launch it for you. Auto-complete also works with directories, files and
apt-get repositories. Everything in Linux is case-sensitive so this means Moebius.config, moebius.config and moebius.Config are all treated as different applications.
Assuming your Pi is connected to the Internet we should update the Moebius software repositories and then its applications. This could be thought of as the Linux equivalent of Windows Update.
apt-get update apt-get upgrade -y
Moebius uses the Bourne compatible (
/bin/sh) Bash shell (
/bin/bash). I apply some customisations to help make its usage a little more useful with a Pi. Most of your system settings are in plain text files stored in
/etc/. Whenever you make a change to a file within here I recommend making a copy of the original so you can restore it if needed. Enter the settings directory, backup and then edit the Bash system-wide file.
cd /etc/ nano -B bash.bashrc
Nano is my recommended text file editor, the
-B argument automatically backups the source file.
bash.bashrc is the file name of the file we are editing. In Nano use the
⬇️ key or
PgDn to scroll to the end of the file and add the following if you wish. At the bottom of the file add the following though it is probably best if you copy the code and paste using a Putty SSH connection.
# Alias definitions. # You may want to put all your additions into a separate file like # /etc/bash_aliases, instead of adding them here directly. # See /usr/share/doc/bash-doc/examples in the bash-doc package. if [ -f /etc/bash_aliases ]; then . /etc/bash_aliases fi
Now create the file
bash_aliases that will be used to hold our customisations.
Copy and paste the following code into
#!/bin/sh # Alias definitions. # You may want to put all your additions in here. # See /usr/share/doc/bash-doc/examples in the bash-doc package. # Enable color support if [ -x /usr/bin/dircolors ]; then test -r ~/.dircolors && eval "$(dircolors -b ~/.dircolors)" || eval "$(dircolors -b)" alias ls='ls --color=auto' alias grep='grep --color=auto' alias fgrep='fgrep --color=auto' alias egrep='egrep --color=auto' fi # Extra ls aliases alias ll='ls -FAl' alias la='ls -FA' alias l='ls -FAoh' # Raspberry Pi Aliases alias raspi-audio="/usr/bin/alsamixer" alias raspi-cpu="/bin/cat /proc/cpuinfo" alias raspi-disk="/bin/df -h --total" alias raspi-firmware="/opt/vc/bin/vcgencmd version" alias raspi-mem="/usr/bin/free -th" alias raspi-ip="/bin/hostname -I" alias raspi-ping="/bin/ping -c 3 www.google.com" alias raspi-reboot="/sbin/reboot" alias raspi-shutdown="/sbin/shutdown -Ph 0" alias raspi-update="/usr/bin/apt-get update -y;/usr/bin/apt-get upgrade -y" alias raspi-version="/bin/cat /proc/version"
Once done press Ctrl+X to exit, answer Y to the Save modified buffer question and Enter to leave as is the File Name to Write [Backup] prompt.
If you try one of the new aliases it will return an error.
$ ll -bash: ll: command not found error.
source command to apply the changes and then retry the
source /etc/bash.bashrc ll
ll alias should now work and be treated as just another command. Another quick tip, you can pipe the output of one command into another.
ll | less
less allows you to use the arrows or the
PgDn keys to scroll through the output of
ll. To exit press
You can read more on customising profiles at http://www.hypexr.org/bash_tutorial.php.
As mentioned at the start of this article MAME is a complex piece of software that emulates antiquated video arcade machines to trick embedded game software into thinking they are running on original hardware.
As MAME is open-source and has been a working project since 1997 it comes in many different flavours for many operating systems. The official MAME project is for modern Microsoft Windows PCs with emulation accuracy a more prioritised goal than emulation speed. That means ports of the current versions of MAME are not suited for low and underpowered devices such as the Raspberry Pi.
AdvanceMAME is a MAME port that is for custom, embedded hardware and is perfect for our use. The most recent AdvanceMAME version is 1.2 which is compatible with ROMS packaged for MAME version 0.106 that came out in July 2006. This is important to note as the official MAME build as of May 2013 is version 0.148. So ROMS that work on your PC edition of MAME may not work on your Pi.
There is also an alternative Pi port of MAME based on the iMAME code-base which first came out for the HP Ipaq colour PDA back in 2001! The age of its code base and the ancient MAME 0.37 ROM support means it is best avoided.
Shea Silverman at http://blog.sheasilverman.com/tag/mame/ has compiled a Raspberry Pi Raspian port of AdvanceMAME. Download it to your root home directory. Install it using the Debian package management program.
cd ~ wget http://sheasilverman.com/rpi/raspbian/debs/advancemame_1.2-1_armhf.deb dpkg -i advancemame_1.2-1_armhf.deb
apt-get -y install libsdl1.2debian libfreetype6
Run AdvanceMAME for the first time.
A configuration file
advmame.rc is placed in the
/root/.advance/ directory. The file holds a huge list of default settings. Backup and then edit this file with Nano.
cd /root/.advance/ cp advmame.rc advmame.rc~ nano advmame.rc
Change the following settings.
device_mouse none misc_freeplay yes misc_quiet yes record_sound no record_video no
device_mouse turns off mouse support.
record_video turns off both recording functionality which is not suited to the Pi.
misc_freeplay turns the free-play mode switch on if a game supports it.
misc_quiet turns off the annoying start-up copyright message.
If the Pi is connected to a HDMI TV or monitor add the following to your settings.
device_video_clock 5 - 50 / 15.62 / 50 ; 5 - 50 / 15.73 / 60
For Pi’s using a HDMI to VGA converter this setting worked well for me.
device_video_clock 5 - 50 / 15.75 / 50
If you’re using the yellow composite connection get your device_video_clock value from the AdvanceMAME install document http://advancemame.sourceforge.net/doc-install.html#4.5. If you are not sure what analogue TV system your country uses try here http://countrycode.org/tv-standards.
Finally you may also want to tweak the audio with the sound_samplerate setting. This sets the audio quality output and I imagine could improve the performance of a game if lowered. The default value is
44100 but poorer quality values of
11025 are permitted.
A detailed list of all the settings used by advmame.rc is in the AdvanceMAME documentation http://advancemame.sourceforge.net/doc-advmame.html#8.
Save changes to
advmame.rc and exit Nano.
MAME ROMs and launch
MAME by itself is pretty useless. To get any fun or functionality you need ROM images of the game programs that are found in the arcade machines. A legal collection of free for non-commercial use ROMs is available at the MAMEDev site.
Your ROMs can go in either the
/root/.advance/rom/ or the
/usr/local/share/advance/rom/ directories. I would recommend the
/usr/local/share/advance/rom/ directory for greater flexibily. I download and then test the copy of AdvanceMAME with the 1982 arcade game Victory by Exidy.
cd /usr/local/share/advance/rom/ wget http://mamedev.org/roms/victory/victory.zip -U Firefox advmame victory
Make sure you do not run advmame victory in a SSH shell or a Putty connection as it will not work. At start-up you will experience a period of colour cycles, this is the legacy arcade software testing the hardware at power-on. At the Diagnostic Test Failure Screen press the 1 key. Congratulations you have a MAME game running on your Raspberry Pi!
To bring up the MAME menu press Tab.
To insert coins press the 5 key.
To start as player 1 after inserting a coin press the 1 key.
To exit MAME and return to Linux press Esc.
Transfer files from your PC to your Pi (optional).
Now that you have a running MAME device you may want to transfer files to the Pi from your PC. There are a couple of options available but I use SSH’s secure file transfer or SFTP. Its set-up is painless, near automatic and gives full access to the Pi’s file system if it is wanted. On the Windows side of things I use FileZilla Client, a free and open-source file transfer application.
On the Pi install openssh-server and fetch its IP address.
apt-get install -y openssh-server hostname -I
Your Pi should be ready to receive incoming SFTP connections.
Download, install, launch FileZilla Client on the PC and fill in its Quickconnect bar and press the Quickconnect button.
Host: Is the Pi’s IP address returned by
Password: Is your
root account password.
The left Local site: pane is the file system on your PC, the right Remote site: is your Pi. You can browse through directories on either. To transfer files to the Pi, simply select and right-click, Upload. If you want to upload ROMs it is best that you first navigate the Remote site directory to
Start MAME at boot (optional)
To have a true portable arcade device you need the Pi to login and launch MAME automatic without the need for a keyboard or user input.
To auto-login as root with no user login or password prompt, backup and edit the initialisation process settings.
cd /etc/ cp inittab inittab~ nano +54 inittab
1:2345:respawn:/sbin/getty --noclear 38400 tty1
1:2345:respawn:/sbin/getty -a root --noclear 38400 tty1 #1:2345:respawn:/sbin/getty --noclear 38400 tty1
Save changes to inittab and exit Nano.
To auto-launch AdvanceMAME we need to set-up the root account to use the file
.profile to run a custom Bash launch script after login.
cp /usr/share/base-files/dot.profile /root/.profile cd /root/ nano .bashrc
.bashrc add the following to auto-start AdvanceMame and save your changes. The echo command displays text on-screen while the && characters creates a new line. Hashes
# are used to ignore lines in a script which makes them useful for programming comments.
# /root/.bashrc: executed by bash(1) for root shells. # Launch AdvanceMAME with a ROM if [ -z "$SSH_CONNECTION" ]; then echo && echo "Starting AdvanceMAME" && echo /usr/local/bin/advmame victory fi
Congratulations you now have a self contained Raspberry Pi arcade emulator, reboot your Pi and test the auto-login and auto-launch.
While booting if you ever need to abort the auto-launch of AdvanceMAME you can tap Ctrl+C at the Welcome in your Moebius. Starting AdvMAME notification.
Install a menu to list games (optional)
AdvanceMenu is complementary program to AdvMAME that displays a complete list of all the MAME games stored on your Pi. You can additionally select and start any game from this list. To enable this menu feature first download and install AdvanceMenu for the Pi.
cd ~ wget http://sheasilverman.com/rpi/raspbian/debs/advancemenu_2.6-1_armhf.deb dpkg -i advancemenu_2.6-1_armhf.deb
Then run the program.
You should see a white menu with a list of all your MAME ROMs. The big grey box is where any preview images get displayed.
If you ever receive an XML syntax error at launch, delete the
advmame.xml file and try again.
rm ~/.advance/advmenu.xml advmenu
Use the keyboard arrow keys to navigate between games and press Enter to launch the selected title. F1 displays the AdvanceMenu options while Esc exits you to the Linux shell.
Preview images (snapshots) are in
~/.advance/snap. You can either download a collection online http://www.progettosnaps.net/snaps_en.html and place them in there or create your own by pressing the
F12 key when in-game.
If you want to launch advmenu at boot first make sure you follow the previous Start MAME At Boot instructions. But instead of launching advmame [game] edit the root
.bashrc file to launch advmenu.
nano +6 ~/.bashrc
#/usr/local/bin/advmame [game] /usr/local/bin/advmenu
Save the changes and reboot.
Slow or bugged hardware
If you are suffering from slower than expected hardware performance issues you may wish to update the Raspberry Pi’s fireware. Follow the
README.md instructions for rpi-update at https://github.com/Hexxeh/rpi-update so your Pi is refreshed to utilise the latest drivers for its hardware. This could improve performance and solve possible hardware bugs.
Another option to improve performance would be to run moebius.config and select Overclock to change the Pi’s clock preset to something greater than
The older ALSA drivers on the Pi are known to have quality issues when software is not running at full speed. I originally had big problems using the 3.5mm headphone jack combined with a HDMI display output, yet audio via HDMI worked perfectly. I would recommend an update to your Pi’s firmware, follow the README.md instructions for the use of rpi-update at https://github.com/Hexxeh/rpi-update.
If you have no audio output run
raspi-audio). Use the arrow-keys to adjust the PCM volume to make sure it is at least a value of
Controllers including the XBox 360 series
Potentially due to the power requirements you may find that your USB joypad or joystick will not work with your Pi. My Xbox 360 USB controller failed to work even when attached to the Pi via a powered USB hub. Using a 10 volt over-charge USB source to power my Pi didn’t help either. My imported Elecom joystick mentioned at the start of this article worked fine without any tweaking.
To get XBox 360 controllers to work on the Pi you need to install some extra drivers.
apt-get install -y xboxdrv
Now edit a boot configuration file to load the XBox 360 driver at boot.
nano +28 /etc/rc.local
Your cursor should be near the end of the file in between
Add the following lines if you are using XBox 360 Wired Controllers.
xboxdrv --trigger-as-button --id 0 --led 2 --deadzone 4000 --silent & sleep 1 xboxdrv --trigger-as-button --id 1 --led 3 --deadzone 4000 --silent &
Or these lines if you are using Wireless Controllers.
xboxdrv --trigger-as-button --wid 0 --led 2 --deadzone 4000 --silent & sleep 1 xboxdrv --trigger-as-button --wid 1 --led 3 --deadzone 4000 --silent &
The next time you reboot the drivers should launch and detect any XBox 360 controllers connected to your Pi. There are further configurations available from the RetroPie Setup GitHub page.
Using a non-root account
Though it is against best practice to use root for a general Linux activity I could not get AdvanceMAME with the USB drivers to correctly work without it. If you have better luck please let me know. Strangely one edit you need to make to launch AdvanceMAME as a non-root user is to as root give the floppy disk driver other group read write access.
chmod o+rw /dev/fd0
ERROR: required files are missing
There are several reasons why you may receive this error, see the MAME development FAQ. http://mamedev.org/devwiki/index.php/FAQ:ROMs#Why_does_MAME_report_.22missing_files.22_even_if_I_have_the_ROMs.3F
Written by Ben Garrett