RETRO-GAMER

Multi-System Retro Emulator for ESP32-FabGL

License: GPL v3 Platform: ESP32 Display: VGA

---

Table of Contents

• Description
• Supported Systems
• Features
• Hardware Requirements
• Pin Configuration
• Installation
• SD Card Structure
• Usage
• Building from Source
• Development
• Troubleshooting
• Known Limitations
• Acknowledgements
• License

---

Description

Retro-Gamer is a multi-system retro emulator firmware for ESP32-based devices with VGA output via FabGL. It brings retro gaming to life on a big screen with crisp 320x240 resolution and 64 colors (RGB222).

This project is a port and enhancement of ducalex's Retro-Go, adapted to run on the FabGL VGA framework. It features a unified launcher for all supported systems, in-game menus, save states, and extensive customization options.

Unlike the original Retro-Go (which was designed for handheld devices with small LCD screens), Retro-Gamer is optimized for VGA displays and PS/2 keyboard input, making it perfect for DIY retro gaming consoles and arcade cabinets.

---

Supported Systems

---

Features

---

Hardware Requirements

Minimum Requirements:

• ESP32 with PSRAM (mandatory)
• VGA compatible display (standard VGA monitor)
• PS/2 Keyboard
• MicroSD Card (for ROMs and saves)

Supported Boards:

• LilyGO TTGO VGA32
• Olimex ESP32-SBC-FabGL Rev B

---

Pin Configuration

LilyGO TTGO VGA32:

Olimex ESP32-SBC-FabGL Rev B:

Same as above, except SD CS = GPIO 4

---

Installation

1. Prepare the SD Card

Create the following folder structure on your SD card:

SD Card
├── retro-go/
│   ├── config/
│   │   ├── favorites.txt
│   │   ├── recent.txt
│   │   └── wifi.json (optional)
│   └── saves/
│       ├── nes/
│       ├── gb/
│       ├── sms/
│       ├── gg/
│       ├── pce/
│       ├── snes/
│       ├── lnx/
│       ├── md/
│       └── misc/
└── roms/
    ├── nes/         (NES .nes, .fc)
    ├── gb/          (Game Boy .gb)
    ├── gbc/         (Game Boy Color .gbc)
    ├── sms/         (Master System .sms)
    ├── gg/          (Game Gear .gg)
    ├── sg1000/      (SG-1000 .sg)
    ├── pce/         (PC Engine .pce)
    ├── snes/        (SNES .sfc, .smc)
    ├── lnx/         (Lynx .lnx)
    ├── col/         (ColecoVision .col)
    └── md/          (Mega Drive/Genesis .md, .gen, .bin, .smd)

2. Flash the Firmware

1. Download the latest firmware from the Releases page.
2. Connect your ESP32 board to your computer via USB.
3. Flash using esptool:

esptool.py write_flash --flash_size detect 0x0 RetroGamer.bin

Or use the esptool web version for a GUI-based flashing experience.

3. Add ROMs

Place your ROM files in the corresponding folders on the SD card (see SD Card Structure above).

---

SD Card Structure

ROM Folders

Save States

Save states are stored in:

/retro-go/saves/<system>/<rom_name>.sav<slot>

Example: /retro-go/saves/nes/Super_Mario_Bros.sav0

---

Usage

Launcher Controls

In-Game Controls

In-Game Menu

Press ESC during gameplay to open the in-game menu, which provides:

• Resume: Return to game
• Save State [0-3]: Save current state to selected slot
• Load State [0-3]: Load state from selected slot
• Turbo: Toggle fast-forward mode
• Sound: Toggle audio ON/OFF
• Palette: Change color palette (NES/GB only)
• Rotate: Rotate screen (Lynx only)
• Reset Game: Reset the current game
• Quit to Menu: Exit to launcher

WiFi File Manager

1. Create /retro-go/config/wifi.json on your SD card:

{
  "ssid0": "your-wifi-ssid",
  "password0": "your-wifi-password"
}

Up to 4 networks can be configured (ssid0-ssid3).

2. Connect your ESP32 to the network (WiFi connection happens automatically on boot).
3. Find the IP address in the boot screen (top-right corner).
4. Open your web browser and navigate to http://<IP_ADDRESS>/ to manage files.

Turbo Mode

Press Tab in-game to toggle turbo mode. When enabled:

• The game runs at approximately 2× speed
• Audio is continuous (no interruptions)
• Useful for skipping long cutscenes or grinding in RPGs

ROM Cache

Retro-Gamer uses a ROM cache to speed up boot times. The cache is stored at /retro-go/rom_cache.txt on your SD card.

When to refresh the cache:

• After adding new ROMs
• After removing ROMs
• If ROMs are not appearing correctly in the launcher

How to refresh the cache:

1. From the launcher: Press ESC to force a cache refresh and rescan all ROM directories.
2. Manual method: Delete the file /retro-go/rom_cache.txt from your SD card and restart the device. The cache will be rebuilt automatically.
3. From the web interface: Use the WiFi file manager to navigate to /retro-go/ and delete rom_cache.txt, then restart the device.

The cache is automatically updated when:

• The system detects changes in ROM directories (based on file modification timestamps)
• You press ESC in the launcher

---

Building from Source

Requirements

• ESP-IDF v4.4 or later
• FabGL Library

Build Instructions

1. Clone the repository:

git clone https://github.com/foky26/Retro-Gamer.git
cd Retro-Gamer

2. Set up the ESP-IDF environment:

. $HOME/esp/esp-idf/export.sh

3. Build the firmware:

idf.py build

4. Flash to your device:

idf.py flash

Build Metrics

---

Development

Debug System

The project includes a comprehensive debug system controlled by DEBUG_ENABLED:

// In config.h or debug.h
#define DEBUG_ENABLED 1  // Enable debug output
#define DEBUG_ENABLED 0  // Disable debug output

Debug macros available:

• DBG_ERROR(tag, format, ...) - Critical errors (red)
• DBG_WARN(tag, format, ...) - Warnings (yellow)
• DBG_INFO(tag, format, ...) - Information (white)
• DBG_VERBOSE(tag, format, ...) - Detailed debug (gray)

Architecture

Retro_Gamer.ino          ← Main: hardware init, launcher UI, game loop
├── src/
│   ├── debug.h           ← Debug system (Serial)
│   ├── nes_bridge.c/h    ← NES emulator bridge
│   ├── gb_bridge.c/h     ← Game Boy bridge
│   ├── sms_bridge.c/h    ← SMS/GG/SG-1000/ColecoVision bridge
│   ├── pce_bridge.c/h    ← PC Engine bridge
│   ├── snes_bridge.c/h   ← SNES bridge
│   ├── lynx_bridge.c/h   ← Atari Lynx bridge
│   ├── genesis_bridge.c/h ← Mega Drive bridge
│   ├── wifi_manager.*    ← WiFi + HTTP server
│   └── sound_control.c/h ← Audio control

Adding a New Emulator

1. Create a new bridge file in src/<system>_bridge.c
2. Implement the required bridge functions:
   • bool <system>_bridge_init(int sample_rate)
   • int <system>_bridge_load_rom(const char *path)
   • void <system>_bridge_run_frame(bool draw)
   • void <system>_bridge_set_input(uint32_t buttons)
   • void <system>_bridge_shutdown(void)
   • uint8_t* <system>_bridge_get_framebuffer(int *width, int *height)
   • int16_t* <system>_bridge_get_audio(int *num_samples)
3. Add the system to emu_type_t in Retro_Gamer.ino
4. Update getEmuType(), emuName(), and emuShortName()

---

Troubleshooting

---

Known Limitations

• Save States: Work for most systems but may have occasional issues with some games
• SNES Performance: ~15-25 FPS due to ESP32 CPU limitations
• VGA Color Depth: 64 colors (R2G2B2) — adequate for retro systems
• Audio: 8-bit DAC output at 22050Hz — acceptable for retro audio
• No Bluetooth: Bluetooth gamepad support is not implemented
• Single Player Only: No multiplayer/netplay support

---

Acknowledgements

Original Retro-Go (ducalex)

• The NES/GB/SMS emulators and base library were originally from the "Triforce" fork of the official Go-Play firmware by crashoverride, Nemo1984, and many others.
• The design of the launcher was originally inspired/copied from pelle7's go-emu.
• PCE-GO is a fork of HuExpress and pelle7's port was used as reference.
• The Lynx emulator is a port of libretro-handy.
• The SNES emulator is a port of Snes9x 2005.
• The Genesis emulator is a port of Gwenesis by bzhxx.
• PNG support is provided by lodepng.
• Special thanks to the ODROID-GO community for encouraging the development of retro-go!

FabGL Port (This Project)

• ducalex for creating and maintaining the original Retro-Go firmware
• UfkuAcik for the initial port to FabGL VGA framework
• FabGL library by Francesco Di Vittorio for providing the VGA, PS/2, and audio framework
• The FabGL community for their support and contributions

Additional Thanks

• All the emulator authors whose work made this project possible
• The open-source community for their continuous support and contributions

---

License

This project is licensed under the GNU General Public License v3.0 - see the COPYING file for details.

Exception:

• handy-go/components/handy (Lynx emulator, zlib license)

---

Contributors

---

Retro-Gamer - Bringing retro gaming to VGA displays, one pixel at a time! 🎮