fretwire — Roadmap

Target: HX Stomp (VID 0x0E41 / PID 0x4246). Goal: full GUI editor on Linux. Strategy: recover the MI_00 USB control protocol by observing traffic to and from the device; read the model/preset/control data from the user's own installed copy at runtime (nothing is redistributed); build a libusb transport + greenfield GUI.

Implementation language: Rust. USB via nusb (pure-Rust, cross-platform, async) — no libusb C dependency, clean on Linux; falls back fine for dev on Windows. Workspace layout:

crate	role
`fretwire-data`	parse shipped JSON (`.models`, catalog, controls, `.hlx` presets) into typed structs
`fretwire-protocol`	MI_00 wire message types + encode/decode codec (filled in during Phase 2/3)
`fretwire-usb`	`nusb` transport: enumerate, claim MI_00, bulk/interrupt I/O
`fretwire-core`	device session API (connect, sync, param set, preset load/save, snapshots, tuner)
`fretwire-cli`	command-line validator/driver
`fretwire-tauri`	GUI — Tauri 2 (WebKitGTK) + Svelte

Phase 0 — Recon ✅ (done 2026-06-21)

Locate the device; set up USBPcap + Wireshark.
Inventory res/ — found complete model/preset/UI data as JSON/XML.
Identify device VID/PID and the MI_00 vendor control interface.
Set up project dir + notes.
Scaffold the Rust workspace (5 crates) — compiles clean.
fretwire-data: parse every shipped .models + .hlx; presets round-trip losslessly (3 tests green).
fretwire-usb: nusb enumeration works — fretwire detect reports the unit present.

Phase 1 — Capture infrastructure

Determine which USBPcap root hub the HX Stomp is on; build a capture filter.
Establish a repeatable capture procedure (start cap → do ONE known action → stop).
Capture the startup handshake (launch HX Edit with device connected).
Capture a set of labeled single-action sessions: - one parameter tweak (e.g. amp Drive) — note before/after value - block on/off (bypass) - model swap in one block - preset change (select another preset) - snapshot change - tuner on/off - receive a full preset (open editor on a preset) - send/save a preset to the device
Store each as captures/NN-<action>.pcapng + a .md describing the exact action.

Mostly answered without the captures (2026-08-22). This list asked for five footswitch and controller assign captures. Four were settled by construction instead — op 56 assigns and unassigns a block's bypass to a switch, op 37 assigns a parameter to a source ordinal, both byte-exact and verified live, and the CLI has assign-bypass / unassign-bypass / assign-param. Worth remembering next time a list like this reads as capture-blocked.

What is left of it:

assign_param_to_exp1.pcapng — one parameter assigned to EXP1. Source ordinals 3..=7 are the footswitches; 1 and 2 are believed to be the two expression inputs and that is [unverified] for want of an expression pedal to try it with. This is the only one of the five still worth a capture, and it needs a pedal plugged in more than it needs Windows.
A layout reorder (a bound block moved between switches) is separate from binding and has no op of its own yet; whether the device treats it as unassign-plus-assign is unchecked.

Still wanted for the footswitch ring colour / custom label write (ops 58-62, the one area where guessing has already cost a power cycle): see section B of captures/_RUNBOOK-hx-edit-session.md.

Phase 2 — Protocol decode (in progress)

Phase 4 — Linux transport (proof of life)

fretwire-protocol codec built + tested: Frame encode/decode (exact bytes), Tlv body, BE-f32 value helpers, channel/cmd/op constants. 7 golden tests against real captured frames (round-trip byte-exact) + byte-exact generation of the validated 5-packet handshake.
libusb prototype: claim MI_00, replay the handshake, read a reply.
Implement parameter read/write; verify against the physical unit.
Implement preset get/set; round-trip a .hlx.

Phase 5 — Core library

Data layer: parse .models / catalog / controls / presets + device preset stream into a state model (fretwire-data).
[~] Editor model (fretwire_core::editor): preset stream → typed EditorPreset/EditorBlock with resolved model id + category, device-ordered named params + values, and byte-exact edit command generation (bypass). Live session (connect/sync over fretwire-usb, param read/write, preset get/set, snapshots, tuner) still to come.
Graceful disconnect / Session::close() — DONE (verified live 2026-06-25). Connecting put the device into host-owned "edit mode" (front-panel page/preset arrows dead); dropping the interface — even a USB port reset — did not release it (it's firmware RAM, not USB state). The fix: send HX Edit's shutdown session-close (cmd 0x02, empty body) on each channel (status → edit → primary), request/response with a ~150 ms settle before releasing the interface (firing blind doesn't work). Runs on Drop so even Ctrl-C cleans up; fretwire disconnect exercises it. primary never acks (handshake diverges there) and the panel releases regardless, so the ack wait is capped (300 ms) to keep teardown fast. Decoded from launch_hx_*_close*.pcapng.
CLI for validation (the GUI rides on top of this).
[~] DSP-fit / model availability. HX Edit greys out models that won't fit the remaining DSP. (1) per-model cost — SOLVED: the .models files carry load (mono) and load_stereo (% of DSP budget); range 0.35–40.0 (amps ~28%, poly pitch/sustain cap at 40). Wired into Catalog (bundled_loads) → EditorBlock.dsp_load (incl. paired cab, by Mono/Stereo variant) → EditorPreset.dsp_load; pull shows "DSP X% used". (3) current usage — SOLVED: sum of block loads (computed locally — factory preset reads 71.8%, self-consistent). (2) budget — likely 100% per DSP (the 40-cap + busy-preset sums fit); still to confirm the exact HX Stomp cap and validate our % against HX Edit's meter on the same preset. Availability: the devices field (per-model device-id+firmware list; None = universal) gates which models a given unit even offers — but on the HX Stomp this is moot: the Stomp runs the full HX model library; its only constraint is DSP + the 8-block cap, so HX Edit's grey-out is DSP-fit driven, which we've built. The devices field is cross-product/firmware versioning (Helix Native + old-firmware gating), not a Stomp model restriction. swap warns when the projected load exceeds editor::DSP_BUDGET (~100%) via Catalog::model_load_by_index. Live probe (2026-06-25): the handshake identity reply carries the model string "P33Main" + ~12 trailing bytes (serial/HW-rev/firmware/flags, undecoded) — no 0x0021xxxx device id, so the devices ids can't be matched from the wire either. Only loose end: confirm the budget value vs HX Edit's own DSP meter (our two-amp preset reads 73.5% — does HX Edit agree?). Treat this thread as essentially resolved otherwise.

Phase 6 — GUI (the editor loop is done; remaining work is mostly UI polish)

Phase 7 — Preset & device management

Phase 7.5 — Tooling / developer experience

Move the CLI to clap. (2026-07-29) fretwire-cli hand-rolled a match over std::env::args for ~35 subcommands, with hand-maintained eprintln! help. Both motivating problems were observed rather than theoretical, and both are now structurally impossible: 1. The help drifted. Editing one eprintln! during the 2026-07-26 session silently dropped set and snapshot from the listing. The migration found three more commands missing from it — tree, move-to-row, before-split — which nobody had noticed. --help is now generated from the command definitions, so it cannot disagree with them. 2. Silent bad-argument fallbacks. args.next().map(|s| s.parse().unwrap_or(0)).unwrap_or(0) meant fretwire goto 5 banana quietly targeted bank 0 — and on save/rename, that was a persistent write to the wrong setlist. Every numeric argument now errors instead. bypass/move-to-row became ValueEnums: the old parser read any unrecognised word, and a missing argument, as off/series — so a typo silently did the opposite of the request. Every documented invocation was smoke-tested unchanged (parsing happens before connect, so argument acceptance is checkable without hardware).

Phase 8 — Publishing

Phase 9 — Other HX devices (Helix Floor first)

Opened 2026-07-22 by a contributor's Helix Floor captures + backup. Survey: docs/helix-floor.md. The data layer already covers the Floor (355/355 models, 19,377/19,377 param keys resolve) and its USB control interface is identical to the Stomp's, so this is mostly plumbing — once we can see a real session.

Identify the device: PID 0x4248, preset device ID 0x210001, version word 0x03800000 (not the firmware version — a 3.80 Stomp reports it too). Constant + udev rule landed; no code matches on the PID yet.
Decode the .hxb backup container (header + concatenated raw zlib streams).
Get a capture with HX Edit connected (captures 3 & 4, 2026-07-22).
Verify the handshake — it is byte-identical to the Stomp's. All ten device_handshake() frames appear verbatim in both Floor captures. No change needed. Floor model code is P21.
Confirm our preset parser reads Floor streams — it does, unmodified, including all 8 snapshots. Cross-checked against the .hxb backup as ground truth.
Handle slot type 7 (Looper) in fretwire_data::stream enumeration. Different content shape: model index at key 8, params at 7 → 4, enabled at 10. Fixed the Stomp too — a Floor capture's serial preset went from 8 blocks to 9 once its Looper stopped being skipped.
Walk preset key 1 (the second DSP's slot array) alongside key 0. Blocks now carry (dsp, index) and flatten to the wire slot with dsp * 20 + index. fretwire_protocol::edit needed no change. EditorPreset gained a DspView per DSP (its own split/mixer/input/output nodes, grid and load); the flat accessors now mean DSP 0, which is what a one-DSP device has. Verified against a real Floor capture: "Pull Me Under" decodes all 15 blocks across both DSPs with the right rows and footswitch bindings (it used to show 7).
Verify the write path — byte-exact, 9/9 ops. Captures 3 & 4 are HX Edit-driven and carry the full write path; our existing edit builders reproduce the Floor's bytes exactly for set_value, bypass, begin_structural, swap_model (incl. a paired amp+cab swap), save_preset and select-preset. Envelope shapes are identical to the Stomp's. No protocol change is needed for the Floor in either direction.
DSP2 addressing — solved (WinCap5, 2026-07-23). Wire slot numbers are global: slot = dsp * 20 + index, so DSP1 is 0–19 and DSP2 is 20–39. There is no DSP field and none is needed. Confirmed by five DSP2 blocks edited in HX Edit on FACTORY 1 12B "Pull Me Under", each sweep's first wire value landing one UI increment from that block's stored value — and consistent with every earlier capture (all slots < 20, all DSP1). The same capture also gives the read side of a parallel, dual-DSP preset. No further Floor captures are needed.
Replaced the scattered PID constants with a device-descriptor type. fretwire_protocol::Device + DEVICES carry PID, model code, preset device ID, DSP count, snapshot count and a Support flag; Device::by_pid/by_model_code do the lookups. Transport::open now matches any known device (verified ones first) and exposes which it opened via Transport::device() / Session::device(); present_devices() lists everything plugged in. The HX Stomp XL is Reported (2026-08-20) — an owner has the editor working against one, and both bugs they filed reproduced on an HX Stomp — with its unknown fields still honestly None, because "a user says it works" fills in none of them. We have no capture, preset or backup from one, so opening it still logs a caveat. Tests pin the invariants, including that every table entry has a matching udev rule. Still open on the XL: how many setlists it has. Its banking was answered on 2026-08-21 by the owner reading 01A-32D off the panel, and its model code P36 by their handshake log.
Helix LT — PID 0x424A, Reported (2026-08-22, PR #3). Surveyed on a contributor's physical unit: handshake, preset read, snapshot decode and the setlist/preset browses all work unmodified once the PID is in the table, so the LT needs no protocol change. It stamps the Floor's P21 and carries the Floor's geometry (2 DSPs, 8 snapshots, 8 banks of 128), so by_model_code("P21") keeps resolving to the Floor — they are one data class. Survey: docs/helix-lt.md. Still open on the LT: its preset_device_id (never on the wire; the Floor's came from a .hxb, and we have no LT backup), how its screen banks presets, and every write path — no edit has ever been sent to one, which is why it is not Verified.
HX Effects — PID 0x4245, Untested (2026-08-22, issue #10), then Reported (2026-08-24). A contributor ran lsusb and sent the line: ID 0e41:4245 Line6, Inc. HX Effects, which made it findable and nothing more — the table's first Untested entry. An owner has since reported it working, which moves it to Reported by outcome: detect finds one, the udev rule covers it, opening it still warns, and every other field is None. It is the family member least like the rest (effects only, no amps or cabs), so nothing is inherited from the Stomp. Still open: everything else — the report carries no capture and no panel readings. One pull from an owner would settle its model code and preset geometry.
Helix Rack — PID 0x4249, Untested (2026-09-01). The table's only entry added without a person behind it. The id is the Linux kernel's Line 6 rate quirk, which labels it "Helix Rack >= fw 2.82"; the same table's 0x4248 "Helix >= fw 2.82" and 0x424A "Helix LT >= fw 2.82" are the two ids we did measure on hardware, so the value between them is corroborated at both ends. Every field is None — not even the Floor's P21, though the Rack is a Floor in a rack box, because a guessed code would make by_model_code ambiguous. The pre-2.82 ids are deliberately absent (0x4241 Helix, 0x4242 Helix Rack, 0x4244 Helix LT): this protocol was recovered from firmware 3.x. Still open: everything. fretwire detect naming one is the entire report needed to move it to Reported.
Global settings — op 24 reads, op 25 writes, 27 ids named (2026-08-22, and eight Ins/Outs ids from an HX Stomp XL owner on 2026-08-23). The namespace is flat and numbered; a 601-id sweep costs 1.4 s, so settings-dump / settings-diff maps it with no capture at all. fretwire_protocol::settings is the shared table, the CLI has setting-get/setting-set, and the GUI has a Globals panel. Id 27 (preset numbering) turned the preset sidebar's manual toggle into a view of the pedal's own setting — it reads the form at connect and writes it when switched, so the sidebar item and the Globals panel's "Preset numbering" row are two views of one value (2026-08-22; verified live 2026-08-23, switching in the GUI changes the form on the pedal's own screen). The global EQ is fully mapped: 190-200, three bands of frequency/Q/gain then the two cuts, and the GUI draws it as a response curve. Still open: 138 answering ids are unidentified; 127 (Auto In-Z, renamed from a mis-transcribed "Guitar In-Z" on 2026-08-23) has two observed values and neither is named; 201-203 are unknown (an earlier "global EQ" gloss was withdrawn). Writes are gated to identified ids only.
The footswitch record is decoded (2026-08-22). Op 33 returns {102: switch (zero-based), 65: ?, 109: label, 66: ?, 67: [assignments]}, and an assignment is {59: enabled, 68: ?, 66: colour, 69: {109: name, 98: slot, 28: param, …}}. Key 66 is the LED ring colour, 0xRRGGBB — proved by binding two blocks of different categories, a delay coming back 0x06FF00 (green) and an amp 0xFF0003 (red). The same key in the type-41 status push is the ring's current colour, bright when engaged and ~1/16 brightness when bypassed, which refutes the "state bitmask" reading that section carried.
Custom footswitch colours and labels — SHIPPED (2026-08-27). Pick a ring colour and a name per footswitch, the way HX Edit does. Storage decoded the same day (label = layout key 14 gated by 13, colour = 16 gated by 15; docs/preset-format.md), written through the op-21 document path since no surgical op is known: Session::{set_switch_label, set_switch_color}, CLI switch-label/switch-color, and a ✎ mini-editor on the GUI block panel with the ten palette swatches. The palette was mapped live by sweeping indices 1-10 and reading the ring, then matched to Line 6's own footswitchLED enum in HelixControls.json: 0 Auto Color, then White, Red, Dark Orange, Light Orange, Yellow, Green, Turquoise, Blue, Violet, Pink, and 11 Off — all twelve observed live. The ring and scribble repaint immediately on the write. hxb-convert carries @fs_customlabel and @fs_customcolor.
```
Still open, low priority: ops 58-62 (HX Edit's incremental route — **do not probe by
guessing**, one power cycle per guess, see `docs/safety.md`); whether record keys
`65`/`68`/`26`/`120` matter; the LEDs' exact RGB (the GUI's swatch colours are by-eye
approximations).
```
assign-bypass leaves the switch label unset where the pedal sets it — SETTLED (2026-08-27). Op 33's 109 mirrors the layout entry's key 14 gated by 13, and the pedal never backfills them — not with time, not on re-read, not on a snapshot change, not across a save and flash reload (all tried live). The panel's bind gesture writes 13: true + 14: <name> itself; op 56 writes the virgin pair. So op 56 is not missing a follow-up op — the difference is two document keys, writable on purpose. See docs/protocol.md.
Session grid/routing planning is still DSP-0 only. add_block_at, place_block, insert_block, reorder_block and set_node_pos plan slot moves inside one 20-slot array and read it via dsp_blocks(0)/dsp_grid(0) — complete for the Stomp, needs a dsp argument for the Floor. Reading and per-block edits are already DSP-agnostic; only this layer is not.
Grid/UI: the routing view assumes one DSP × 2 rows. The Floor needs 2 DSPs × 2 paths. The backend is ready — PresetDto.dsps[] carries each DSP's grid/nodes/load, and every cell and block is tagged with its dsp; the flat fields mirror dsps[0] so the current UI is unaffected until it's rewritten.
[~] .hxb import/restore. The conversion is built and measured (2026-08-25): fretwire_data::tone turns a tone object — what an .hxb slot and an .hlx file both carry — into the wire preset, and fretwire hxb-convert writes an export file the existing backup-show/restore path already reads. Blocks, split topology and snapshots all come across, and so do the footswitch bindings with their custom labels and LED ring colours; checked against one preset held in both forms (a Floor backup and a wire dump of the same slot off the same unit), where all 15 blocks, 106 parameter values, 320 snapshot-matrix cells and all 8 bypass bindings match the device's own bytes. This gives .hlx import too — the format is the same tree — which is the more useful half, since .hlx is what people share. > 2026-08-26: the block-type gaps are closed. The amp+cab refusal dissolved on a live > measurement: both cab families are ordinary Helix.sym entries and a paired cab stores > whichever the preset uses — there was never a family mapping to find. A swap sweep on the > Stomp measured every missing class (dual cab 16/32, IR 19/21, looper 22, synth 23, plus > the family split 18/33 that refuted the old unconditional 33), the IR block's key-27 UUID > reference fell out of the same dumps, and the looper had a device-written oracle in the > Sultans stream all along. Every non-empty preset in the sample backup now converts — > 363/363, from 39. Fixtures: captures/pairing_sweep.md; oracle tests: > fretwire-data/tests/paired_blocks.rs. > 2026-08-26, later: controller assignments carry across too. The oracle preset turned > out to describe its whole table — the earlier "extra rows from the capture session" > reading was a scan hitting a different preset of the same name — so key 4, each > snapshot's per-controller values (2), and the type-2 footswitch-layout row a > switch-sourced assignment also owns are all written now, byte-identical to the device's > own across all four source kinds the oracle holds (EXP ×2, footswitch, snapshots). All > 608 controller entries across the sample backup's 363 presets carry; the one source kind > still skipped is MIDI (its row carries a CC number no tone we hold shows). Bonus decode: > the Floor's switch ordinals run from 6 (switch = ordinal − 5), not the Stomp/XL's 3. A converted preset has still never been sent to a pedal. What is left: - Topology AB (a DSP the paths merely pass through, Floor-only) still has no wire evidence and stays a refusal. - The four input/output nodes store a ragged prefix of their symbol's parameter list and the rule is unknown; they keep the target's values. - MIDI-sourced controller rows (the CC number, key 1 under a MIDI source) — needs one tone+wire pair with a MIDI assignment.

Phase 10 — Headless / serve mode

Opened 2026-08-23 by a Helix Floor owner running a Pi 5 with PiPedal, who asked for a Raspberry Pi build and described wanting something else: the editor served over the network from a machine with no screen. Survey and full breakdown: docs/serve-mode.md.

The pieces are further along than the size suggests — ui/src/lib/ipc.js is already a single transport seam with two implementations behind it (Tauri, and the browser mock), the UI already runs in a plain remote browser via npm run dev, and of 61 commands only 2 touch AppHandle, for 3 event names total.

Lift commands.rs + dto.rs out of fretwire-tauri into a transport-neutral crate — DONE (2026-08-31): fretwire-commands, in default-members so the offline suite covers it. fretwire-tauri keeps 65 one-line #[tauri::command] wrappers (the surface had grown from 61) plus a TauriSink; spawn_heartbeat and export_setlists take an events::EventSink, and each event's name + JSON payload live once in events::Event.
fretwire-serve — DONE (2026-09-01): axum + embedded dist/ (rust-embed; one static binary in release), POST /invoke/{command} through fretwire_commands::dispatch (offline- tested, camelCase args like Tauri's), a WebSocket at /events for the three events, clean SIGINT/SIGTERM session teardown, and a single-editor lease (second browser → close 4409 / HTTP 409; released on disconnect). Out of default-members like fretwire-tauri. The UI's ipc.js picked up the third transport (serve.js), selected by a marker the daemon injects into index.html — the same dist runs under Tauri, serve, and the mock.
Client-side files — DONE (2026-09-02): five _inline command variants (ir_upload/ir_export, export_setlists/backup_show/restore_preset) carry the file in the invoke — base64 for the WAV, the text for an export — sharing their bodies with the path pair; the UI picks by INLINE_FILES (serve or the mock) via lib/files.js, so in a browser IRs and exports are uploads/downloads and the export dialog can still target the daemon's disk. Data import stays server-side permanently (fretwire import-data over SSH — the installer is ~1 GB); that is the one flow still reaching pickPath() under serve, and the server-side directory browser is a nice-to-have for it. See docs/serve-mode.md §3.
Auth for non-loopback — DONE (2026-09-02). Loopback needs nothing (only local processes reach it); any wider --bind requires a bearer token, generated once into ~/.local/share/fretwire/serve-token (0600; or --token / FRETWIRE_SERVE_TOKEN) and printed at startup inside the link to open — #token=…, a fragment, so it never reaches logs or a Referer. The page keeps it per origin, sends it as Authorization: Bearer on invokes and as a query parameter on the event socket (browser JS can't set handshake headers), and asks for it on a 401 / close 4401. With a token the Host rule relaxes to "our port" and Origin must equal Host (a rebinding page lands on its own origin with no token); without one the 2026-09-01 loopback rule stands. No TLS to start, by decision: a LAN bind assumes a trusted network, and the SSH tunnel, a VPN, or a TLS proxy cover the rest. See docs/serve-mode.md §4.
A GROUP= udev rule — DONE (2026-08-26), with the arm64 CLI item in Phase 8: every rule line now grants GROUP="plugdev" alongside uaccess, install-udev creates the group and prints the usermod step, and the test asserts both grants per line.
Verify PiPedal coexistence on hardware. Different USB interface from the audio one, and fretwire-usb already falls back to detach_and_claim_interface, so it should be fine — but detaching an interface out from under a live audio path is not a friendly failure, and this has never been tested here.
The arm64 serve artifact, once the crate exists (the arm64 CLI shipped independently — Phase 8).
MCP server — a third consumer of the same lift. DONE (2026-09-02): fretwire-mcp, a stdio server on the official rmcp SDK — 14 read tools (offline export-file and catalog tools, live reads), +10 edit-buffer tools behind --allow-writes, +preset_save behind --allow-save; ungated tools are unlisted. Text results in HX Edit's display units, set the same way. Left open: the in-daemon HTTP transport (needs a second seat on the lease), model_params, .hxb input. See docs/serve-mode.md. The original case: asked for independently on 2026-08-23, the same day as serve mode, which is the strongest argument for doing the lift at all. The requester's guess that the CLI is a poor fit is correct and measurable: ~60 live subcommands each call Session::connect(), so it's one handshake and teardown per invocation with no cursor or edit buffer carried across; a long-lived MCP process fits Session + the heartbeat better. Offline-first, and after the lift. Most of the value (explain / generate / tone-match / batch-rename / diff a preset) needs no pedal — it runs on backup JSON plus the catalog, all of which is already implemented offline. Don't translate 61 GUI-shaped commands into 61 tools. Read-only by default; edit buffer before persistent save; firmware/DFU never in the tool surface (docs/safety.md). Available today with no code: fretwire backup + point an agent at the JSON. See docs/serve-mode.md.

Safety

See docs/safety.md. TL;DR: captures + offline work are zero-risk; live control is low-risk (worst case = power cycle); firmware/flash/bootloader/DFU is the only brick risk and is out of scope — never transmit it. Back up the device before any write experiments.

Risks / unknowns

Auth: HX Edit has auth_*.xml + an authentication log → confirm the device link itself doesn't require online auth (editing should be local; account is for licenses/marketplace).
The wire preset format may be binary (not the JSON .hlx); captures will tell.
Firmware update path is explicitly out of scope (risk of bricking) until late, if ever.

FilesExpand file tree

ROADMAP.md

Latest commit

History