Toolbox Aid

March 6th, 2026 10:26 PM Mr. Q Categories: Gaming

If you want a professional arcade cabinet experience where the dedicated joystick plays only the games, hidden buttons handle the “technical” side (selecting, exiting, and locking the system), this guide is for you. We will use the Raspberry Pi’s GPIO pins to trigger system commands directly, ensuring guests can’t mess up your settings.

---

1. Hardware: The “Admin” Control Panel

Wire your buttons to these specific GPIO pins. Connect one side of each button to the physical GPIO pin and the other to a Ground (GND) pin. Using a “Hotkey” for the hidden buttons adds a layer of safety against accidental presses.

Function	GPIO Pin (BCM)	Physical Pin	Purpose
Select / Confirm	GPIO 17	Pin 11	Launches games / Enter
Back / Cancel	GPIO 27	Pin 13	Goes back in menus / ESC
Start	GPIO 22	Pin 15	Opens the Main Menu
Hotkey	GPIO 23	Pin 16	Required for combo actions
Volume Up	GPIO 5	Pin 29	Increase System Volume
Volume Down	GPIO 6	Pin 31	Decrease System Volume
Brightness Up	GPIO 12	Pin 32	Increase Screen Brightness
Brightness Down	GPIO 13	Pin 33	Decrease Screen Brightness
Enter Kiosk (Hotkey + 24)	GPIO 24	Pin 18	Hidden (Lock UI)
Exit Kiosk (Hotkey + 25)	GPIO 25	Pin 22	Hidden (Unlock UI)
Ground (GND)	Any GND	Pin 6, 9, 14…	Common Rail

---

2. Software Setup: GPIO-to-Keyboard

We need Batocera to see these pins as keyboard presses rather than a second joystick.

1. Connect to your Pi via SSH (User: root / Pass: password).
2. Install the Adafruit Retrogame driver:
   curl https://raw.githubusercontent.com > retrogame.sh && sudo bash retrogame.sh
3. Edit the configuration: nano /boot/retrogame.cfg and map your pins exactly:
   • 17 ENTER (Confirm)
   • 27 ESC (Back/Exit)
   • 22 S (Start)
   • 23 H (Hotkey)
   • 5 VOLUMEUP
   • 6 VOLUMEDOWN
   • 12 BRIGHTNESSUP
   • 13 BRIGHTNESSDOWN
   • 24 F7 (Lock)
   • 25 F8 (Unlock)

---

3. Scripting the Kiosk Toggle

We will create two scripts to modify the system configuration and restart the interface.

Create the Enter Kiosk Script:
nano /userdata/system/enter_kiosk.sh

#!/bin/bash
sed -i 's/system.ui.mode=.*/system.ui.mode=Kiosk/' /userdata/system/batocera.conf
batocera-es-swissknife --restart

Create the Exit Kiosk Script:
nano /userdata/system/exit_kiosk.sh

#!/bin/bash
sed -i 's/system.ui.mode=.*/system.ui.mode=Full/' /userdata/system/batocera.conf
batocera-es-swissknife --restart

Make them executable:
chmod +x /userdata/system/*.sh

---

4. Forced Kiosk Mode on Startup

This script ensures that the system always re-locks itself every time the Pi boots up, even if you forgot to lock it before shutting down.

1. Create the startup script:
   nano /userdata/system/scripts/custom_start.sh
2. Paste the following:
   #!/bin/bash case "$1" in start) sed -i 's/system.ui.mode=.*/system.ui.mode=Kiosk/' /userdata/system/batocera.conf ;; esac
3. Make it executable:
   chmod +x /userdata/system/scripts/custom_start.sh

---

5. Linking Buttons to Actions (Triggerhappy)

We use Triggerhappy to link your keyboard-emulated pins to Batocera system commands. Note the use of the H (Hotkey) modifier for the Kiosk commands.

1. Create the config:
   nano /userdata/system/configs/multimedia_keys.conf
2. Add these lines:
   • KEY_ESC 1 batocera-es-swissknife --emukill (Exit Game)
   • KEY_VOLUMEUP 1 batocera-audio setSystemVolume +5
   • KEY_VOLUMEDOWN 1 batocera-audio setSystemVolume -5
   • KEY_BRIGHTNESSUP 1 batocera-brightness + 5
   • KEY_BRIGHTNESSDOWN 1 batocera-brightness - 5
   • H+KEY_F7 1 /userdata/system/enter_kiosk.sh (Hotkey + Button 24 to Lock)
   • H+KEY_F8 1 /userdata/system/exit_kiosk.sh (Hotkey + Button 25 to Unlock)

---

6. Final Step: Lock the Joystick Out of the Menu

• Assign Player 1: In Controller Settings, set Input P1 to your GPIO/Keyboard device. This makes your buttons the “Master” for the menu.
• Restrict Input: In System Settings > Frontend Developer Options, enable “Only Accept Input from Player 1.” This kills the joystick’s ability to move the menu.
• Gameplay Swap: In Game Settings > Per-System Configuration, set the P1 Controller to your USB Joystick.

---

7. Debouncing & Sensitivity

Most modern arcade buttons and Batocera drivers (like retrogame) handle debouncing in software automatically. You likely won’t need hardware capacitors. If you notice “double-pressing” in menus, you can adjust the polling rate in your driver settings, though this is rarely necessary for standard arcade switches.

The Result

The system always boots into Kiosk Mode. Your joystick is disabled in the menus to prevent tampering. You navigate, adjust volume, and change brightness using the dedicated GPIO buttons. To enter or exit Kiosk mode, you must hold your Hotkey and press your Hidden Admin Buttons.