Batocera Remote Control

Important

ALPHA RELEASE: This project is currently in active alpha development. It is provided for personal, non-commercial use only. Please refer to the LICENSE.md file for terms and conditions.

Warning

VIBE CODED: This codebase has been vibe coded. Use entirely at your own risk.

A mobile-first, installable (PWA) web application to monitor, control, and launch games on a remote Batocera Linux retro-gaming system.

(Features a sleek glassmorphic cyber-punk UI tailored for mobile screens)

---

Features

• 🎮 Game Library & Launcher: Browse systems and lists of games, search titles, view descriptions/developer metadata/box art, and launch games directly on the remote screen.
• 🛑 Active Game Controller: Save/Load/Pause/Fast Forward/Reset/Stop currently running games/emulators with one tap from the dashboard.
• 🌡️ Diagnostics Dashboard: Real-time monitoring of CPU temperature, CPU usage, RAM utilization, and Disk storage.
• 📈 Performance History Graph: Multi-series line chart tracking CPU, Temp, and RAM trends over the last 15 minutes (powered by Chart.js).
• 📶 Bluetooth Controller Management: View paired controllers, check their connected status, scan for nearby Bluetooth devices, pair new gamepads, and disconnect active controllers.
• 🔌 Power Control & Wake-on-LAN: Shutdown, reboot, restart EmulationStation, or power on an offline device using Wake-on-LAN (WoL).
• 📱 Progressive Web App (PWA): Install the remote control as a native app on iOS or Android (features custom app icon, standalone immersive display, and offline asset caching).

---

Prerequisites

• Batocera Device: Running on your local network.
• Configure Developer Services: On your Batocera device, navigate to the settings menu and toggle the following options, then reboot:
  • Go to System Settings -> Frontend Developer Options and enable Public Web Access.
  • Go to System Settings -> Services and enable ES_WEB_NOTIFIER.
• Enable RetroArch Network Commands (Optional): Required for in-game Save State, Load State, Pause, Slot, Fast Forward, and Reset controls. The most reliable way to enable this is directly within the RetroArch user interface:
  1. Start any RetroArch game on your Batocera device.
  2. Open the RetroArch Quick Menu (usually by pressing Hotkey + B or Hotkey + South Button on your gamepad).
  3. Back out to the settings level, navigate to Settings -> Network.
  4. Toggle Network Commands to ON and ensure the Network Command Port is set to 55355.
  5. Save your preferences by going to the Main Menu -> Configuration File -> Save Current Configuration.
• Docker: Installed on the machine where you wish to run the remote control.
• SSH Access (Recommended): Enables Bluetooth pairing, diagnostic metrics, and power control commands. The default username is root and default password is linux.

---

Deployment & Setup

1. Clone the Repository:

   git clone https://github.com/Ian-Hartwell/Batocera-Remote-Control.git
   cd Batocera-Remote-Control

2. Start the Container:

   docker compose up -d --build

3. Link to Batocera:

   • Open your browser and navigate to http://localhost:1235 (or http://<docker-host-ip>:1235).
   • Go to the Settings tab.
   • Enter your Batocera device's IP address (e.g., 10.69.0.23).
   • Enter your SSH credentials (default: user root, password linux).
   • Click Save Settings or Test Connection.

Important

Network Mode & Wake-on-LAN (WoL) Requirement: Because WoL depends on sending UDP broadcast packets, the Docker container must run on the host's network stack to be able to reach your physical LAN.

• Docker Compose: By default, docker-compose.yml is configured with network_mode: host (the ports mapping is commented out because it is not needed in host mode).
• Unraid: Set the container's Network Type to Host (instead of Bridge). If using Host network mode, do not specify port mappings.

---

Configuration

Defaults can be pre-configured via environment variables in docker-compose.yml:

Environment Variable	Description	Default
BATOCERA_HOST	Hostname or IP of the Batocera machine	batocera.local
BATOCERA_USER	SSH username for commands & stats	root
BATOCERA_PASSWORD	SSH password for commands & stats	linux
RETROARCH_PORT	RetroArch UDP network command port	55355
BATOCERA_MAC	MAC address for Wake-on-LAN	(Auto-detected over SSH if credentials provided)

Note

All settings edited or saved via the Web UI are persisted inside a Docker volume (/config/config.json) and take precedence over environment variables.

---

PWA Installation

To install the remote control as a mobile application:

• iOS (Safari): Open the URL, tap the Share icon, and select Add to Home Screen.
• Android (Chrome): Open the URL, tap the three-dots menu, and select Install App or Add to Home Screen.

Once installed, it will open full-screen (without browser address bars) as a native application with offline asset caches.

---

Technical Architecture

• Backend: FastAPI (Python 3.12+)
  • Communicates with Batocera's API on port 1234 for game/metadata queries.
  • Establishes a lightweight SSH connection (via paramiko) to retrieve system telemetry, manage Bluetooth controllers, and trigger administration scripts.
  • Caches system stats for 5 seconds to provide real-time updates while protecting SSH throughput.
• Frontend: Single Page Application (SPA)
  • Styled with custom CSS variables (synthwave theme) and features premium glassmorphism.
  • Connects to browser navigation states (popstate) for back-button control.
  • Implements dynamic Chart.js canvas elements for historical performance graphs.