InkBoy README

The project's README from github.com/kuslota/InkBoy. As one markdown file: README.md.

InkBoy

InkBoy runs Game Boy games on a Waveshare ESP32-S3 e-paper board at about 30 fps. Choose fast dithered black and white or four-shade grayscale. It includes an SD ROM browser, speaker audio, automatic resume, tunable display presets and an optional FPS counter.

Watch the video

Planned, not implemented yet

Hardware

Part Requirement
Waveshare ESP32-S3-ePaper-1.54 V2 200×200 e-paper screen, speaker and microSD slot
microSD card FAT32, for ROMs, saves and presets
InkBoy controller Custom ESP32-C3 gamepad, connected over BLE or a USB-C data cable

Only the custom InkBoy controller is currently supported. Generic Bluetooth and USB HID gamepads are not supported.

Experimental display drive

[!WARNING] Use at your own risk. Custom waveforms and high refresh rates may cause permanent image retention or panel damage. Long-term panel life has not been validated. This applies to default presets, source builds and prebuilt firmware; software checks do not guarantee panel safety.

Quick start

1. Build and flash

Install ESP-IDF v6.1 with Espressif Installation Manager and open its IDF Terminal. Navigate to where you want the project saved (no spaces in the path), connect the board with a USB-C data cable, then run:

git clone --recursive https://github.com/kuslota/InkBoy.git
cd InkBoy
idf.py set-target esp32s3
idf.py build
idf.py flash

This creates an InkBoy folder in your current directory. See the flashing guide for folder setup, subsequent builds, prebuilt firmware and USB recovery.

2. Add games

Format the SD card as FAT32 and copy your ROMs into /roms. Power the board off before inserting or removing the card. The Big2Small puzzle game is included: copy roms/big2small.gb onto the card. It has its own GPL licence; no proprietary game ROMs are bundled.

3. Connect the controller

Choose Settings → Controller → Connection:

If your button wiring differs, use Settings → Controller → Map buttons.

Controls and saves

Input In menus
Controller Up / Down Move selection
Controller A / Start; B Select; back
PWR tap; hold 0.7 s Next item; back
BOOT tap; hold 0.7 s Select; previous item

During gameplay, the controller provides the usual Game Boy buttons. Press BOOT or PWR to pause, save and return Home.

Each pause replaces the game's single resume checkpoint. Continue saved restores it; manual save slots and rollback are not available. Use Home → Power off before removing the SD card. BOOT wakes the board.

The controller badge on Home and in Controller settings shows connected, WAIT (disconnected), OFF (service unavailable), or USB: PC (serial/flashing enabled). Full controls, badge meanings and save files are in the controls guide.

USB controller mode

The controller shares the port with flashing and serial. Unplugging it does not free the port automatically.

To flash: hold BOOT + PWR together for at least 2 seconds until the badge shows USB: PC, disconnect the controller, connect your computer, then flash normally. The saved USB preference is unchanged. Restarting returns to controller mode; to return without restarting, disconnect the computer and repeat the gesture.

For repeated flashing, logging or automation, select Bluetooth first. USB then stays free across restarts. Some serial tools reset the board when opening the port. See USB switching and recovery for details.

Compatibility

Game Boy (DMG) games and dual-mode cartridges in DMG mode, up to 2 MiB. Color-only games and RTC cartridges are not supported. Busy scenes may drop below 30 fps; grayscale can leave faint trails. See full limitations.

More details

Contributing

Found display settings that work better? Open a pull request with your preset or changes to pulse counts, HOLD, history corrections or shade transitions. Include your board/display model, what you tested, and what improved or got worse; comparison photos or videos are welcome. See the tuning guide for the available settings.

Credits

Full license information is in THIRD_PARTY_NOTICES.md.

License

MIT, see LICENSE. Third-party components keep their own licenses.

InkBoy (kuslota/InkBoy)

diy
Searching Database…

174 ·GitHub
InkBoy
What is this?InkBoy is firmware that runs Game Boy games on a Waveshare ESP32-S3 e-paper board at about 30 fps, with dithered black-and-white or four-shade grayscale rendering.
Is this an app I install, or do I need special hardware?It's firmware for a specific piece of hardware, not a phone or desktop app: a Waveshare ESP32-S3 e-paper board with a built-in speaker and microSD slot, paired with a custom InkBoy gamepad.
How do I get it running?Install ESP-IDF v6.1 via the Espressif Installation Manager, open its IDF Terminal, then build and flash the project to the board over a USB-C data cable. Format a microSD card as FAT32 and copy ROMs into a /roms folder.
What hardware do I actually need?A Waveshare ESP32-S3-ePaper-1.54 V2 board, a FAT32-formatted microSD card for ROMs and saves, and the custom InkBoy controller (an ESP32-C3 gamepad connected over BLE or USB-C) — generic Bluetooth or USB HID gamepads aren't supported.
Any catches before I build one?The display driving is experimental — custom waveforms and high refresh rates can cause permanent image retention or panel damage, and long-term panel life isn't validated. On top of that, only DMG Game Boy games up to 2MiB work (no Color-only or RTC cartridges), and busy scenes can drop below 30 fps.
What game is included to test with?Big2Small, a puzzle game under its own GPL license, is bundled as roms/big2small.gb; no proprietary ROMs are included.
Where does the emulator core come from?It comes from CrankBoy and Peanut-GB through the esp32-gameboy component, with PaperBoy by Zephray having inspired the per-pixel driving approach. Sound uses the MiniGB APU from Peanut-GB.
How does saving a game work?Pausing replaces the game's single resume checkpoint, which 'Continue saved' restores. There are no manual save slots or rollback.
Can I flash new firmware without unplugging the controller?Hold BOOT and PWR together for at least 2 seconds until the badge shows 'USB: PC', then disconnect the controller and connect your computer. Switching the controller to Bluetooth mode keeps the USB port free across restarts for repeated flashing.
What are similar projects?frank-386, keybytes, crosspoint-reader, esp32sim, PixelFonts, MicroManipulatorStepper, esp-sdr, mu300-linux
Which topics is it in?diy, esp8266, eink, bluetooth-le, esp32-s3, retro, usb, microcontroller, bluetooth, emulation, retrogaming, embedded-systems
Creator
kuslota
Size
0.9 MB
Stars
174
Updated
CommitOct 22
Age
20d
Commits · 90 Days