Cross-platform (Linux / macOS / Windows) client for
krikzz's FlashKit MD programmer
— dump and flash Sega Mega Drive / Genesis cartridges. Ships as a desktop
GUI (flashkit-md-gui), a terminal UI (flashkit-md-tui), and a CLI
(flashkit-md).
All credit for the hardware and the original client goes to krikzz — this project is a port of the original Windows-only client and would not exist without that work. Original C# client and hardware sources: github.com/krikzz/flashkit (MIT). Buy the programmer from krikzz.com.
Download the latest release from the
Releases page
(every release includes a SHA256SUMS file). All builds are
self-contained — no .NET runtime or other dependencies to install.
Download FlashKit-MD.app-vX.Y.Z-osx-arm64.zip (Apple Silicon) or
...-osx-x64.zip (Intel), unzip, and drag FlashKit MD.app to
Applications. If macOS reports the app as damaged or from an unidentified
developer on first launch, right-click → Open, or clear the download
quarantine:
xattr -dr com.apple.quarantine "/Applications/FlashKit MD.app"
The CLI ships in flashkit-md-vX.Y.Z-osx-{arm64,x64}.tar.gz alongside a
bare GUI binary; the same quarantine note applies
(xattr -d com.apple.quarantine ./flashkit-md).
Flatpak (x86_64, arm64): download
flashkit-md-vX.Y.Z-linux-{x64,arm64}.flatpak for your architecture and
flatpak install ./flashkit-md-vX.Y.Z-linux-x64.flatpak
flatpak run io.github.jfryman.FlashKitMD
flatpak run starts the GUI; the TUI and CLI ride along in the same
bundle:
flatpak run --command=flashkit-md-tui io.github.jfryman.FlashKitMD
flatpak run --command=flashkit-md io.github.jfryman.FlashKitMD info
Tarball (x86_64, arm64): flashkit-md-vX.Y.Z-linux-{x64,arm64}.tar.gz
holds the flashkit-md CLI, flashkit-md-gui, and flashkit-md-tui
binaries — untar and run.
Either way, your user needs access to the programmer's serial port. If you get "Access to the port ... is denied", add yourself to the serial group and log out and back in:
sudo usermod -aG dialout $USER # Debian/Ubuntu/Fedora
sudo usermod -aG uucp $USER # Arch
or install the udev rule in
packaging/99-flashkit-md.rules.
Download flashkit-md-vX.Y.Z-win-x64.zip and unzip; run
flashkit-md-gui.exe (GUI) or flashkit-md.exe (CLI). If SmartScreen
warns about an unrecognized app, choose "More info" → "Run anyway".
flashkit-md-tui is the GUI's terminal sibling for SSH sessions and
keyboard-first workflows: the same live device/cartridge status, cart info
panel, transaction log, and auto-dump/auto-write panels, rendered with
Terminal.Gui. Tab moves between
controls, Enter activates, and file prompts open an in-terminal browser.
Plug in the programmer and start the GUI — the status bar along the bottom shows when the programmer is detected (and on which port) and whether a cartridge is seated. Cart details refresh automatically every couple of seconds; every operation appears in the transaction log with its own progress bar and result (size and MD5, or the error).
- Read/Write ROM, Read/Write RAM — the classic per-file operations, with a file picker named after the cart's header.
- Auto-dump — tick Dump ROM (and optionally Dump RAM), pick a folder, and every cartridge you insert is dumped there automatically, named after its header. Existing files are never overwritten (a " (2)" suffix is added).
- Auto-write — for flash-cart development loops: pick a ROM image and every flash cart you insert is erased and reprogrammed with it. Destructive by design, so it asks for confirmation when enabled; cartridges without a writable flash chip (retail games) are detected and skipped. Auto-dump and auto-write cannot be enabled together.
- Patching — tick Apply patch and pick a
.ipsor.xdelta, and Read/Write ROM apply it (to the dump before saving, and to the image before flashing); the format is detected from the file. Create patch dumps the cart and writes the diff against a base ROM you choose — name the output.xdeltafor an xdelta patch, anything else writes IPS. The same panel exists in the TUI.
usage: flashkit-md [--port <serial-port>] <command> [file]
flashkit-md --version
commands:
info print cart ROM name/size and save-RAM size; a
cart with no valid header gets a read-only
flash ID probe (blank flash vs empty slot)
--flash-id always run the flash ID probe
read-rom [file] dump cart ROM (default file: <ROM name>.bin)
--trust-header dump the size the ROM header declares instead
of the mirror-probed size (useful on flash
carts, where probing can misjudge the extent)
--apply-patch <patch>
apply an IPS or xdelta patch to the dump
before saving
--create-patch <base>
diff the dump against <base> and write a patch
instead of the ROM (default: <name>.ips; an
.xdelta/.vcdiff output name writes xdelta)
write-rom <file> erase flash cart and write ROM image (up to the
flash chip's size, max 8 MiB)
--full-erase erase the whole flash chip first (size from
the CFI query; 4 MB with --no-flash-check), so
no stale data above the image shows up as
ghost saves
--patch <patch>
apply an IPS or xdelta patch to the image
before flashing
--no-flash-check
skip the CFI flash-presence check that write-rom
and bake-save run before erasing
read-ram [file] dump save RAM (default file: <ROM name>.srm)
write-ram <file> write save RAM from file
bake-save <file> program a save image into flash at the save
window (0x200000) of an SRAM-less flash cart:
the game sees the saves read-only, so they
survive every power cycle but cannot be
overwritten in-game (needs a 4 MB chip)
The programmer is auto-detected by probing likely USB serial ports
(/dev/ttyUSB* on Linux, /dev/cu.usbserial* on macOS, COM* on Windows).
CDC-ACM ports (/dev/ttyACM*, /dev/cu.usbmodem*: ESP32 boards, Arduinos and
the like) are never probed, since opening them can reset the board. Use
--port to pin a specific port.
info on a cart with a valid header prints its name, system, region and
sizes. A blank (erased) flash cart reads 0xFF everywhere, just like an empty
slot, so when the header is missing info asks the flash chip to identify
itself (CFI query and autoselect ID — read-only, nothing is erased or
written) and reports what answered:
Cart : Flash cart, blank (reads 0xFF)
Flash : CFI OK, 8 MiB, mfr 0x0001 dev 227E/2210/2200 (Spansion S29GL064N family)
A flash cart holding data without a valid header shows Flash cart, unrecognised header instead. If nothing answers, info prints No cart detected (or non-flash cart with no valid header) — usually an unseated
cart. Carts with a valid header are never sent flash commands unless you
pass --flash-id. The GUI and TUI show the same result in the cartridge
panel, and auto-write treats a blank flash cart as an inserted cart.
Dumps print an MD5 you can compare against the original Windows client's
output; write-rom and write-ram verify by reading back.
write-rom erases only as much flash as the image needs (matching the
original client). If the cart previously held a larger ROM, the leftover
data above the new image stays on the chip — and a game with save support
may read it through the save-RAM window at 0x200000 and show "corrupted"
ghost save slots on console. Use write-rom --full-erase to wipe the whole
chip first. The chip's size comes from its CFI answer, so a full erase
covers exactly the chip, whatever its size (with --no-flash-check there is
no CFI answer and it assumes 4 MB).
write-rom accepts images up to the flash chip's size, at most 8 MiB, and
refuses a larger image before erasing anything. 8 MiB needs a cart that
maps flash flat across 0x000000–0x7FFFFF, like the MegaWiFi (validated on a
Rev.C board). read-rom and info report a size above 4 MB only when the
cart's header declares one and the upper half really differs from the lower
half; for anything else, read-rom --trust-header dumps the size the header
declares, up to 8 MiB.
The FlashKit cart plays saves-capable games but cannot persist saves unless
its board actually has SRAM populated; info reporting RAM size : 0B on
the flash cart tells you saving won't work. As a workaround, bake-save
programs a save image (e.g. dumped from a real cart with read-ram) into
the flash at the save window: the game then sees those saves — loadable,
surviving every power cycle — but as a read-only snapshot it cannot
overwrite in-game.
See DEVELOPING.md.
The FlashKit MD hardware and the original client are by
krikzz and published at
github.com/krikzz/flashkit under the
MIT license. This port is likewise MIT-licensed
(see LICENSE), retaining krikzz's copyright notice.
Thanks also to joeyparrish/flashkit-md-py, an independent Python port of the same client.
