gb.teensy

GAME BOY COLOR EMULATOR

gb.teensy

gb.teensy is an open-source Game Boy (DMG/CGB) emulator ported to run on a Teensy 4.1 microcontroller. It is a work-in-progress project that can run at least Tetris and passes Blargg CPU instruction tests; it requires custom wiring for display, audio, and controls and loads ROMs from an SD card.

Jump to download ↓Jump to setup guide ↓

gb.teensy emulator screenshot.

game boy colorPRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why gb.teensy exists

gb.teensy brings Game Boy emulation to small, hobbyist hardware (Teensy 4.1) so retro games can run on microcontroller-based handheld or embedded projects. It targets hardware enthusiasts who want a compact, hardware-driven Game Boy experience using an MCU, an FT81x-driven display, and an SD card for storage.

BEST FOR

What gb.teensy is best for

Prototyping a custom handheld or embedded display that runs a small number of Game Boy ROMs on a Teensy 4.1; testing CPU instruction correctness (Blargg tests) on microcontroller hardware; learning how a software emulator is adapted to constrained MCU environments.

The people behind gb.teensy

Project history and status

The repository describes gb.teensy as a work-in-progress Game Boy emulator for the Teensy platform. The README lists features (runs Tetris, passes Blargg CPU instruction tests, audio output) and shows active development (many commits). The project builds on Arduino/Teensyduino libraries, uses the FT81x Arduino Driver for display, and expects ROM files on an SD card. There are open issues in the repository, and no formal binary releases are published via GitHub Releases (the repository shows no releases).

What gb.teensy supports

Target hardware: Teensy 4.1 microcontroller
Display: FT81x-compatible displays via FT81x Arduino Driver
Storage: SD card (FAT32, MBR partitioning) for loading ROMs
Audio: Requires external filter/amplifier circuitry and speaker wiring
Controls: GPIO button wiring (simple wiring, no external pull-ups required)

Download and availability

OFFICIAL DOWNLOADS

Get gb.teensy

Source code is available from the project's GitHub repository. There are no packaged releases on the Releases page; you must clone/build from source and deploy to a Teensy 4.1.

Get gb.teensy ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

gb.teensy setup guide

Setup note: Practical setup requires Teensy-specific toolchain (Arduino + Teensyduino / PlatformIO), an FT81x display or compatible driver and wiring for audio and buttons. ROM files are not included and must be provided on an SD card formatted FAT32 (MBR). The README contains wiring tips and example usage; below is a focused step-by-step setup guide based on the repository documentation.

1) Prepare hardware: Obtain a Teensy 4.1, an SD card (FAT32, MBR), an FT81x-compatible display/eVE module (or compatible display driver), and basic audio/speaker circuitry (filter + amplifier) if you want audio output. Prepare pushbuttons for input wired to available Teensy GPIO pins.
2) Get the source: Clone the official GitHub repository (blazer82/gb.teensy) to your development machine. The project is distributed under GPL-3.0; read the license file in the repository before use.
3) Toolchain and dependencies: Set up Arduino + Teensyduino or another supported MCU toolchain (the repo includes a PlatformIO configuration). Install dependent libraries referenced by the README: the FT81x Arduino Driver, TeensyTimerTool, and standard Arduino/Teensyduino support libraries. Ensure PlatformIO or the Arduino environment is configured for Teensy 4.1.
4) Wiring the display: Follow the FT81x Arduino Driver documentation and the README's reference to the FT81x wiring guide for display connections. The display uses SPI or parallel interfaces depending on the module; wire the FT81x signals to the Teensy pins used by the FT81x driver. Verify power and backlight wiring according to the display module's specifications.
5) Wiring controls and audio: Wire pushbuttons to Teensy GPIO pins; the README notes pull-ups are not required for button wiring in this project. For audio, provide the recommended filter and amplifier circuitry between the Teensy audio output pins and a speaker or amplifier; the README suggests using a Game Boy replacement speaker for authentic sound.
6) Prepare ROM storage: Format the SD card as FAT32 with MBR partitioning. Place ROM files on the card using 8.3 MS-DOS file names (short filenames). The repository indicates the ROM to load is currently specified in source code (src/main.cpp) and not chosen via a runtime menu.
7) Configure ROM to load: Edit src/main.cpp (or the cartridge load call) to set the ROM filename to be loaded, e.g. Cartridge::begin("tetris.gb");. Rebuild and flash the firmware so the compiled code contains the path/name of the ROM to load from the SD card.
8) Build and flash: Use PlatformIO or Arduino+Teensyduino to build the project for the Teensy 4.1 and upload the firmware to the board. Confirm the build environment is using the correct Teensy core and that any referenced libraries are available to the build system.

Software reminder: ROM images, BIOS files, and commercial game data are not included. You are responsible for providing legally obtained ROMs. The project depends on Arduino/Teensyduino and several third-party libraries (FT81x Arduino Driver, TeensyTimerTool).