kuslota / InkBoy

# 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.
## Planned, not implemented yet
- Support for generic Bluetooth HID gamepads, beyond the custom InkBoy controller.
- Better USB connectivity handling, to make switching between controller use and flashing/serial easier.
## 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:
 [code] 
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**:
- **Bluetooth:** turn on the custom controller. InkBoy finds it automatically as `ESP32 Gamepad`.
- **USB:** connect the controller with a USB-C to USB-C **data** cable and select USB.
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,