Hardware architecture

A pedal is another host for a Maru module. The module owns the sound; the host supplies buffers, events, devices and a lifecycle. You can audition the module in a browser and compile its Processor for a hardware experiment without rewriting its DSP in a board SDK.

Hardware integration is in development. Cross-builds and emulation exist for three target lanes; none is yet qualified on a physical board. See Hardware platforms and profiles for the current scope.

Who owns what

Owner	Responsibility
Module	Graph or restricted-TypeScript Processor, declared audio/MIDI ports, parameter schema, presets, resources, state and face
Audio SDK and DSP library	Shared authoring contracts, parameter semantics and reusable processing leaves
Compiler and module toolchain	Derive a target Program from canonical module source; generate bounded instance, buffer and event adapters
Pedal project	Select the module and board profile; bind logical knobs or switches to existing parameter paths in pedal.jsonc
Target producer	Build, emulate, detect, install or flash, verify and profile; retain artifact identity and evidence
Device host and board adapter	Audio/MIDI I/O, scheduling, physical control acquisition, buffer conversion, activation and telemetry

The browser face consumes host capabilities. It does not generate audio or open a device. A pedal project contains configuration, not another implementation of its effect. GPIO, ALSA, USB, codec and vendor SDK code belong below the module boundary.

Two concrete host paths

Module declaration + Processor + public DSP leaves
                    ↓ compiler / module toolchain
          generated processing and event adapter
                    ↓
 Linux: effect .so              MCU: linked effect archive
                    ↓                        ↓
 resident audio/MIDI service    board firmware + SDK adapter
                    ↓                        ↓
 ALSA / MIDI devices            codec / DMA / USB-MIDI

Pi 5: the resident maru-engine-host-pedal service loads one generated effect through a validated pedal descriptor. Audio uses ALSA; MIDI effects use the descriptor's optional event extension. The development build uses a file backend to exercise the same daemon and engine path on the host computer. The installable package carries the effect, service, manifest, control map and install/rollback script. Real Pi audio, installation and recovery still need device tests.

Pico 2 and Daisy Seed: the effect is linked into firmware. The board adapter supplies the callback, audio buffers and physical controls. The freestanding runtime uses caller-owned instance storage and detects attempts to allocate during realtime processing. The Pico 2 produces UF2 firmware; Daisy uses a DFU image, with SRAM/SDRAM placement when required. This is firmware delivery, rather than loading a Linux shared library. Codec-less USB-MIDI effect firmware also exists for Pico 2; Daisy MIDI effect mode is not implemented.

These paths share module semantics and generated processing contracts. Their operating systems, loaders, storage and recovery procedures differ. A general paired device agent, signed remote update service and mobile control experience are further integration work.

A knob follows the parameter contract

physical pot or encoder → calibrated control source
                        → pedal binding → named parameter event
                        → host block boundary → module Processor

The module schema owns units, range, default and taper. The project selects which parameters get physical controls. The adapter owns pins, calibration, debounce and polling. Controls publish validated updates; the callback consumes bounded events. The browser can exercise the same bindings with virtual controls before wiring a board.

The current hardware event adapters have timing constraints of their own. In particular, the Linux control ring applies updates at block start, and raw MIDI ingress into the generated pedal adapter is block-quantized. Portability does not imply identical sample-offset ingress on every host.

Build evidence is different from device evidence

A release audit combines source/artifact identity, static callback inspection, dynamic allocator/lock probes, sound and MIDI comparisons, memory fit, control behavior and device measurements. Pi emulation includes the first unprimed effect call. A zero-allocation observation does not override a static path to an allocator or trap handler.

QEMU checks MCU instruction semantics and output. It does not reproduce the board's codec, DMA, interrupts, cache, external memory timing or analog path. Its instruction counts help identify expensive code; real cycle measurements, xruns, round-trip latency and recovery must come from the intended board.

The useful development loop is audition → build → emulate → inspect the audit → install or flash → measure the device. Each result retains its environment, module revision and artifact identity. A failed or unavailable stage remains visible.

Continue with From module to hardware for the workflow and Designing controls for hardware for control design.