New retrogame: Settings File

The latest version of retrogame reads the file /boot/retrogame.cfg on startup. A sample retrogame.cfg file was placed there by our installer on the prior page.

Below is an example from the PiGRRL 2 configuration file: There’s a lot of stuff in there but really it’s pretty simple…most of it is comments, which start with a ‘#’ character.

# Sample configuration file for retrogame.
# Really minimal syntax, typically two elements per line w/space delimiter:
# 1) a key name (from keyTable.h; shortened from /usr/include/linux/input.h).
# 2) a GPIO pin number; when grounded, will simulate corresponding keypress.
# Uses Broadcom pin numbers for GPIO.
# If first element is GND, the corresponding pin (or pins, multiple can be
# given) is a LOW-level output; an extra ground pin for connecting buttons.
# A '#' character indicates a comment to end-of-line.
# File can be edited "live," no need to restart retrogame!

# Here's a pin configuration for the PiGRRL 2 project:

LEFT       4  # Joypad left
RIGHT     19  # Joypad right
UP        16  # Joypad up
DOWN      26  # Joypad down
LEFTCTRL  14  # 'A' button
LEFTALT   15  # 'B' button
Z         20  # 'X' button
X         18  # 'Y' button
SPACE      5  # 'Select' button
ENTER      6  # 'Start' button
A         12  # Left shoulder button
S         13  # Right shoulder button
ESC       17  # Exit ROM; PiTFT Button 1
1         22  # PiTFT Button 2
2         23  # PiTFT Button 3
3         27  # PiTFT Button 4

# For configurations with few buttons (e.g. Cupcade), a key can be followed
# by multiple pin numbers.  When those pins are all held for a few seconds,
# this will generate the corresponding keypress (e.g. ESC to exit ROM).
# Only ONE such combo is supported within the file though; later entries
# will override earlier.

The important lines, in the middle, consist of a key name followed by a GPIO pin number. That’s really all there is to it.

Your basic letter and number key names are straightforward…for function keys and such, you can look in the file keyTable.h (included alongside the retrogame executable) for valid names, or in /usr/include/linux/input.x (remove the initial “KEY_” from the name).

If you want to use a GPIO pin as a spare ground for buttons: use “GND” as the key name, then list one or more pin numbers separated by spaces.

If you need just one more key…not as a gaming control, but for accessing menus or similar…follow a key name with multiple pin numbers (these can already be assigned to other keys themselves, that’s fine). When those buttons are all held for a few seconds, the corresponding keypress will be generated. We used this in our Cupcade project to access the Escape key. Currently only one such multi-button combo can be assigned.

If you want to put retrogame.cfg somewhere other than /boot, or assign a different name: in /etc/rc.local, where retrogame is being run, insert the absolute pathname to your configuration file as an argument (i.e. just before the “&”):

/usr/local/bin/retrogame /boot/myConfig.cfg &

Locating the configuration file in /boot makes it easier to edit this file on a non-Pi system, since the SD card can be inserted in a USB reader and accessed from most any computer.

If editing in /boot directly on the Pi, you’ll need to do this as root, i.e. sudo nano /boot/retrogame.cfg

If you change the name or location of the configuration file, you’ll need to reboot or restart retrogame. But if you’re just editing the pin assignments in the existing file, there’s no need…retrogame will pick up on these changes automatically, while its running, once changes are written to the file.

This guide was first published on Jun 03, 2013. It was last updated on 2017-03-07 13:46:39 -0500.

This page (Configuring Retrogame) was last updated on Nov 26, 2016.

Text editor powered by tinymce.