esp-box-emu

The ESP-BOX-EMU is a gameboy-inspired add-on for the ESP32-S3-BOX and ESP32-S3-BOX-3 which provides:

Game Controller (gamepad input with a/b/x/y, start/select, d-pad)
LiPo battery (1000 mAh) with charging over USB-C
Micro-SD card for storing roms, boxart, and savegames
TinyUSB MSC device wrapping the uSD card
Volume +/- buttons
USB-C port for charging and programming
Haptics (using LRA powered by DRV2605)
Custom software stack including:
- NES Emulator (nofrendo)
- Gameboy / Gameboy Color emulator (gnuboy)
- Sega Master System / Game Gear emulator (smsplus)
- Genesis emulator (gwenesis); NOTE: this is a WIP and does not support full-speed / sound / savestates yet.
- LVGL main menu with rom select (including boxart display) and settings page (all generated from Squareline Studio)
- LVGL emulation paused menu with save slot select, save slot image display, and configuration (sound, brightness, display, etc.). (all generated from Squareline Studio)

box-emu-input-refactor-compressed.mp4

esp-box-emu.housing.and.assembly.v162-compressed.mp4

This project is designed to be in the same form factor as the Gameboy Color and to reuse the same button plastics and membranes for a good play feel.

The housing is designed to be 3d printed (I use PLA or PETG on Prusa i3 mk3+), and assembled with M3 screws.

These are the parts / sources I'm using for stock / replacement GBC membranes and buttons.

Link to Fusion 360 CAD (Free Version):

The printable files can be found in the ./mcad folder or can be downloaded from printables.

The electrical files can be found in the ./ecad folder.

Features

This project has the following features (still WIP):

Cloning

Since this repo contains a submodule, you need to make sure you clone it recursively, e.g. with:

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

Alternatively, you can always ensure the submodules are up to date after cloning (or if you forgot to clone recursively) by running:

git submodule update --init --recursive

Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py -p PORT flash monitor

(Replace PORT with the name of the serial port to use.)

(To exit the serial monitor, type Ctrl-].)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

Rom Setup and Configuration (uSD Card)

Format your uSD card as a FAT filesystem and add your roms (.nes, .gb, .gbc), images (.jpg), and metadata.csv.

ROM Images

For ease of use, there is a ./boxart/source/resize.bash script which will resize all jpg images in the boxart/source folder to be 100x px wide (keep aspect ratio but make width 100 px) and put the resized versions in the boxart folder. You can then copy them onto your sd card and update your metadata file appropriately.

Metadata.csv format

<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

esp-cpp / esp-box-emu

esp-box-emu

Features

Cloning

Build and Flash

Rom Setup and Configuration (uSD Card)

ROM Images

Metadata.csv format

References and Inspiration:

Other NES Emulators

Other Genesis Emulators

Useful Background / Information

About

Languages