# Designing controls for hardware

> How to make a small number of physical controls useful across modules with many parameters.

Canonical: https://maru.audio/docs/hardware-controls
Documentation index: https://maru.audio/llms.txt

A browser panel can show twenty parameters. A pedal may have three knobs and a
footswitch. Hardware design is therefore not a matter of copying every screen
control onto the faceplate. It is the design of a small, memorable control
surface for the most important musical decisions.

## Keep the full parameter model

Every meaningful parameter should still have a stable name, range, unit, and
default. The web UI, automation, presets, remote control, and hardware all
refer to that same parameter identity.

The physical surface is a projection of that model. It may expose only the
parameters that matter during performance, while the web view remains available
for editing the complete sound.

This separation avoids two common problems:

- hiding important parameters inside hardware-specific code; and
- making a module with three knobs impossible to use from a richer controller.

## One knob can do more than one thing

A single physical control can be useful in several ways:

**Direct control.** One knob moves one parameter. This is the clearest choice
for a control such as output level or blend.

**Macro control.** One knob moves several parameters together. For example, a
“character” knob can increase drive, shorten a tone filter, and add a small
amount of blend. Each underlying parameter remains explicit; the macro defines
the relationship between them.

**Context or pages.** The same physical knob controls different named
parameters in different modes. The mode must be visible and predictable so a
user does not change an unseen value by accident.

**Preset or scene changes.** A footswitch or gesture can change a coordinated
group of values. This is often better than forcing one knob to represent a
large collection of unrelated settings.

Use direct controls for precision, macros for musical gestures, and presets or
scenes for discrete changes. A module can use more than one approach, but each
relationship should be intentional and discoverable in the web UI.

## Make mappings feel trustworthy

The adapter turns the physical source into a normalized logical control. The
module/package layer then decides what that source means. This keeps a control
such as `dial-1` independent from the board's ADC channel or vendor SDK.

Good mappings make four decisions explicit:

- **Range:** what part of the parameter does the physical travel cover?
- **Curve:** should the control give fine resolution at the bottom, middle, or
  top?
- **Smoothing:** how much sensor noise should be removed?
- **Pickup:** what happens when a saved preset and the real knob disagree?

Soft pickup is often important on a pedal. Without it, loading a preset can
make a parameter jump as soon as the knob moves from its old physical position.

## Avoid invisible conflicts

If a knob, phone, MIDI controller, and automation lane can all change a value,
the product needs a clear authority and feedback policy. The user should be
able to tell which value is active and why.

Macros also need guardrails. Avoid mappings where two controls fight over the
same parameter without explanation, or where a small movement causes a large
unnoticed change elsewhere. Show the affected parameters in the web view and
keep the mapping editable as configuration rather than baking it into the DSP.

The same boundary applies to MIDI controllers: the host maps an incoming
controller value onto a declared parameter. The module continues to receive
that parameter through its normal contract.

## Design for fewer controls, not fewer capabilities

The goal of a pedal surface is not to expose every parameter. It is to expose
the decisions a musician needs while playing, while preserving the complete
module for editing, automation, and future hardware.

Start with the performance question: “What would I want to change without
looking away?” Give those decisions direct controls or well-designed macros.
Leave deep editing to the web view or another richer surface.

For a musical example, [What changes when an instrument becomes a pedal?](https://maru.audio/blog/hardware-for-audio-pedals.md)
compares holding a harmony under your foot with using a second press to release
it.

For the complete module-to-device model, read
[From module to hardware](https://maru.audio/docs/from-module-to-hardware.md).