Skip to content

About

.NET port of https://krikzz.com/pub/support/flashkit-md/

Resources

Stars

10 stars

Watchers

0 watching

Forks

Repository files navigation

flashkit-md-dotnet

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).

FlashKit MD GUI

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.

Install

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.

macOS

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).

Linux

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.

Windows

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".

Using the TUI

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.

Using the GUI

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 .ips or .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 .xdelta for an xdelta patch, anything else writes IPS. The same panel exists in the TUI.

Using the CLI

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.

Notes on flash carts

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.

Building from source / contributing

See DEVELOPING.md.

Credits and license

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.

About

.NET port of https://krikzz.com/pub/support/flashkit-md/

Resources

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages