FlashFloppy: turning Gotek hardware into a USB floppy drive

The hardware is fixed, the firmware is the variable part

FlashFloppy is a floppy drive emulator for Gotek hardware. The description is short: connect to retro machines just like a real floppy drive but use disk images on a modern USB stick.

The division of labour is what defines this project. The hardware is a Gotek, a commercially made USB floppy emulator that already exists as a product. FlashFloppy is the firmware that runs on it, and the alternative firmware is what makes it useful. The README's stated benefits follow from that: you can say goodbye to old and unreliable floppy disks, and you can download and play from the disk image archives for your retro machines.

What the firmware claims to offer is a wide range of host support, covering retro computers, synths and machinery, direct reading and writing of many image formats, a flexible track layout for raw sector images, and heavy configurability through the `FF.CFG` configuration file.

The two claims that matter in practice are the host support and the track layout. A floppy is not a random access block device with a capacity, it is a specific set of tracks and sectors with a geometry the host's own software was written against. A disk image that lays out the data differently from what the host expects will not boot, regardless of how correctly the emulator reads bytes. The track layout configuration is therefore not a convenience feature but the mechanism that makes a given image usable on a given machine.

The documentation lives in the GitHub Wiki rather than in the repository, with separate pages for Gotek compatibility, host platforms, image formats, track layouts, the configuration file and downloads.

Building it means compiling for three microcontrollers

The Makefile at the repository root builds the firmware from source, and the structure of the build tells you what is involved.

The project name is `flashfloppy` and the version is derived from the git commit, with `VER:= $(shell git rev-parse --short HEAD)` exported as `FW_VER`, so the firmware knows which build it came from.

There are per-microcontroller targets, and the naming is `%` based. A `prod-%` target builds six things for the given MCU, and there is a matching `debug-%` and `logfile-%` for the other two build levels:

prod-%: FORCE
	$(MAKE) target mcu=$* target=bootloader level=prod
	$(MAKE) target mcu=$* target=shugart level=prod
	$(MAKE) target mcu=$* target=apple2 level=prod
	$(MAKE) target mcu=$* target=quickdisk level=prod
	$(MAKE) target mcu=$* target=bl_update level=prod
	$(MAKE) target mcu=$* target=io_test level=prod

Those six targets are the interesting part. The `bootloader` is the firmware's own bootloader, `bl_update` is the mechanism for updating it, `io_test` is a diagnostic build. Then there are three disk interface implementations: `shugart`, which is the Shugart SA-400 interface used by most PC compatibles, `apple2`, for the Apple II's Disk II compatible interface, and `quickdisk`, for the Quick Disk serial protocol.

So the firmware is not one binary. It is a family of builds, one per disk interface, per microcontroller, per build level. A user with an Apple II and a user with a PC-compatible machine are running different firmware images, which is the correct design given that the electrical and protocol layers differ.

The `all` target lists what a full build covers: `all-stm32f105`, `all-at32f435`, `apple2-bootloader-stm32f105` and `ffemu`.

There is also a separate `ffemu` component, built with its own Makefile in the `ffemu/` directory, with `ffemu-shugart` and `ffemu-apple2` variants. That is a host-side emulator, and the `ffemu` Makefile is invoked with `O` and `TARGET` variables, so it is a distinct build product from the firmware.

Out-of-tree builds and a Python helper in the toolchain

The build system is a plain GNU Make setup with a small amount of custom structure, and it separates build products from downloaded dependencies.

The `O` variable controls where the build happens. The comment in the Makefile states that build products are placed in `$(O)/out` and downloads are cached in `$(O)/ext`, and that you can specify `O=<path>` for an out-of-tree build. The `OUT` and `EXT` variables are derived from it with `abspath`, so relative paths work.

That separation matters for a project like this, because the firmware depends on third-party libraries that have to be fetched. The `ext` directory is the download cache, and `mrproper` removes both the output and the extension cache while `clean` removes only the output.

The `target` rule is the generic path. It makes the output directory for the specific MCU, level and target combination, then descends into it with `Rules.mk` to produce `target.bin`, `target.hex` and `target.dfu`. Those three artefacts are the flashable forms, a raw binary, an Intel hex file and a DFU file, and having all three means the same build can be programmed with whichever tool the user has.

Python appears in the toolchain as well, with `PYTHON := python3` in the Makefile, which is used by the download and generation steps.

The `Rules.mk` file at the repository root is the shared rule set, and the `scripts/` directory holds the helper scripts. The `inc/` directory holds the headers shared across the firmware targets, `src/` the main sources, and the `attic/` directory holds code that is no longer built. The `examples/` directory contains `FF.CFG`, `IMG.CFG` and a `Host/` directory, which is where the configuration file format is demonstrated, and `fonts/` holds embedded font data for the device's own display.

There is also a `RELEASE_NOTES` file at the root, which is where the per-release detail lives given that the repository README itself is a short overview that points at the wiki.

Licensing is permissive but it comes with a condition

The licence situation here is unusual and worth reading carefully before you flash anything or sell a programmed device.

The README states that most code is public domain, and the rest is MIT/BSD or open source friendly, with the details in the `COPYING` file. So it is not a single licence but a mixture, and the `COPYING` file is where the exact terms for each part live.

The redistribution terms are spelled out more concretely. The source code and all binary releases are freely redistributable in any form. Because FlashFloppy includes third-party code, you should include or link to the `COPYING` file in any redistribution. The README makes the commercial case explicitly: you are free to sell and profit from Gotek devices programmed with a binary release of FlashFloppy, but at a minimum you should incorporate or link to the `COPYING` file on your selling page, and it gives the example wording of stating that FlashFloppy is free software and pointing at the licence.

That is a permissive, business-friendly arrangement. The obligation is attribution by reference rather than by publishing source, which is a much lighter requirement than a copyleft licence would impose on someone selling hardware.

The catch is that the obligation attaches to third-party code with its own terms, and a mixture of public domain, MIT and BSD in one project means the `COPYING` file is the only place that tells you which is which. This is a licensing observation rather than legal advice, and the `COPYING` file is what governs.

The repository's own licence is reported as a custom one that GitHub cannot classify, which is consistent with a file that is a concatenation of several licences rather than a single standard text.

Release cadence and the gap between tags and commits

The version history is worth reading closely because the release list and the commit history tell different stories.

The listed releases are v3.42 on 2024-01-11, v3.43 on 2025-01-22 and v3.44 on 2025-04-12. The last push to the repository was on 2026-10-16, which is more recent than the newest tag, and the repository is not archived.

So the code is being worked on, and the work is not always being tagged. That is normal for firmware, where a build is often made from the tip of a branch rather than from a release, but it does mean the release list is not a complete picture of what has changed. The `RELEASE_NOTES` file at the root is the more detailed record.

The three build levels are worth understanding in the same way. `prod` is the shipping build, `debug` adds diagnostics, and `logfile` is the level that produces log files. Being able to produce a logfile build of the same interface target is a real diagnostic tool, because it lets someone capture what the emulator is doing on the wire while a machine fails to boot from a particular image.

The `io_test` target in the build list supports the same idea from the other end. It is a build that exercises the I/O path rather than the full firmware, which is the level to reach for when a machine will not see the drive at all.

The repository also has a `README` file alongside `README.md`, which is a distinction that usually means the older plain-text version is kept for historical reasons, and a `.github/` directory holding the CI workflow that the CI badge points at.

Editorial conclusion

FlashFloppy fits a retro-computing hobbyist or a repair shop with a Gotek-equipped machine who wants to abandon physical floppies without losing the machine's original software, and who is comfortable flashing firmware. It does not fit someone who wants a turnkey product, since the hardware is a specific Gotek device and the firmware has to be installed on the device, and it does not fit a general-purpose storage need where a USB stick would do. Verify first that your Gotek unit is in the supported compatibility list, because the emulator behaviour depends on the hardware revision, that the image formats you actually hold are among the supported ones, that your host machine's expectations about disk geometry are covered by the track layout options, and that the copy of the firmware you install matches the licence terms, since the project asks that you include or link to the COPYING file with any redistribution.

Frequently asked questions

Official sources

1. Issues
2. keirf/flashfloppy on GitHub
3. README
4. Releases