FIRST READ THIS BIT
It is a good idea to back up your software in case of emergency. I recommend imaging your whole SD card for easy restore should something go bad.
By default this software operates at low resolutions and is intended for use on monitors that can handle 240p/480i, 288p etc.
This software is intended for use with RaspberryJAMMA hardware using GPIO controls.
TheMK_ARCADE_JOYSTICK kernel module loads early during boot, to disable it edit /etc/modules with root privileges 'sudo nano /etc/modules'.
I DO NOT recommend hotplugging usb devices when powering the pi through JAMMA.
Plug and unplug your USB keyboard or whatever else when the power is off.
***
INCLUDED SOFTWARE
This Raspberry Pi distro is built around the following software (and would not be possible without a lot of peoples hard work, huge thanks to everyone involved in open source development)
EMULATORS
-MAME 0.203 (newest version of MAME included, has the most accurate emulation and can do a few things the others can't like mirrored cocktail mode & fine adjustments to video output size ) *203 will have the most accurate emulation available
-MAME 0.172 (2nd newest version of MAME included, has the most accurate emulation and can do a few things the others can't like mirrored cocktail mode & fine adjustments to video output size) *172 is HIGHLY RECOMMENDED
-AdvanceMAME (designed for use with arcade monitors, very configurable - HIGHLY RECOMMENDED for its mix of good speed, options and generally good emulation quality)
-RetroArch and it's cores
lr-MAME2003-plus (MAME 0.078 retroarch core, good speed but a little buggy, improving though -
good for MK2 and later Midway titles & SEGA System32 games) *also very good at mapping analog controls to a digital joystick (a bit buggy on actual analog controls)*
lr-MAME2000 (MAME 0.037) (Retroarch version or MAME4All) (the fastest version of MAME for arm architecture but very old with the most dated emulation.) *Not particularly recommended for Pi3, the other versions of MAME have much better emulation due to age, last resort for hard to run titles* - no high score support
lr-MAME2010 (MAME 0.139 retroarch core) (not particularly recommended, most buggy MAME version included – no suport for saving high scores – last resort)
lr-FBA_Next (retroarch core, fast but not as accurate/configurable as mame - good for CPS3 & PGM & a few SHMUPS that are buggy in advmame – has most complete NEOGEO support) – partial high score support
-Daphne (plays laser disc games like Dragons Lair & Space Ace)
- Assorted console emulators (usually MESS or RetroArch based)
FRONTENDS
-Attract-Mode (fancy frontend hugely themeable, access to Attract-Mode menus through 'tab' on keyboard or cab ‘test’ button/switch, cab ‘service’ button or keyboard ‘F4’ to access ARpiCADEsettings service menu – service menu is sepperate instance of Attract-Mode)
-AdvanceMENU (now depreciated & will need config to actually use, but is still installed) the optional frontend, formally the default.
OTHER SOFTWARE IN USE
-Linux and other free tools (Raspbian base)
-GPIO controls are currently using mk_arcade_joystick modified to suit the wiring of the RaspberryJAMMA board
-The hotkey system is currently using xboxdrv as a joystick to keyboard interpreter
***
BASIC USE
Copy roms to SD card plug into JAMMA cab power up and play.
ADDING ROMS
Arcade roms should be placed in /boot/romsArcade/*/%.zip where "*" is the emulator and "%" is the game. Roms must be in the correct directories and named and zipped according to the conventions of the relevant emulator.
The exception to the arcade rom storage system is Daphne, its roms are stored in /boot/romsArcade/daphne/rom and framefiles in /boot/romsArcade/daphne/framefile/(directory with same name as the rom) due to the way the emulator works.
Console roms in: /boot/romsConsoles/*/%.ext where "*" is the emulator, "%" is the game and “ext” is the relevant extension. Roms must be in the correct directories and generally must be unzipped (except advmess). Names of console roms are not critical as they are for arcade roms, name them so you can identify them in the menu. Use underscores instead of spaces in filenames, in menu underscores will be shown as spaces.
Rom scanning is automatic at startup by default but can also be done manually through the service menu (usefull if you have disabled the autoscan in /boot/run.sh). Make sure to safely remove/eject your SD card before pulling it out of your PC.
JOYSTICK SHORTCUTS (IN GAME HOTKEYS)
Hold 1P Start for a couple of seconds exits a game back to the menu. (equivilent of keyboard ’esc’ key)
Press 1P Start + P1B1 == Credit (equivilent of keyboard ’5’ key)
Press 1P Start + P1 Joy Down == Pause/Unpause (equivilent of keyboard ’p’ key)
Press 1P Start + P1 Joy Right == MAME menus (MAME only) (equivilent of keyboard ’tab’ key)
Press 1P Start + P1B6 == Retroarch menus (Retroarch emulators only) (equivilent of keyboard ’F1’
key)
Hotkey shortcuts can be configured in /boot/hotkeys.ini (back it up first just in case).
The hotkeys system can be fully disabled in /boot/run.sh for single game use or if you have a dedicated exit button or similar.
***
ADVANCED USE
SD CARD STRUCTURE
The "boot" partition (disk label ‘BOOT’) There are (at least) two partitions on a typical Raspberry Pi installation. Only one of these partitions (the first) is usable by Windows. For Windows users this software compilation features an expanded first partition containing the rom directories for the emulators. This allows you to update your roms through a Windows computer.
There has been a lot of effort put into making as much accessable through the boot partition as possible but for some tasks you will need access to the second partitoin too. More extensive customisation can be done on the pi or on a Linux (or possibly other UNIX like OS) box which will be able to see the second partition as well as the first. There is a directory on the boot partition to assist in updating settings usually unreachable by Windows using scripts run from the menu (/boot/config-updater). It is also possible third party Windows software can assist here.
There is quite a lot of stuff in /boot for easy access through a desktop computer.
Please note:
Some othese files are best edited in Notepad++ or other advanced text editor rather than the built in Windows ones. The built in Windows notepad and wordpad tend to change the format of files and can break things.
config.txt (the Rpi bios settings file)
Basic instructions to the Raspberry Pi for booting are contained in
/boot/config.txt
which can be seen in the boot partition of the SD card as config.txt (even in Windows). Options contained within this file include video mode and overclocking. For use with the RaspberryJAMMAhardware the hdmi_mode option directly changes the resulting RGB output from the JAMMA edge connector. This software boots in 480i and switches resolution before launching games so be careful editing resolution settings here.
Video output width can be changed in config.txt using the overscan options without image quality being ruined. Best not to play with the height though as it will affect the scanline perfect output and degrade the image.
Video output can also be flipped (180 degrees) in this file without a performance hit using display_rotate=2 Although rotating (90 degrees) output here is possible it is easier to achieve consistent results across multiple emulators using emulator specific options (these can be set automatically through the service menu options).
Rom folders
Arcade roms are stored on this partition in /boot/roms/*/%.zip where "*" is the emulator and "%" is the game. Roms must be in the correct directories and named and zipped according to the conventions of the relevant emulator. The exception to the rom storage system is Daphne, its roms are stored in /boot/roms/daphne/rom and framefiles in /boot/roms/daphne/framefile/(directory with same name as the rom) due to the way the emulator works.
Console roms are stored in /boot/roms/consoles/*/%.ext where "*" is the emulator, "%" is the game and “ext” is the relevant extension. Roms must be in the correct directories and generally must be unzipped. Names of console roms are not critical as they are for arcade roms, name them so you can identify them in the menu.
Autorun Instructions
The instructions for what happens after boot are in /boot/run.sh which is a shell script controlling what happens after the automatic system login. It launches the game selection menu Attract-Mode. You can also make a game auto launch in this file (example in file), launching a game earlier in the script than the line that starts Attract-Mode will cause Attract-Mode to load after you exit the automatically launched game.
Emulator launchers
The emulator launcher scripts are in /boot/launchers/ and are used to change the resolution prior to loading games (when applicable) and back again after. This folder also contains the parts of the new system config menu for Attract-Mode (servMenu.sh).
Emulator previews and loading images are also stored in /boot, preview snaps (or movies), marquees and wheel images go in: /boot/previews/(relevant folder name) for snaps movie files will be used if available (and supported by the Attract-Mode theme you’re using). The loading images can be found in /boot which one is used at any time is dictated by the script nowloadn.sh (also found in /boot). Multiple loading files exist to cover multiple resolutions that can be used, individual files can be adjusted if you want to find consistent results across multiple resolutions on your particular setup.
Hotkey config is done through /boot/hotkeys.ini You can delete lines to disable certain functions, or add new ones if you need them. (sorry this process is not yet well documented, hotkeys are currently a bit WIP)
Optional
If you are curious about what is actually happening during boot the regular Linux boot text can be seenby replacing /boot/cmdline.txt with /boot/cmdline.txt.bak if you want to go back to the silent boot use
/boot/cmdline.txt.silent
Please note: RPi2 will always show the boot text, Rpi3 (all versions) can be switched on and off
***
The other partition (disk label ‘ARpiCADE’)
Basically invisible to Windows is the second partition. It contains the Linux system and emulator software and config files. To edit these files you will need either a computer running an OS that can write to this partition or to edit the files on the Raspberry Pi using a USB keyboard. Editing on the Raspberry Pi is easiest outside of an arcade cabinet on a more modern monitor however in cab edits are possible in a pinch (and, if using AdvMenu, the F8 menu in AdvMenu can help too).
MAME options files
To edit MAME options:
for MAME 0.203 (partially controlled by the launcher instead of the config file)
/home/pi/mame203/mame.ini
for MAME 0.172 (partially controlled by the launcher instead of the config file)
/home/pi/mame172/mame.ini
for AdvanceMAME (MAME-106) (some behaviour is controlled by the launcher instead of the
config file)
/home/pi/.advance/advmame.sdl.rc
(& for games that render badly in SDL /home/pi/.advance/advmame.rc)
there is also a dedicated AdvMAME094 config file (and some of it’s behaviour is actually controlled
in the launcher script)
/home/pi/.advance/advmame-0.94.0.rc
For Retroarch based emulators use the Retroarch menus to edit settings. Some Retroarch emulators are using multiple config files selected by the launcher scripts.
Rotation options are best done via the service menu in Attract-Mode rather than manually in the config files.
Menu config files
Editing attract modes config is best done through the built in menus but if needed all the files are in
/home/pi/.attract/
To edit AdvanceMenu options (not required to rotate or switch layout)
/home/pi/.advance/advmenu.rc
Bootsplash
Another file you may want to change is the boot splash which can be found at
/etc/splash.png
you will need to have root access (admin rights) to write to this location due to the structure of the Linux system. This can also be done through the new service menu in Attract-Mode or the F8 menu in AdvanceMENU (explained below in the FAQ).
***
FAQ
Why so many versions of MAME?
Each version of MAME included has it's strengths and weaknesses, to get the most out of the system a bit of mixing and matching is required.
MAME 0.172 has a great mix of speed and emulation quality – highly recommended to start here.
MAME 0.203 is the latest version and has the best emulation quality although it's performance is highly variable between titles.
AdvanceMAME has many more options and more accurate emulation than MAME4All or MAME2003/MAME078 as well as better performance than MAME0203.
Mame4all has faster emulation and is useful for any games which run slow in the other emulators, although it has the least accurate emulation of the MAMEs included (it is based on 15 year old MAME).
MAME072 (MAME2003 Retroarch core) has hacks built in to speed up the emulation of some Midway DCS audio titles. This emulator is slowly improving and is still under active development. It is also very good at mapping analog controls to digital JAMMA controls.
Do I need to safely shutdown the board in any way?
I recommend exiting a game so as you are at the game menu before shutting down your cabinet. It should not be necessary to run a shutdown script as while at the game menu there are no writes to the SD card to be interrupted to corrupt the card. If you make changes to your systems settings I recommend a shutdown or reboot to ensure those changes are written to the SD card. (but have a backup just in case things go bad some day)
How do I do X with Y piece of software on the Pi?
Try Googling specific pieces of software you are working with because with the exception of some scripts and modifying the scaling code of SDL1.2 I haven't been a programmer on any of this software.
The versions of software on this software compilation are publicly available and have much information online. If your query is to do with one of the scripts I have written or a specific ARpiCADE thing get in contact and I’ll help if I can.
How do I change the software from low res to high res to use with my other cab?
You start by setting the Pi to the resolution you want in /boot/config.txt using the hdmi_mode= setting you desire. This will ensure the hardware boots at the resolution you want and is the first thing to do. You will then need to edit the service menu launcher script (boot/launchers/servMenu.sh) to uncomment (remove the ‘#’ hash) the highres options. After a reboot the option will be available in the service menu. When the relevant option is selected the system will reconfigure itself and reboot in the selected settings.
How do I edit the game menu?
Fine tuning of the game list can be achieved through editing the file corresponding to the list you’re editing:
/home/pi/.attract/romlists/allGames.txt
/home/pi/.attract/romlists/Arcade.txt
/home/pi/.attract/romlists/Console.txt
each emulator also has its own list in the same folder, It is a good idea to switch off the rom scanning in /boot/run.sh to stop it overwriting any changes you've made. Attract-Mode themes and features can be explored via Attract-Modes built in menus access by pressing ‘test’ in your cab or using a keyboard by pressing 'tab'.
How do I rotate the system for my vertical monitor?
If your cab has no service button you will need to plug in a USB keyboard before powering up. Once the system has booted press either 'service'(cabside) or (on keyboard) 'left' or 'right' until you're at the service menu. Use the joystick to select low res vertical and the system will reconfigure itself and reboot setup vertical. You will probably also want to change the theme in Attract-Mode to a vertical one.
If you need to flip the picture to suit your monitor mounting:
In the file /boot/config.txt
display_rotate=2
or (depending on what is in the file currently)
#display_rotate=2
will flip the image should your monitor mounting be upside down compared to the image.
How do I edit files on the Rasp Pi?
Plug a USB keyboard into the Pi (best to do while powered off). When game menu has booted press "esc" to leave the menu (a second menu loads so do it again). You are now on a Linux command line and can edit files using the editor Nano nano /path/to/file.extension "ctrl" + "x" will exit nano after giving you the option to save your changes. If you need root access to save changes to a file launching nano with super user rights can be done with sudo nano /path/to/file.extension
Be careful editing files with super user privileges as you can render the system useless. It's probably a good idea to Google ‘Linux command line basics’ and familiarise yourself a bit if you want to learn more about using Linux on RPi.
When you are done on the command line you can type 'sudo reboot' to reboot, 'sudo poweroff' to shutdown the pi safely, or 'logout' to restart Attract-Mode (logging out will cause you to be automatically logged back in which causes /boot/run.sh to be run again so however you have run.sh setup is what will happen after a logout).
Please note if testing changes: running some emulators from the command line will give different results than through whatever menu is launched in run.sh in some conditions due to the modified version of SDL1.2.
How do I change the bootsplash?
There are 2 ways automated and manually...
This can be achieved from Attract-Mode service menu (cab service button OR left or right on a keyboard to find the service menu) or advmenu using the F8 menu and the /boot/config-updater folder.
Place the new picture you want in the /boot/config-updater/ folder as splash.png then boot up and use the option to update the splash.
The manual way:
Make the boot splash you want and copy it to the memory card in the boot partition (for the example, doing it maually you can do it however you want as long as you get the commands right) as "splash.png". Boot the Pi with USB keyboard attached, wait for menu to load, press "esc" to exit menu and at the command line copy your new boot splash to the system as a super user:
sudo cp /boot/splash.png /etc/splash.png
Then reboot to see if it worked out how you wanted.
sudo reboot
How can I set FREEPLAY?
The games that originally had freeplay options in dip switches can be set using the mame menus or in AdvanceMAME only through the config file line:
misc_freeplay yes
however, not all games had a freeplay mode and also a lot of games do not show an attract mode when set to freeplay so you will probably want a coin slot/button or button combo to add credits in mame.
Games which used test menus to set freeplay can have their test menus accessed by pressing the cabs Test button/switch or 'F2' on a keyboard during the game. You can also use the shortcut P1 Start + Button 1 for credits although this is not always practical (particularly for 2 player games).
Why don't my roms work?
Different versions of MAME use different romsets, some roms will work across many versions of MAME others won't. You can convert romsets using programs like romcenter and datfiles for the emulators.
The ARpiCADE image is sized smaller than the memory card I want to use how can I resize it?
The image is sized for an 8 gig card as it's the minimum usable size. To use a bigger card you will need to use the partitioning program of your choice to move the 2nd partition to the end of the image and resize the first partition to fill the newly created space in the middle of the card. Before resizing the first partition copy it's contents to your computer as resizing will destroy the contents, then copy it back when resized and you should have a working image.
There is a fantastic tutorial for this (many thanks to FrizzleFried) found here:
http://ahaforums.com/wp/2018/02/02/how-to-setup-arpicade-updates-for-larger-16gb32gb64gb-memory-cards/
Will this SD card image run on a standard RPi3 w/o the RaspberryJAMMA hardware?
Yes but it may require some setup. You may need to adjust the resolution in /boot/config.txt if your HDMI monitor doesn't like the signal (mine are fine with it), if you do need to change to high res also uncomment the change to highres options in /boot/launchers/servMenu.sh and adjust the system to highres in the Attract-Mode service menu (left/right on the keyboard or cab service button in the menu to find the service menu). Do not launch a game before changing the resolution like this or the launcher script could change the res to one unsuited to your monitor. Keyboard use may be buggy as the system is intended for cabinet use. You may want to disable the GPIO joystick driver and hotkeys system too but it shouldn’t really need to be done.
How do I stop the game list being generated every time I power up?
Can be disabled in /boot/run.sh (this is the file that controls what happens after the pi boots). Just hash the rom scanning line out to disable it. When I say hash I mean this symbol: #
How do I enable hi-res the easy way?
You need to adjust the resolution in /boot/config.txt to high res also uncomment the change to highres options in /boot/launchers/servMenu.sh and adjust the system to highres in the Attract-Mode service menu (left/right on the keyboard or cab service button in the menu to find the service menu). Do not launch a game before changing the resolution like this or the launcher script could change the res to one unsuited to your monitor.
How can I use WiFi?
As of 3.8 both WiFi and SSH are enabled by default but you will need to enter your WiFi details into /etc/wpa_supplicant/wpa_supplicant.conf to use it. This can be done via the service menu but requires a keyboard.
All standard Raspbian ssh details including password apply (password is raspberry). For more SSH info see here for Mac and Linux:
https://www.raspberrypi.org/documentation/remote-access/ssh/unix.md
OR here for Windows:
https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md
