OpenCyclone-FlashBoy

Warning

This project is a work in progress, generated with vibe coding. It is not yet tested and may contain bugs. Use at your own risk.

A Linux-native CLI and GUI for the Flash Boy 3.2 Cyclone Dumper (and any other clone of the insideGadgets GBxCart RW v1.1/v1.2).

The device is a CH340 USB-to-serial bridge that talks the GBxCart RW serial protocol at 1 000 000 baud. This project gives you a clean interface without the original Cyclone Windows software or the heavy FlashGBX GUI, and adds first-class integration with RomM (upload dumps and scrape metadata) and RetroDECK (launch a dumped ROM with one button).

Supported hardware: Flash Boy Cyclone v3.x, GBxCart RW v1.1/v1.2. For newer GBxCart RW revisions (v1.3, v1.4) prefer upstream FlashGBX.

Features

• autodetect of the CH340 USB device
• info — read firmware + PCB version of the dongle
• dump-rom / dump-save / write-save — ROM/SRAM R/W
• ROM identification (GB/GBC + GBA titles, region, SHA1)
• RomM integration: upload ROMs, upload saves, force metadata scrape
• RetroDECK integration: launch any dumped ROM with one button
• Qt GUI with progress bar, log area, and auto-scrape-on-insert
• chunked uploads for files > 64 MiB

Quickstart

git clone <this-repo>
cd OpenCyclone-FlashBoy
./opencyclone.sh

That's it. On first run the launcher creates a private virtualenv, installs the required packages, and opens the GUI.

Advanced installation

If you want to install system-wide or into an existing venv:

pip install -e .            # CLI only
pip install -e .[gui]       # CLI + GUI (PySide6)

udev rule (recommended, no root needed)

sudo cp udev/99-opencyclone.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
# then unplug/replug the device

If you start the GUI (opencyclone-gui) and the device is plugged in but you don't have permission to open it, a dialog will pop up offering to install the udev rule for you (or add your user to the dialout group).

From the command line you'll see a Permission denied error. Fix it with one of:

# Option A: install the bundled udev rule (recommended)
sudo cp udev/99-opencyclone.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
# then unplug and replug the device

# Option B: add yourself to the dialout group
sudo usermod -aG dialout $USER
# log out and back in (or run `newgrp dialout`)

Otherwise run the app with sudo for testing.

Usage

Make sure the physical switch on the PCB matches the cartridge family (GBC vs GBA) — the device uses it to pick the right voltage. The CLI and GUI auto-detect the active mode (DMG/AGB) at runtime, so you don't have to tell the software which way the switch is set. Use opencyclone detect (or the Detect cartridge button) to see the detected mode.

CLI

opencyclone devices
opencyclone detect
opencyclone info

# dump a GBA ROM
opencyclone dump-rom mygame.gba --size 0x200000

# dump a GB/GBC ROM (4 MiB default)
opencyclone dump-rom mygame.gb

# dump / restore saves
opencyclone dump-save  pokemon.sav --size 0x8000
opencyclone write-save pokemon.sav

You can still force a specific mode with --mode DMG or --mode AGB in case auto-detection fails for some unusual cartridge.

RomM

RomM is a self-hosted ROM manager. Once configured, OpenCyclone can upload dumps directly to your instance.

# one-time setup
opencyclone config set romm_url      https://romm.example.com
opencyclone config set romm_token    rmm_xxxxxxxx...   # client API token

# upload a dumped ROM (auto-picks the right platform from the header)
opencyclone romm-upload-rom mygame.gb

# upload a save (the ROM must already be on RomM)
opencyclone romm-upload-save mygame.sav mygame.gb

# force RomM to re-scrape metadata (cover, IGDB, etc.)
opencyclone romm-scrape mygame.gb

The token / URL can also be passed on the command line, or come from ROMM_URL / ROMM_TOKEN / ROMM_USER / ROMM_PASSWORD env vars.

GUI

opencyclone-gui

The GUI lets you:

• pick the serial port
• press Detect cartridge to read the header, identify the game and show its title, platform, region, publisher, SHA1, … (the device's GBC/GBA hardware switch is auto-detected)
• dump the ROM / save to a file with a progress bar
• upload the dump to RomM with one click
• toggle Auto-scrape on insert to trigger metadata refresh every time you Detect a cartridge
• press ▶ Play in RetroDECK to launch the dumped ROM through RetroDECK's RetroENGINE CLI (flatpak run net.retrodeck.retrodeck …)

Persistent settings (RomM URL/token, RetroDECK command, auto-scrape flag) are stored in ~/.config/opencyclone/config.json.

Dumps, saves, camera images and covers are stored under $XDG_DATA_HOME/opencyclone (default: ~/.local/share/opencyclone), organized in subfolders: roms/, saves/, camera/, covers/.

Protocol references

• Lesserkuma/FlashGBX — command / variable map
• gbxcartrw_gbcamera.py — minimal OFW-only Python reference
• GBxCart RW Manual (insideGadgets)
• RomM API docs
• RetroDECK CLI

License

GPLv3+. See LICENSE.