FUG-107: auto hardware discovery — qwiic sensor drivers in the effects VM

[issuefleet]

Plug any qwiic/I2C sensor into a splanc device and the model can enumerate the
bus, identify the part, write a driver for it, and install it — the driver runs
in the effects VM and exports sensor values as uniforms that effects
reference. Implements the FUG-107 vision end-to-end.

Design: a driver is just an effect with a different entry point

Rather than add a second interpreter, a sensor driver is ordinary .fxb
bytecode run by the same fx_vm as effects — same sandbox, same per-invocation
instruction budget, same host/wasm/device parity. The differences:

• a void poll() entry instead of shade() (a program is an effect XOR a
  driver);
• export <type> name "unit"; declarations — the values poll() writes;
• I2C intrinsics i2c_write / i2c_read8 / i2c_read16.

On the device each poll's exports are copied into the active effect's uniform
of the same name/width — the exact set_uniforms slot path a slider uses — so
a driver and an effect authored independently line up automatically. In the VM
the intrinsics call an I2cBus trait: the firmware backs it with the ESP-IDF
qwiic master, the host/browser back it with a mock register map, so drivers are
authored and unit-tested with no hardware.

The pipeline (bottom-up, one commit per layer)

1. Driver VM (firmware/fx_vm, fx_compiler) — I2cBus trait + I2cWrite/
   I2cRead opcodes threaded through run(); .fxb v2 header adds
   poll_entry (v1 still parses); Vm::run_poll / Vm::export; the compiler
   gains export decls + exports manifest, a poll() entry, and the
   i2c_* builtins. (Also fixed two latent bugs the driver AI would trip on:
   the disassembler truncated at min/max/mix, and string literals mangled
   non-ASCII units.)
2. Protocol — ScanI2c → I2cScanResult{addresses}, SubmitDriver{fxb, poll_interval_ms, bindings, activate} → DriverState, RemoveDriver.
3. Firmware runtime — qwiic bus brought up in main.cpp (scan probes
   0x08–0x77); a second fx_vm runs the driver's poll() off the render loop
   (lm_drv_poll), applying exports → effect uniforms each poll.
4. Web + AI — a qwiic sensor database keyed by I2C address (identifyScan),
   export→uniform bind-by-name (computeBindings), scanI2c/submitDriver
   client methods, and two AI tools (scan_bus, set_driver) + a driver-dialect
   system prompt wired into the editor's chat when a device is connected. The
   model can scan the bus, identify the part, write a driver from its register
   map, compile it, bind it, and install it — iterating on the first poll result.

EFFECTS.md documents the whole driver stack.

Verification

• VM/compiler: host unit tests compile+run drivers against a mock I2C bus
  (read→exports, config write, bus-error -1/0, effect/driver exclusivity,
  v2 back-compat).
• Protocol: conformance_test + phone_client_frames_test green.
• Firmware dispatch: ffi_test drives scan_i2c → submit_driver → poll → remove_driver end-to-end on the host.
• Firmware image: bazel build -c opt //firmware/player_app:esp32c6 links
  clean.
• Web: full app type-checks; sensorDb/driverBindings unit-tested; 67
  web tests green.

Hardware-pending

Real-sensor bring-up is the one step I couldn't run — there's no qwiic module on
the HITL bench. The qwiic pins in main.cpp (default SDA=6/SCL=7 @100 kHz) are
build-time overridable and will likely need tuning to the actual board's qwiic
connector. The export→uniform bridge matches by name+width; the AI is instructed
to export the type the target uniform expects (client-side type matching would
need the scalar type threaded into the uniform manifest — a small follow-up).

🤖 Generated with Claude Code

---

Update (HITL fix): the first HITL run failed on the BLE-provision → wss TLS
handshake lane. Root-caused to boot-time footprint — the firmware paid for I2C at
boot (driver-install heap + a 4 KB static buffer), eating into the mbedtls
handshake headroom the arena sizing is tuned around. Fixed: I2C init is now lazy
(first sensor use, not boot) and the driver buffer is 1 KB, so FUG-107 adds ~1 KB
.bss and zero boot-time heap on a sensor-less device. (Couldn't reproduce on a
rig from the fleet worktree — it's logged out of Tailscale — so this leans on the
root-cause analysis + the CI re-run.)

Update (merge): merged origin/main (FUG-121 native OSC input landed). The
overlap was in the same firmware files but disjoint code regions — resolved one
conflict in tests/ffi.rs (both features append host assertions; kept both). The
.fxb finish() now carries both my v2 poll_entry header and FUG-121's
embedded uniform manifest. Re-verified post-merge: all host rust tests, the
esp32c6 image, web type-check + tests, and both wasm bundles build/pass.

Update (test-lane fix): the post-merge test/test-macos failure was a link
error, not a test assertion — FUG-121's transport_bench (a host binary linking
player_ffi_host, which bazel test //... builds) hit undefined reference to lm_i2c_scan because ffi.rs now imports the qwiic hooks. Added the same no-op
stubs the host ffi_test uses. Verified bazel build is green across
//firmware/... //fx_compiler/... //tools/... //web/... //solver/... //shared/....

Update (v2 .fxb web parsers): fixed two browser-side .fxb parsers that
hardcoded the v1 18-byte header and so broke on this PR's v2 .fxb — parseFxb
(perf estimator) rejected version != 1, and parseFxbTextures read the buffer
table at the wrong offset. Both now handle v2 (20-byte header); a new
fxbV2.test.ts pins them. These are runtime-only paths (node tests don't emit
real .fxb), which is why they surfaced late. All .fxb consumers (Rust VM +
disassembler, both web parsers) now agree on the v2 layout.

Update (merge 2 — FUG-122): rebased onto main again after FUG-122 (FX-VM
native datatypes + framing) landed — a large overlapping change to the VM
opcodes, run(), the .fxb writer, and the compiler. Resolved: appended
FUG-107's I2cWrite/I2cRead opcodes AFTER FUG-122's new fixed/int ops so their
discriminants are unchanged (I2C mirror consts renumbered 102/103); threaded the
I2cBus param through FUG-122's rewritten run() (resident stack/locals/
call_stack + 4-tuple return) including run_poll; kept both features' compile
tests and extended FUG-122's opcode-classifier test to cover the I2C ops. The
.fxb finish() now composes v2 poll_entry (FUG-107) + embedded manifest
(FUG-121) + the new datatype flags (FUG-122). Re-verified on the merged tree:
all host rust tests, the esp32c6 image, web type-check + 65 unit tests, and
both freshness gates (fx_vm_perf_doc_freshness, codegen_freshness) pass.

Update (merge 3 — FUG-125): rebased onto main again after FUG-125 (FX
engine optimizer + VM superinstructions + on-device RV32 JIT) landed — another
large overlapping change. Resolved: FUG-107's I2cWrite/I2cRead re-appended at
discriminants 106/107 (after FUG-125's 102–105) across all coupled sites — the
Op enum, from_u8, the run() dispatch, the fx_vm_op mirror, the
disassembler, opt::op_len, and fx_jit::op_len (exhaustive, so it had to be
sized); merged FUG-125's JIT-table run() params with the I2cBus param
(run_poll passes both). The bytecode optimizer now repoints poll_entry
too (threaded through optimize/decode/encode/Prog + the reachability
root), so a driver's poll() is optimized + relocated exactly like an effect —
verified by the compile→optimize→run driver tests. fx_jit correctly declines
to JIT the I2C ops (I/O, not in the straight-line integer subset). Re-verified on
the merged tree: all host rust tests + transport_bench, the esp32c6 image,
web type-check + 68 unit tests, and both freshness gates pass.

Closes-Linear: FUG-107 (https://linear.app/fughilli/issue/FUG-107/auto-hardware-discovery)

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://fughilli.github.io/splanc/pr-preview/pr-96/
Built to branch gh-pages at 2026-08-19 23:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.