esp-box-emu

NES EMULATOR

esp-box-emu

ESP-BOX-EMU is an open-source firmware and hardware project that turns an ESP32-S3-BOX (and ESP32-S3-BOX-3) into a handheld retro emulation console. It runs a set of on-demand emulator cores (NES, Game Boy / Color, Sega Master System / Game Gear, Genesis / Mega Drive, MSX 1/2) plus a Doom port, presenting a polished LVGL UI, boxart support, save states, and

Jump to download ↓Jump to setup guide ↓

esp-box-emu emulator screenshot.

nesPRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why this project exists

Designed to make a compact, buildable Game Boy-style handheld using Espressif’s ESP32-S3-BOX hardware. It integrates multiple small emulator cores into a single firmware image with on-demand core loading and SD-based ROM management so users can run many retro systems without reflashing.

BEST FOR

What it does best

On-device, portable multi-system play on ESP32-S3 hardware with a touchscreen/menu UI, boxart and save-state integration, and an emphasis on running many cores on the constrained ESP32-S3 (including a dual-core Genesis port to reach playable speed).

The people behind esp-box-emu

History and status

The project is hosted on GitHub under esp-cpp/esp-box-emu and documents a complete build, hardware add-on, and ready-made one-time programmer distributed via GitHub Releases. The README describes supported systems (NES, GB/GBC, SMS/GG, Genesis/Mega Drive, MSX, plus Doom), notes that cores and games load on demand at runtime, and provides build/flash instructions that use ESP-IDF. Releases include prebuilt 'programmer' binaries for Windows/Mac/Linux to perform the one-time programming step. The repository uses git submodules and references ESP-IDF as the build system. The project appears active with releases and recent commits at the time of profile creation; consult the repository for up-to-date activity and release details.

What esp-box-emu supports

NES (Nintendo Entertainment System)
Game Boy / Game Boy Color
Sega Master System / Game Gear
Sega Genesis / Mega Drive
MSX 1 / 2
Doom port (WAD required separately)

Download and availability

OFFICIAL DOWNLOADS

Get esp-box-emu

Official downloads (programmer binaries and release artifacts) are published on the project's GitHub Releases page. The firmware and source are available from the repository; there are prebuilt programmer utilities for Windows, macOS, and Linux distributed with each release.

Get esp-box-emu ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

esp-box-emu setup guide

Setup note: Practical setup notes — follow these repository-supplied steps and requirements carefully. This guide assumes you own an ESP32-S3-BOX or ESP32-S3-BOX-3 and that you will provide your own ROM files and any required Doom WAD. Do not expect copyrighted game ROMs, firmware, or BIOS files to be included with the project.

1) Read the repository README and releases: Open the esp-cpp/esp-box-emu GitHub README and Releases. The README lists supported hardware, features, SD card layout, and provides links to release artifacts (including a platform-specific one-time 'programmer' binary).
2) Prepare host toolchain and ESP-IDF: Install Espressif's ESP-IDF toolchain and prerequisites for your OS (the README instructs building via idf.py). Ensure your ESP-IDF version matches any constraints documented in the repository or submodules. Install the cross-toolchain and add idf.py to your PATH per Espressif's official docs before attempting to build or flash.
3) Clone the repo with submodules: Clone recursively so submodules are fetched: git clone –recurse-submodules git@github.com:esp-cpp/esp-box-emu (or use the HTTPS clone URL). If you forgot –recurse-submodules, run: git submodule update –init –recursive.
4) Use the provided one-time programmer (recommended for quick start): For a quick play-first experience, download the 'programmer' release for your OS from the repository's Releases page, unzip it, and run the programmer binary as documented in the README (Windows: double-click the .exe; macOS/Linux: run the binary from a terminal). The programmer performs the one-time flashing necessary to convert an ESP32-S3-BOX into a handheld device running the firmware image shipped in that release.
5) Building and flashing from source (developer / custom builds): If building from source, open a terminal in the repo and use idf.py: idf.py -p PORT flash monitor — replacing PORT with your board's serial port. The firmware uses ESP-IDF's build system. Use idf.py monitor to view serial output and Ctrl-] to exit the monitor. Follow any additional build instructions in the repository (components, patches, or submodule-specific steps).
6) Prepare micro-SD card with ROMs and metadata: Format the micro-SD card as FAT. Copy your own ROM files with the correct extensions (.nes, .gb, .gbc, .sms/.gg, .smd/.bin/etc. for Genesis depending on core), boxart images (.jpg), and a metadata.csv mapping filenames to boxart and display names. The README includes an example metadata.csv and a boxart resize script that makes 100 px-wide boxart suitable for the UI.
7) File naming, core selection, and save-states: The emulator auto-selects the core by ROM extension. Save states and automatic save screenshots are stored on the SD card; the README documents the save system and menus. Do not expect the project to include commercial ROMs or WAD files — you must provide legally obtained game images and any required Doom WAD.
8) Hardware add-on and assembly (optional): If you intend to build the full Game Boy–style handheld, the repository includes 3D printable case files and PCB/Eagle/KiCad data for the add-on board. The README lists assembly guidance, recommended screws, and parts. If you do not have the add-on, the firmware can still be used on stock ESP32-S3-BOX hardware but features and inputs may vary.

Software reminder: This project requires the Espressif ESP-IDF toolchain and compatible host toolchain. Releases include prebuilt 'programmer' tools but building from source requires installing ESP-IDF and matching any version constraints listed in the repository.