Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

FM3 adapter: the same protocol family, verified rather than assumed

Open
  • Is something wrong?
#40 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
36/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend

Research direction

Start with fm9/adapter.py, fm9/protocol.py, and fm9/sim.py, then read docs/PROTOCOL-CONTRIBUTIONS.md and docs/PROTOCOL.md for FM9 assumptions that require FM3 verification. Run the hardware regression on a real FM3 and record its firmware version and evidence; completion requires a truthful adapter, registry, simulator, green tests, verified protocol notes, and proof that only decoded message types are reachable.

Written by the indexing model from the issue text.

Description

enhancement help wanted

An outside contributor has offered to build an FM3 adapter. This issue is the landing pad: what the work actually is, what "done" means here, and what each side owes the other. Whoever picks it up, comment and it is yours.

Why the FM3 is the natural next device

ToneCommand supports exactly one device today. The HeadRush adapter (#33) was framed as the easy second device because its API is open; the FM3 is the close second device, because it speaks the same gen-3 Fractal editor protocol family the FM9 work already decoded. fm9/protocol.py is a port of mcp-midi-control's gen-3 codec, and Fractal's own "Axe-Fx III MIDI for Third-Party Devices" Rev 1.4 spec covers the documented command set for the whole family. Unlike ToneX (#23, #27), there is no protocol archaeology to do from scratch. There is, however, real verification to do, and none of it can be assumed.

What an adapter is

Exactly what #33 describes: one Python class implementing the fm9/adapter.py contract (status, preset/scene/bypass/channel, verified parameter writes, slot reads without selection, whitelisted store), plus an honest Capabilities declaration, a parameter registry the planner can reason about, and a simulator model so the test suite runs without hardware. No UI work; the safety layer (validation, confirmation, preset pinning, store whitelist, read-back verification) is inherited, not reimplemented. That is the architecture's whole point.

FM3-specific work items

  1. Model byte. The FM9 codec hardcodes model byte 0x12 from the Rev 1.4 spec; the FM3 has its own byte in the same document. Thread it through the codec as a parameter rather than forking the file.
  2. Grid geometry and cable encodings. The FM3 grid is smaller than the FM9's, and every cable-encoding claim in docs/PROTOCOL-CONTRIBUTIONS.md (items 5, 7, 11, 12) was proven on FM9 hardware only. Each one must be re-proven on an FM3 by write-plus-readback before the adapter may use it. The row-2 same-row quirk in particular may or may not exist there; do not carry it over on faith.
  3. Blocks and parameters. The vendored catalog and grounding sidecars were built against the FM9's rosters. The FM3 shares the modeling family but not the block complement or counts; it needs its own registry mapping, with the same facts-only, cited, fail-loudly-on-drift rules the FM9 data follows.
  4. The read paths that lie. The dead ends documented in items 4 and 8 (zeroed sub 09 00 GETs, display-name queries returning roster defaults, asynchronous writes with plausible stale reads) were observed on FM9 firmware. Verify which of them hold on FM3 firmware rather than assuming either way, and record the answers in docs/PROTOCOL.md marked with the device and firmware they were proven on.
  5. Rule zero is structural. The transport layer's message whitelist means firmware and bootloader operations are unreachable by construction. That property must hold identically for the FM3 adapter, on day one, not as a later hardening pass.
  6. Simulator honesty. fm9/sim.py is the model, including its habit of naming undecoded territory instead of silently simulating it. An FM3 sim that pretends is worse than none.

The division of labor

The maintainer owns no FM3, so hardware verification belongs entirely to whoever builds this, and their regression log is the evidence the review will ask for: the equivalent of hardware_regression.py run on a real FM3, with firmware version stated. In return: contract questions answered quickly, review with file-level findings, and protocol discoveries land in docs/PROTOCOL.md with credit, the same way every FM9 finding did.

Done means

  • Adapter class behind the existing contract, capabilities declared honestly, partial is fine if truthful.
  • FM3 registry and simulator, full test suite green without hardware.
  • Write-plus-readback verification on a real FM3, logged with firmware version.
  • Protocol notes contributed back, each claim marked verified or UNDECODED.
  • Rule zero demonstrated: no path to any message type outside the decoded surface.
Dominant language
Python
Stars
7
Forks
3
Avg merge
2h 20m
Merged PRs (30d)
48

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from monzta1/ToneCommand

All issues in monzta1/ToneCommand

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.