Box emu

esp-box-emu

A pocket-sized, Game Boy-style retro emulation handheld built around the ESP32-S3-BOX. Drop in a micro-SD card of ROMs and play NES, Game Boy / Color, Sega, MSX, and Genesis games — plus a full-speed port of Doom — on hardware you can 3D print and build yourself.

https://github.com/user-attachments/assets/2d3da6ea-2e80-42c3-bbd6-5a2c59601201

Table of Contents

• esp-box-emu
  • Overview
  • Emulators
  • Gallery
  • Quick Start — Play It
  • Build the Hardware
  • Build the Firmware
  • ROMs and SD Card Setup
    • Boxart images
    • metadata.csv format
  • Features and Roadmap
  • References and Inspiration
  • License

Overview

The ESP-BOX-EMU turns an ESP32-S3-BOX or ESP32-S3-BOX-3 into a handheld retro game console. A custom add-on board and 3D-printed shell wrap the BOX in a Game Boy Color form factor — real d-pad and buttons, battery, haptics, and a micro-SD slot — and the firmware runs a stack of emulators behind a polished LVGL interface with boxart, save states, and settings.

Highlights

• 🎮 Six systems + Doom — NES, Game Boy / Color, Sega Master System / Game Gear, Sega Genesis, and MSX 1/2 emulators, plus a full-speed Doom port — all with sound.
• 🧬 Full-speed Genesis — a custom dual-core port of gwenesis splits the emulation across both of the ESP32-S3's cores (CPU + video on one, the sound unit on the other) for full-speed Sega Genesis / Mega Drive with audio.
• ⚡ No reboots — every core and game loads on demand right from the menu, so you can jump between titles and even different systems without ever restarting the device.
• 🕹️ Real controls — d-pad, A/B/X/Y, Start/Select and volume buttons in a familiar Game Boy Color layout; the emulator is auto-selected from the ROM file extension.
• 💾 Load from SD — keep ROMs, boxart, and save states on a micro-SD card, and mount the card over USB-C as a mass-storage drive (TinyUSB MSC).
• 💤 Save anywhere — up to 5 save slots per game, each with an auto-generated screenshot shown in the load menu.
• 🔋 Portable — 1000 mAh LiPo battery with USB-C charging.
• 📳 Haptics — LRA haptic feedback (DRV2605), including in-game effects in Doom (weapon fire, taking damage, pickups, and more).
• 🖼️ Polished UI — LVGL menus for ROM select (with boxart) and settings (sound, brightness, display scaling, haptics), designed in Squareline Studio.
• 🛠️ Fully open hardware — 3D-printable GBC-style case and an open PCB (Fusion/Eagle and atopile + KiCad), all included in this repo.

Emulators

The right emulator is chosen automatically from each ROM's file extension, and games load on demand straight from the menu — no reboot required. Pick a title, play, then drop back to the menu and launch a different game (or a completely different system) without ever restarting the device. Every core runs with audio, and several offer an Unlocked mode (toggle with the X button) that removes the frame-rate cap for maximum speed.

🧬 Full-speed Genesis on the S3. The Genesis core ships with a custom dual-core modification of gwenesis that spreads the workload across both of the ESP32-S3's CPU cores: core 0 runs the 68000 CPU and VDP (video), while core 1 runs the sound unit (Z80 + YM2612 FM synth + PSG). Sound-chip writes are queued and applied in order on core 1, which lets Genesis / Mega Drive games run at full speed with audio — something a single core can't keep up with.

Gallery

https://github.com/esp-cpp/esp-box-emu/assets/213467/3b77f6bd-4c42-417a-9eb7-a648f31b4008

https://github.com/esp-cpp/esp-box-emu/assets/213467/a3d18d03-c6a1-4911-89d1-e18119e8cc03

Quick Start — Play It

Already have the add-on hardware (or an ESP32-S3-BOX you want to flash)? You don't need to build anything from source — a prebuilt one-time programmer is published with every release.

1. Download the programmer for your OS (windows, macos, or linux) from the latest releases page.

2. Unzip it.

3. Run it: double-click the .exe on Windows, or run it from a terminal on macOS / Linux, e.g.:

   ./esp-box-emu_programmer_v1.0.0_macos.bin

   (The version in the filename matches the release you downloaded.)

Then set up a micro-SD card with your ROMs and you're ready to play.

Build the Hardware

The add-on is designed to match the Game Boy Color form factor and reuse GBC button plastics and silicone membranes for an authentic feel. The shell is meant to be 3D printed (PLA or PETG on a Prusa i3 mk3+) and assembled with M3 screws.

Case / mechanical — printable files are in ./mcad or on Printables. CAD is on Fusion 360 (free viewer):

Electronics — schematic and layout files are in ./ecad, provided as both Fusion/Eagle files and atopile + KiCad sources. You can also order the board directly:

GBC replacement buttons / membranes used for a good play feel:

• Silicone pads for Game Boy Color (1)
• Silicone pads for Game Boy Color (2)
• Game Boy Color button plastics

Build the Firmware

This repo uses submodules, so clone it recursively:

git clone --recurse-submodules git@github.com:esp-cpp/esp-box-emu

If you already cloned it non-recursively (or forgot the flag), pull the submodules with:

git submodule update --init --recursive

Then build, flash, and open the serial monitor with ESP-IDF:

idf.py -p PORT flash monitor

Replace PORT with your board's serial port. To exit the monitor, type Ctrl-].

Measuring performance and memory

The firmware prints greppable one-line reports on the serial console so a captured play session doubles as a profile:

• [mem] phase=boot|menu|launch|quit ... — internal RAM / PSRAM free and largest free block at each phase, with [mem] delta ... lines at launch and quit relative to the menu (a non-zero delta after quitting is a leak or fragmentation).
• [mem] block|region|task phase=... — at boot and launch, every internal-RAM block above a threshold (labelled with the task whose stack it is), each registered heap region's used/free/largest, and every task's stack high-water mark (stack_free_min, repeated at quit after a full play session).
• [genesis mem] NAME: N bytes -> INTERNAL|PSRAM — where each big emulator buffer landed (the Genesis gets noticeably slower when its hot buffers fall back to PSRAM).
• [genesis perf] fps=.. frame=..us 68k=..us vdp=..us convert=..us barrier=..us ... — per-frame time breakdown averaged over the last 300 frames (~5 s): 68000, VDP render, RGB565 conversion, time core 0 spends waiting for the core-1 sound unit, present/audio, pacing sleep, late=/skipped=/dropped= frame counts (skipped = emulated without rendering because the panel could not show the frame), blit= (video task time per displayed frame), the core-1 sound unit's own frame time, and Z80 counters (irq= V-ints taken, busreq=, halted= scanline slices lost to a held bus, wto= handshake timeouts, ymw= Z80→YM2612 writes). Compile with GENESIS_PERF=0 to remove it.
• [display] lcd spi clock: N Hz — the clock the LCD SPI device actually got (the ESP32-S3 can only divide 80 MHz by integers, so a 60 MHz request runs at 40 MHz: 320×240×16bpp is ~31 ms per frame, the panel's ~31 fps ceiling).

Capture and summarise a session (performance PRs should include a before/after from the same game and the same ~1 minute of play):

python tools/serial_capture.py PORT --out before.log --until "delta phase=quit"
# ... flash the change, play the same section again ...
python tools/serial_capture.py PORT --out after.log --until "delta phase=quit"
python tools/perf_report.py before.log after.log

perf_report.py prints each run's launch/quit memory, buffer placement, and the perf-line averages side by side with deltas.

ROMs and SD Card Setup

Format a micro-SD card as FAT and add your ROMs (.nes, .gb, .gbc, …), boxart images (.jpg), and a metadata.csv file (see the example metadata.csv).

Boxart images

Boxart displays best at 100 px wide. The ./boxart/source/resize.bash script resizes every .jpg in boxart/source to 100 px wide (preserving aspect ratio) and writes the results to the boxart folder. Copy those onto the SD card and reference them from your metadata file.

Dark Forces setup

Dark Forces is played with the original (purchased) game data; the engine does not include it. Copy the DOS install files onto the SD card into a single folder, for example darkforces/:

darkforces/DARK.GOB
darkforces/SOUNDS.GOB
darkforces/SPRITES.GOB
darkforces/TEXTURES.GOB
darkforces/LFD/*.LFD       (menus, briefings and cutscenes)

Then reference DARK.GOB from metadata.csv:

darkforces/DARK.GOB, boxart/darkforces.jpg, Star Wars: Dark Forces

Settings (settings.ini) and agent / save files are written to the same folder.

PICO-8 setup

PICO-8 carts are plain .p8 text files or .p8.png cartridge images. Put them in a folder on the card (for example pico8/) and reference them from metadata.csv:

pico8/celeste.p8, boxart/celeste.jpg, Celeste Classic

Carts that use cartdata() save to pico8/cdata/. The 128x128 screen shows 1:1 in the "original" video mode and scaled to 240x240 in "fit". Multi-cart games that load("#id") their other carts work when those carts sit in the same folder as id.p8.png / id.p8.

What to expect: the Lua interpreter runs at roughly 1.3M instructions per second on the S3 (its heap lives in PSRAM), enough for carts of Celeste's weight at full speed, but CPU-heavy carts close to PICO-8's limit run at a few frames per second. Save states work (the cart's Lua heap and PICO-8 RAM are snapshotted between frames); carts' own cartdata() saves are kept separately; there is no mouse or keyboard.

metadata.csv format

Each line maps a ROM to its boxart and display name:

<rom filename>, <rom boxart filename>, <rom display name>

Example:

mario.nes, boxart/mario.jpg, Mario Bros.
super_mario_1.nes, boxart/super_mario_bros_1.jpg, Super Mario Bros.
super_mario_3.nes, boxart/super_mario_bros_3.jpg, Super Mario Bros. 3
zelda.nes, boxart/zelda1.jpg, The Legend of Zelda
zelda_2.nes, boxart/zelda2.jpg, The Legend of Zelda 2: the Adventure of Link
mega_man.nes, boxart/megaman1.jpg, MegaMan
metroid.nes, boxart/metroid1.jpg, Metroid
pokemon_blue.gb, boxart/pokemon_blue.jpg, Pokemon Blue
pokemon_red.gb, boxart/pokemon_red.jpg, Pokemon Red
pokemon_yellow.gbc, boxart/pokemon_yellow.jpg, Pokemon Yellow
links_awakening.gb, boxart/tloz_links_awakening.jpg, The Legend of Zelda: Link's Awakening
links_awakening.gbc, boxart/tloz_links_awakening_dx.jpg, The Legend of Zelda: Link's Awakening DX

Features and Roadmap

A checklist of what's implemented and what's still in progress.

Emulation

• Auto-select emulator by ROM extension: NES, GB/GBC, SMS/GG, MSX, Genesis, Doom, Dark Forces, PICO-8
• On-demand core loading — every emulator and game loads at runtime with no reboot needed to switch games or systems
• Custom dual-core Genesis (gwenesis): 68000 + VDP on one ESP32-S3 core, sound unit (Z80 + YM2612 + PSG) on the other, for full-speed audio and gameplay
• Doom haptic feedback :rocket:
• Save state (with automatic save-screenshot creation to the SD card)
• Load state — up to 5 slots per game, with save-screenshot previews
• Shared-memory system so many emulators can be built in together while keeping their hot state in fast internal RAM
• Dark Forces (The Force Engine port; software renderer with sound and music)
• SNES emulator (WIP)

User interface

• LVGL ROM-select menu with boxart and title, navigable by controller
• LVGL settings menu (volume, video, haptics) and in-game pause menu
• GUI data (titles + boxart) loaded from the metadata file
• Squareline Studio source for the LVGL boilerplate (SLS files, generated files)

Video and audio

• Emulator framebuffers in SPIRAM, with queued screen transfers for maximum draw speed
• Video scaling with ORIGINAL, FIT, and FILL display modes
• Audio output over I2S via the es8311 codec (codec component)
• Mute button toggles audio while a ROM is running
• Haptic feedback via a DRV2605-driven LRA
• Decorative graphics in the black borders during NES / GB/C emulation (WIP)

Storage and input

• micro-SD (FAT) filesystem over SPI
• TinyUSB MSC device to expose the SD card to an attached USB host
• Memory-mapping of the selected ROM from storage into a raw data partition (SPI flash)
• D-pad + A/B/X/Y + Start/Select input (MCP23x17 on v0 hardware, AW9523 on v1)
• Touchscreen input (tt21100 component)

Hardware

• Control-board schematic / layout: joystick / d-pad / buttons (via I²C I/O expander + ADC), battery, charger, DRV2605 haptics, micro-SD, boost converter, and USB 2.0 passthrough from USB-C
• Case CAD in the GBC footprint: USB-C port, micro-SD slot, Start/Select, ABXY, and D-pad in familiar locations

References and Inspiration

Other NES emulators

• https://github.com/nesemu/NESemu
• https://github.com/NiwakaDev/NIWAKA_NES
• https://github.com/kanathan/plainNES
• https://github.com/blagalucianflorin/lbnes
• https://github.com/daniel5151/ANESE
• https://github.com/Grandduchy/YaNES

Other Genesis emulators

• https://github.com/h1romas4/m5stack-genplus
• https://github.com/libretro/blastem

Useful background / information

• https://github.com/alnacle/awesome-emulators
• https://www.zophar.net/nes.html
• https://yizhang82.dev/nes-emu-overview
• https://www.gridbugs.org/zelda-screen-transitions-are-undefined-behaviour/
• https://bgb.bircd.org/pandocs.htm
• https://github.com/pebri86/esplay-gb
• https://github.com/hex007/esp32-gnuboy
• https://github.com/rofl0r/gnuboy
• https://github.com/zid/gameboy
• https://github.com/Jean-MarcHarvengt/MCUME
• https://github.com/OtherCrashOverride/go-play
• SNES signal reference
• NES signal reference
• Genesis signal reference
• DIY Game Boy

License

This project is licensed under the terms in LICENSE.