CrankBoy Manager

A cross-platform desktop application for managing Game Boy ROMs on CrankBoy via USB/serial connection.

Features

• Drag-and-drop file transfer - Simply drag ROM files onto the window
• Folder support - Drop a folder to automatically find all ROMs inside
• ZIP Archive support - Automatically extracts and processes ROMs from within .zip files
• Automatic compression - .gb and .gbc files are compressed to GBZ for faster transfer
• Automatic cover art download - Matching cover art is automatically downloaded and transferred with each ROM
• Batch transfers - Queue an unlimited number of files to be processed and transferred one by one
• Progress tracking - Visual progress bars for each file and overall transfer
• Auto-restart - Optionally restart CrankBoy after transfer to refresh library
• Cross-platform - Works on Windows, macOS, and Linux

Installation

You can use uv to automatically install the dependencies on first launch (recommended), or install the dependencies manually with pip as follows:

Requirements

• Python 3.10 or higher
• PyQt6
• pyserial

Install Dependencies

pip install -r requirements.txt

Usage

Run the Application

python main.py

or with uv:

uv run --python '>=3.10' --with-requirements requirements.txt main.py

Transfer Files

1. Connect your CrankBoy via USB
2. Select the serial port from the dropdown (click Refresh if needed)
3. Add files by:
   • Dragging and dropping files/folders onto the window
   • Clicking "Add Files..." button
4. Click "Start Transfer"
5. Wait for completion - Files will automatically decompress on the device

Options

• Verbose - Show detailed transfer log
• Auto-restart - Restart CrankBoy after all transfers complete

Supported File Types

• .gb - Game Boy ROMs (automatically compressed)
• .gbc - Game Boy Color ROMs (automatically compressed)
• .gbz - Pre-compressed GBZ files (transferred as-is)
• .zip - ZIP Archives (ROMs inside are automatically unpacked)

Automatic Cover Art Download

When you transfer a ROM, the app will automatically:

1. Calculate the CRC32 of the ROM file
2. Look up the game in the CrankBoy database (based on CRC32)
3. Download the matching cover art from the CrankBoy covers repository
4. Transfer both the ROM and cover art to your device

Notes:

• Cover art is downloaded automatically - no configuration needed
• Covers are saved with the same basename as the ROM file (e.g., MyGame.gb → MyGame.pdi)
• If a cover is not found in the database or download fails, the ROM will still be transferred
• Covers are downloaded fresh each time (not cached locally)

Building Standalone Executable

Quick Build (Recommended)

Windows

build.bat

macOS / Linux

chmod +x build.sh
./build.sh

Linux (Flatpak)

# requirements-flatpak.txt is generated from requirements.txt (dropping
# NO-FLATPAK lines); build_flatpak.sh does this for you.
grep -v 'NO-FLATPAK' requirements.txt > requirements-flatpak.txt
flatpak run --command=flatpak-pip-generator org.flatpak.Builder --requirements-file=requirements-flatpak.txt
flatpak run --command=flathub-build org.flatpak.Builder --install app.crankboy.crankboy-manager.json
flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest app.crankboy.crankboy-manager.json
flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo
flatpak run app.crankboy.crankboy-manager

Advanced Build Options

Python Build Script

# Standard build
python build.py

# Clean previous builds
python build.py --clean

# Install dependencies only
python build.py --install

Build Outputs

After building, you'll find:

• Windows: dist/CrankBoyManager.exe + dist/CrankBoyManager-1.0.0-windows.zip
• macOS: dist/CrankBoy Manager.app + dist/CrankBoyManager-1.0.0-macos.zip
• Linux: dist/crankboy-manager + dist/CrankBoyManager-1.0.0-linux.tar.gz

Protocol

This GUI uses the ft (File Transfer) protocol:

• Fixed 177-byte chunks
• CRC16 verification per chunk
• Automatic GBZ compression/decompression
• Detailed error reporting

See the main CrankBoy repository for protocol documentation.

Acknowledgments

This project was developed with the assistance of LLM coding tools, including Kimi and DeepSeek. These tools helped in the prototyping of the PyQt6 interface and the implementation of the ft protocol.