A command-line interface for interacting with the Croco Game Boy cartridge reader/writer. This tool allows you to manage ROMs, save files, and device information on your Croco cartridge via USB.
%E2%97%9C-green?style=flat){kind=icon}
- List Games - View all ROMs currently stored on the cartridge
- Upload ROMs - Write Game Boy ROM files to the cartridge
- Delete Games - Remove ROMs and their associated save files
- Device Info - Display cartridge firmware version and hardware details
- Save File Management - Download and upload Game Boy save files (SRAM)
libusb-1.0- USB library for device communication- GCC compiler
- pkg-config
macOS (with Homebrew):
brew install libusb pkg-configDebian/Ubuntu
sudo apt-get install libusb-1.0-0-dev pkg-configFedora
sudo dnf install libusbx-devel pkg-configArch Linux
sudo pacman -S libusb pkg-configAlpine Linux
sudo apk add libusb libusb-dev pkg-configmakeThis will create the croco_cli executable in the build/ directory.
The Makefile includes support for Homebrew installations on macOS. Adjust HOMEBREW_PREFIX if your installation is in a different location.
Run the program without arguments to enter interactive menu mode:
./build/croco_clior use :
make runThe menu provides the following options:
l- List all games on cartridgea- Add/upload a new ROMs- Backup Savefileu- Upload a Savefiled- Delete a ROM by IDi- Display device informationq- Quit
When selecting the upload option, you will be prompted for:
- Path to ROM file - Full or relative path to a
.gbor.gbcfile - Display name - Custom name for the game (max 17 characters)
Example:
[?] Enter path to ROM file (or 'EXIT'): roms/Snake.gb
[?] Enter display name (max 17 chars): Snake
[>] Initializing Data Stream...
Target: Snake
Size: 32768 bytes (2 banks)
[+] Handshake successful. Uploading data...
Writing Bank: [2/2] ...
=================================================
SUCCESS: ROM flashed to cartridge memory!
=================================================The cartridge will calculate the required number of banks (16KB banks) and transfer the ROM in 32-byte chunks. A progress indicator shows the current bank being written.
Select the delete option and enter the ROM ID (shown in the game list):
[!] DANGER ZONE
[-] Enter ROM ID to wipe (or type 'EXIT'):This will remove both the ROM and its associated save file.
Displays all games currently on the cartridge with the following information:
- ROM ID number
- Game name
- ROM size (in 32KB banks)
- RAM size (in 8KB banks)
- MBC type (cartridge hardware type)
Example output:
ID NAME | ROM SIZE | RAM | MBC
---- ------------------------ | ---------- | ------- | ----
[ 0] FydosMagicTiles | 2 Banks | RAM: 0 | MBC: 0x00
[ 1] Hello-ASM | 2 Banks | RAM: 0 | MBC: 0x00
[ 2] Input ASM | 2 Banks | RAM: 0 | MBC: 0x00The Croco cartridge communicates via USB using a custom command protocol. Commands are sent to the device and responses are echoed back.
| ID (Hex) | Command | Description | Response |
|---|---|---|---|
0x01 |
readRomUtilization | Query flash memory state | numRoms, usedBanks, maxBanks |
0x02 |
requestRomUpload | Prepare cartridge for ROM transfer | status (0 = OK) |
0x03 |
sendRomChunk | Send 32-byte ROM data chunk | status |
0x04 |
readRomInfo | Get ROM metadata | romId, name, numRamBanks, mbc, numRomBanks |
0x05 |
deleteRom | Delete ROM and save file | status |
0x06 |
requestSaveDownload | Prepare save file for download | status |
0x07 |
receiveSaveChunk | Receive 32-byte SRAM chunk | bank, chunk, data |
0x08 |
requestSaveUpload | Prepare for save file import | status |
0x09 |
sendSavegameChunk | Send 32-byte SRAM chunk | status |
0x0A |
fetchRtcData | Fetch Real Time Clock data | rtcData (49 bytes) |
0x0B |
sendRtcData | Set Real Time Clock data | status |
0xFD |
readDeviceSerialId | Get RP2040 UUID | serialId (8 bytes) |
0xFE |
readDeviceInfoCommand | Get firmware version and hardware info | hwVersion, swVersion, gitShort, gitDirty |
Based on the real webapp https://cartridge-web.croco-electronics.de/ a bank is the numbers of bytes / 256 ex: 48640 bytes / 256 = 190 banks
"Croco Cartridge not found"
- Ensure the cartridge is properly connected via USB
- Check that no other application (like the web interface) is accessing the device
- Try disconnecting and reconnecting the USB cable
- On Linux, you may need to run with
sudo
"No response from device"
- Close any running Croco web apps
- Disconnect and reconnect the cartridge
- Try running with
sudo - Power cycle the cartridge
"Failed to detach kernel driver"
- Another application is using the device
- Close the Croco web interface
- Run the command with
sudo
Upload fails mid-transfer
- Ensure the ROM file is not corrupted
- Try uploading to a fresh cartridge by deleting other ROMs first
- Check available cartridge storage with the "List Games" option
ROM appears corrupted after upload
- Use only validated Game Boy ROM files
- Verify the file size is correct (typically 32KB-8MB)
- Try deleting and re-uploading the ROM
src/main.c- Main program, device communication, and command implementationsbuild/- Compiled output directory
- Initialize libusb and locate device (Vendor: 0x2E8A, Product: 0x107F)
- Claim USB interface and configure endpoints
- Send commands with 1-byte command ID + payload
- Receive responses (command echo + data)
- All multi-byte values use big-endian byte order
- Web Interface: https://cartridge-web.croco-electronics.de/
- JavaScript Implementation: https://github.com/shilga/croco-cartridge-webapp
- libusb Documentation: https://libusb.info/
This project is released under the MIT license.
Read more on my blog
Credit:
Developed with ❤️ & 💪 by @wirenux