KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

crankboy-manager

★ 24 Open GitHub ↗

Cross-platform desktop app for transferring Game Boy® ROMs to CrankBoy

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

```bash
pip install -r requirements.txt
```

## Usage

### Run the Application

```bash
python main.py
```

or with `uv`:

```bash
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

```batch
build.bat
```

#### macOS / Linux

```bash
chmod +x build.sh
./build.sh
```

#### Linux (Flatpak)

```bash
# 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

```bash
# 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.

crankboy-manager

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README