ryuzaki-mrl / espeon

Gameboy emulator for the ESP32

Espeon is a gameboy emulator for Espressif's ESP32 SoC.

This project started out as a rewrite in order to be more accurate and optimized for the ESP32.

About Espeon

This emulator is being developed primarily with the M5Stack device in mind. You can find more info about it here: https://m5stack.com/

M5Stack Arduino API, M5Stack TreeView library, and M5Stack FACES are required.

If you don't own a M5Stack, feel free to adapt this codebase to your setup.

Recommended setup:

• A board containg an ESP32 chip and at least 4MB (32Mbit) of SPI flash, plus the tools to program it
• A 320x240 ILI9341 display, controllable by a 4-wire SPI interface
• Some kind of I2C gamepad
• SD card reader (optional)

Compiling Espeon

To compile for the M5Stack, you'll need to:

• Set up your Arduino IDE for the M5Stack
• (OPTIONAL) Get a copy of the gameboy's bootrom as a const array called gb_bios
• (OPTIONAL) If you wish to bundle Espeon with a ROM, drag and drop the ROM file into rom2h.bat (max size of 512 KB)
• Run espeon.ino
• Compile the sketch and upload it to the board

Recommended: upload directly via esptool by using the provided partition scheme, or by using M5Burner.

A precompiled release will be provived for each new version.

Running games

If running on a M5Stack, you'll be presented with a menu where you can choose to either load a ROM from the SD card into the ESP32's flash (maximum of 2MB), or boot up the currently flashed ROM.

If either fails, the bundled ROM will be used instead (maximum of 512 KB).

Credits

• Code structure inspired by zid.
• Base Arduino code and ROM bundle script by lualiliu.
• M5Stack TreeView UI library and example code by lovyan.
• Espeon artwork by natsuki-o-bento.

Features

• Fully taking advantage of both ESP32 cores (currently faster than the real gameboy, needs some tinkering)
• Flash a ROM from the SD card
• SRAM is saved to the SD card

TODO:

• Rewrite CPU/LR35902 code
• Audio emulation
• Object-oriented approach
• SRAM autosaving (currently needs a button press)
• Customizable palette and border

espeon's Issues

It works :)

found my way, working fine now :)
have a nice week-end.

Linux feedback

Hello and thanks for this great project !

Here's some unsollicited feedback from my attempt to get this working from Linux Ubuntu (16.04).

• Arduino IDE isn't happy with the lowercase .ino filename, I've renamed espeon.ino to Espeon.ino to stop the IDE from complaining :-)

• Before realizing I could install bin2h with apt, I used the xxd utility to get the bios in a C format:

    xxd -i gbc_bios > gbbios.h
  

• Also the following commands:

    ffmpeg -vcodec png -i "gbborder.png" -vcodec rawvideo -f rawvideo -pix_fmt rgb565 "gbborder.raw"
    bin2h -cz gbborder<"gbborder.raw" > gbborder.h
  

... produced a 153600 bytes gborder.raw file (921652 bytes for the .h file)
and the dreadful DRAM segment data does not fit. compilation error.

I've used the built-in jpeg decoder M5.Lcd.drawJpg as a workaround, not sure about the performances hit but that produced a more ideal memory footprint (2804 bytes) and got me out of the compilation error.

• The SD Updater seems to fit with the gameboy menu, but I haven't tested any game yet (using a M5Fire and no Faces stick around)

I'll edit this post with the followup, trying to get my hands on some roms to verify I'm using the correct bios version (can you share you md5sums?) :D

[edit 1] : as expected the rom won't load when the sketch is compiled with the basic Arduino IDE board/partitions settings, adding some debug statements to the code (#include <esp32-hal-log.h> along with log_e(), log_w() and log_i()) was helpful to find out the reason.

Not sure if this is feasible from the UI though, thinking about platformio 🤔

adding CardKB support

@Ryuzaki-MrL - it is possible to add CardKB to control Espeon?
M5Stack_TreeView support this keyboard...
e.g. https://github.com/lovyan03/M5Stack_TreeView/blob/master/examples/simple/simple.ino#L14

...so, it would be cool to control Espeon by this mini keyboard

https://m5stack.com/products/cardkb-mini-keyboard

Running too fast

Screen refresh rate should be close to 60Hz.

Missing File: gbborder.h

Upon Compile

gbfiles.h:24:23: fatal error: gbborder.h: No such file or directory
compilation terminated.
exit status 1
gbborder.h: No such file or directory

Usability with the WIO terminal dev board?

I know this library is primarily written for ESP32, specifically the m5stack core, but is there any reason it could not run on a wio terminal device board. The wio runs at half the speed and has a much reduced amount of ram, but if you drop the bundled ROM and overclock the WIO to 200mhz it should run albeit with issues in terms of speed.

Cant open file system or flashed rom.

Ive recently gotten NES running on the m5stack, and now I'm trying to get GBA to run on it, I've flashed the 4 bin files using esptools, along with arduino IDE. The software runs, but when I try to load a flash from, it says "espeon fainted, rom_init failed e.t.c.". When I try to click on "Load Rom (SD Card)" nothing happens. I've checked the sd card as well, it isn't corrupt.

Rom loaded correctly, but game not starting

Hello, thanks for this nice project.
My roms are properly loaded , I can see the GameBoy picture, but there is blank or black full screen displayed depending on the loaded rom.
Do I need a game controller to launch the games properly or the games introduction are supposed to be displayed with no further action ?

Thanks

Not a real issue: would it possible to use the whole screen without the Gameboy picture

Hello,

It works perfectly, but the section is quite small because of the Gameboy frame picture.
Would it possible to use the full screen size?

Thanks,

Missing File: gbbios.h

Upon attempting to compile

gbfiles.h:17:21: fatal error: gbbios.h: No such file or directory
compilation terminated.
exit status 1
gbbios.h: No such file or directory

[question] landing page and walkthrough

Hey! this is such a super awesome project! I was trying to get everything setup and realized that I had documented some pretty good steps with pictures to getting this project setup, is that something you were interested in having someone contribute?

ROM Won't Load

ROM (Any) Won't Load

Including flash or sd card

To reproduce

Edit the gbfiles.h file and comment out the three defines (since i don't have a bios file)

/* Uncomment this to include a fallback ROM */
// #define USE_INTERNAL_ROM
// #define USE_INTERNAL_BIOS
// #define USE_INTERNAL_BORDER

Attempt to load from sd card - fails

Flashed to M5 Directly as per partition table - fails

python (path to my esp-idf toolchain)/esptool.py --chip esp32 --port /dev/cu.SLAB_USBtoUART --baud 2000000 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0x110000 dinosofflineadventure.gb

'gb_bios' was not declared in this scope

im not sure whats going on here i use original dmg bios and none im able to find works do you have a specific set you use?

Wrong Library Versions

With current versions of M5 libraries and ESP toolchains the project does not run on the ESP32. I managed to get a usable menu with ESP 1.0.6 but the emulation does not work. What versions of the libraries are required to build the Emulator?

Cant open file system or flashed rom.

Ive recently gotten NES running on the m5stack, and now I'm trying to get GB to run on it, I've flashed the 4 bin files using esptools, along with Arduino IDE. The software runs, but when I try to load a flash from it, it says "espeon fainted, rom_init failed, etc.". When I try to click on "Load Rom (SD Card)" nothing happens. I've checked the sd card as well, it isn't corrupt. Neither can I interact with the Settings button.