How the hub works.

The package: a .fwsc file

For everyone

Every FM-1 firmware comes as one file ending in .fwsc. It is the format of M-VAVE's own updater, and every custom firmware uses it too. Inside are two programs: the update loader, a small helper that writes the firmware, and the firmware itself, the instrument you play.

The first bytes of the file also carry the package's identity, a short name such as FM-1_015. The official firmware V15 is FM-1_015. Custom firmwares pick their own.

The identity: which firmware is this?

For everyone, and important for authors

A running FM-1 answers over USB with the identity of the firmware it runs. The hub uses that answer for one thing only: after you press Connect the FM-1, the card of the firmware on your FM-1 gets the mark on your FM-1.

Many firmwares are built on Felucca, SLOOP or X0X, and several of them keep the number of the project they started from. Then two or more firmwares answer with the same identity, and the hub cannot know which of them is on your FM-1.

For authors: please give your firmware its own number

Pick an identity no other firmware uses. The table below shows every identity on the hub right now. A number that also encodes your version works well, as Charles Vestal's firmwares do: FM-1_9010003 is X0X 1.0.3. Keep the part before the version yours, so that no other project can collide with it. Change it in your build, release, and tell us: your card then gets an exact check and the on your FM-1 mark.

The update loader

For everyone

The FM-1 cannot overwrite the program it is running. So an update happens in two steps: the running firmware first starts the update loader from the new package, and the loader then writes the new firmware. The loader comes from the new package, so every package brings its own.

Felucca's loader

Almost every custom firmware uses the loader from Felucca by Hügelton Instruments. While it waits in update mode, the loader reports the new package's identity. For identities of the form FM-1_9NN, the hub picks up an interrupted update: plug the cable back in, press Install again, and it continues where it stopped.

M-VAVE's own loader

The official V15 brings M-VAVE's loader. A firmware can also be built on top of the official V15 with only the instrument replaced, as Bubba Machine is. Then it brings M-VAVE's loader too. The hub installs it the same way it installs V15 itself, and it can resume an interrupted update of that firmware as well.

What happens when you press Install

For everyone

All of this runs in your browser, over Web MIDI, which only Chrome and Edge have. Nothing is sent to a server. It takes about a minute. Do not unplug while it says Writing.

What the hub checks, and what it does not

For everyone

The hub looks at every listed project's GitHub repository several times a day and takes its newest release. Before a package is offered, it must pass these checks:

• It is an FM-1 package. Its identity starts with FM-1_ and matches what the project reports.
• It has its update loader. Felucca's loader, or M-VAVE's own for a firmware built on the official V15.
• It is unchanged. The hub mirrors the file byte for byte and pins its SHA-256 fingerprint. Your browser checks that fingerprint again before it writes anything.

A release that fails a check is not offered. The last good one stays on the card. If a repository disappears, its card leaves the hub and comes back when the repository does.

Betas

A card says beta when the version is below 1.0 or its name says beta, alpha, rc or test. A beta may change how it saves your work from one release to the next.

Why the hub mirrors the files

A browser is not allowed to download a release file from GitHub directly. So the hub keeps a copy of each package, and a copy of its source code next to it. The firmwares are open source under the GPL-3.0, which allows passing them on unchanged with their source.

Try it before you install

For everyone, and for authors

In the browser

Many firmwares have their own simulator: the firmware's sources built for the browser, with its screen and its sound. On the hub their cards say ▶ Play in the browser. Nothing is installed, and nothing touches your FM-1. OberVave's, for one, is its unchanged firmware: the same sound and screens as on the device, with the computer keyboard or a MIDI keyboard.

The real package, on your computer

fm1-emulator by Simon Johansson emulates the FM-1 itself: its chip (pi32v2) and its board, built on QEMU (GPL-2.0). It runs the same .fwsc you would install, with the screen, the keys, the knobs, the LEDs and the sound, and the firmware's console in your terminal. Download it from its releases (macOS on Apple Silicon, Linux on x86-64; Windows not yet), then:

./emulator felucca-1.5.fwsc

It takes an uncompressed .fwsc or .ufw package or a raw application .bin. Click the keys and buttons, drag or scroll the knobs; on the keyboard Z…C play notes, X / V change the octave, P / O are ENV / LFO, H goes HOME. A firmware's package is linked on its card (release), and the hub keeps a copy of each next to the page.

For authors: boot your release in it before you publish. It catches a package that does not start before anyone's FM-1 does, and it is how the hub's videos are recorded: unchanged packages, real screens, real sound.

Your projects, presets and samples

For everyone

All firmwares keep what you make in the same flash memory of the FM-1, and each in its own way. After a switch, the new firmware may not read what the old one saved. It may start empty, or it may overwrite parts of it.

1. Back up first. Use the backup of the firmware you are on. Each project's page says how.
2. Then switch. Firmwares from the same family, such as Felucca and its forks, often read each other's projects. Others do not.
3. Coming back to a firmware does not always bring your old work back. Restore it from your backup.

Back to the official firmware

For everyone

Download FM-1 V15 from m-vave.com/download (PC Firmware, FM-1) and choose the file in the Official firmware box on the hub. Only that exact file is accepted.

The USB rescue

If the FM-1 does not start any more, hold OCT− while you switch it on. It then waits for an update over USB. Connect it and install any firmware, or V15, from the hub.

If no installer finds it and the computer only sees a USB disk "WL82 UBOOT1.00", the chip's bootloader in ROM still answers, and no update can erase it. The hub's Rescue (Linux) and MvaveFM1Unbricker by Quixotic7 (Windows and Linux, MIT) put a firmware back through it; the Unbricker keeps a full backup of the flash first. An FM-1 that never shows that disk can come back with the FM-1 Transporter, a small RP2040 board on the USB lines (step by step).

Getting your firmware listed

For authors

The hub lists a firmware when all of this is true:

• It makes music. Synths, grooveboxes, drum machines, samplers, chord instruments, controllers. Games and tools without sound are not listed.
• It is open source, with its source code public in the repository and a license that allows passing it on, such as the GPL-3.0.
• It has a .fwsc on a GitHub release. The hub checks the releases on its own several times a day, so every new release appears without anyone doing anything. A project without releases can name its package in a web installer instead. If your release has more than one .fwsc, tell us which one is the firmware.
• The package has an update loader and an identity starting with FM-1_. See the identity section for why your own number helps.

Mail zven@thefirmwarehub.com with the name, the repository and a sentence about what it does. A picture of its screen helps: the cards show each project's real screen, taken from its repository.

Not ready yet?

A firmware without a release package can not be listed yet. Attach the .fwsc to a release, and it can go on the hub the same day. Closed-source firmwares are not mirrored. A very popular one may get a link card that sends you to its maker's own installer.

All identities on the hub, live

For authors

Each firmware as its newest package reports itself. own means no other firmware on the hub uses this identity. shared means the hub cannot tell these firmwares apart on a connected FM-1. M-VAVE loader marks a firmware built on the official V15.

The official V15 reports FM-1_015. Please do not use it.