InkBoy README

README проекта с github.com/kuslota/InkBoy. Одним файлом markdown: 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)

Ищем в базе…

191 ·GitHub
Что это такое?InkBoy — это прошивка, которая запускает игры для Game Boy на e-paper плате Waveshare ESP32-S3 примерно с 30 кадрами в секунду, с выводом изображения в чёрно-белом варианте с дизерингом или в четырёхтоновых оттенках серого.
Это приложение, которое мне нужно установить, или нужно особое оборудование?Это прошивка для конкретного устройства, а не приложение для телефона или компьютера: плата Waveshare ESP32-S3 e-paper со встроенным динамиком и слотом microSD, в паре с самодельным геймпадом InkBoy.
Как это запустить?Установите ESP-IDF v6.1 через Espressif Installation Manager, откройте его IDF Terminal, затем соберите проект и загрузите его на плату по USB-C кабелю для передачи данных. Отформатируйте карту microSD в FAT32 и скопируйте ROM-файлы в папку /roms.
Какое оборудование мне действительно нужно?Плата Waveshare ESP32-S3-ePaper-1.54 V2, карта microSD с файловой системой FAT32 для ROM-файлов и сохранений, а также самодельный контроллер InkBoy (геймпад на ESP32-C3, подключаемый по BLE или USB-C). Обычные Bluetooth или USB HID геймпады не поддерживаются.
Есть ли подвохи, о которых стоит знать до сборки?Управление дисплеем находится в экспериментальной стадии: пользовательские волновые формы и высокая частота обновления могут привести к постоянному остаточному изображению или повреждению панели, а долговечность панели в долгосрочной перспективе не проверена. Кроме того, работают только игры для DMG Game Boy размером до 2 МиБ (не поддерживаются картриджи только для Color и с RTC), а в сложных сценах частота кадров может падать ниже 30 fps.
Какая игра включена для тестирования?Big2Small — головоломка под собственной лицензией GPL, она входит в состав как roms/big2small.gb; проприетарные ROM-файлы не включены.
Откуда взято ядро эмулятора?Оно взято из CrankBoy и Peanut-GB через компонент esp32-gameboy, а идея покадрового управления дисплеем вдохновлена PaperBoy от Zephray. Звук использует APU MiniGB из Peanut-GB.
Как работает сохранение игры?Пауза заменяет единственную контрольную точку продолжения игры, которую восстанавливает пункт «Continue saved». Ручных слотов сохранения или отката нет.
Можно ли прошить новую прошивку, не отключая контроллер?Зажмите BOOT и PWR вместе не менее чем на 2 секунды, пока на значке не появится надпись «USB: PC», затем отключите контроллер и подключите компьютер. Переключение контроллера в режим Bluetooth освобождает USB-порт при перезапусках для повторной прошивки.
Какие есть похожие проекты?frank-386, keybytes, crosspoint-reader, esp32sim, PixelFonts, MicroManipulatorStepper, esp-sdr, mu300-linux
Автор
kuslota
Размер
0.9 MB
Звёзды
191
Обновлён
КоммитNov 15
Возраст
1 мес
Коммиты · 90 дней