One firmware.
Many synths.

What fm1-dock keeps for you

• The log: a 2 KiB ring in RAM that survives a reset: boots, slot checks, module starts, saves, faults. Modules write to it with host->log().
• The crash record: vector, PC, return address, the module and the time of the last fault. Load the symbols above and the console names the function.
• The render load: the last and the worst block, in 24 MHz ticks and as a share of the 5.8 ms a block may take, and the overruns.
• Strikes: which modules crashed at boot and are being skipped.

Probes: ask the chip

When the emulator and the FM-1 disagree, don't guess: write a probe. A probe is a small C program (probes/*.c) that runs once from RAM inside fm1-dock, with interrupts and hardware registers at its disposal, and writes typed records (numbers, text, timings) that come back as JSON. The same probe runs in the emulator:

tools/probe.py run probes/timing.c --on emu,fm1    # side by side, with the ratio
tools/probe.py exec "r3 = r1 * r2" --regs r1=5,r2=7  # one instruction, on the chip

Where the emulator and the chip differ

Found with probes on a real FM-1. Test there before calling anything safe.

A module is a table of functions at the start of its image, linked against nothing of the host's. fm1-dock checks its header, ABI, CRC and sizes before anything of it runs, copies its .data, clears its .bss and calls init(). render() runs in the audio interrupt, everything else in the main loop.

static void render(int32_t *out, uint32_t n) { /* add n stereo frames, Q15 */ }
static void note(uint32_t ch, uint32_t key, uint32_t vel) { /* vel 0: off */ }
static void ui(uint32_t ev, int32_t arg) { /* buttons, encoders */ }
static void draw(uint32_t full) { /* what changed */ }

HB_DESC = { HB_ABI, "MYSYNTH", init, release, note, cc,
            render, ui, draw, 0, 0, HB_F_SCREEN | HB_F_PANEL, midi };

# modules/mysynth/module.cfg: name, version, sources, cflags, includes, libs
python3 tools/hbmod.py modules/mysynth      # -> build/modules/mysynth.dock
uv run --with python-rtmidi tools/dock.py deploy build/modules/mysynth.dock
# or drop the .dock on "Deploy a module" above

Start from modules/sine/sine.c (about 150 lines). The host gives a module the time, the log, the screen (text, a canvas, blits), the LEDs (lit or a dim glow), its own settings record and flash banks, MIDI out, the MASTER gain and the keys' force: hb_module.h has every call.

Limits

Flash

Offsets in the FM-1's 1 MiB flash. An update writes up to 0x93000; deployed modules, their table, the settings and the banks are above it, so installing a new fm1-dock keeps them.

F0 7D 48 42 cmd seq pack7(payload + CRC-32(payload)) F7

7D: non-commercial id; 48 42: "HB". pack7: 8-to-7 bits, LSB first.
A reply: cmd | 0x40 (0x7F: refused), the same seq; its payload
starts with a status byte (0 done). Little-endian words.

Status codes

0 done · 1 bad CRC · 2 bad header · 3 too big · 4 no space · 5 flash error · 6 verify failed · 7 data missing · 8 not started · 9 not found · 10 bad message

Module states

0 ok · 1 bad CRC · 2 bad header · 3 too big · 4 crashed · 5 init failed · 6 too slow

A module file (.dock)

An 80-byte header (magic "HRBR", ABI, flags, name, version, code / data / bss / ram_text sizes, measured worst cycles, descriptor offset, base, relocation count, CRC-32), the relocations, then the image on a 256-byte boundary. Whoever moves it adds the difference to each relocated word, which is how one file lands anywhere in the deploy area.

Implementations: tools/hbdeploy.py (Python), dock.js (this page), and the device side in firmware/src/dock.c.