The Capability Reference

VirtualKnob#

alchemy/surface/virtual_knob.h

A VirtualKnob is one knob/parameter, gathered into one declaration: name, curve and parameter type, LED animation, CV binding, and the metadata the web editor shows. It exists because a knob on this hardware is not always just a potentiometer reading: the value may come from a stored page, be modulated by a param lock or CV, or sit behind pot catch.

Example:

static VirtualKnob cutoff = VirtualKnob(kPotTopLeft, "Cutoff")
    .Exp(20.f, 18000.f)
    .Ring(Level(kAmber, FillAnim::Pulse))
    .Cv(0, 0.6f)
    .Ident("flt.cutoff")
    .Unit("Hz");

const float hz = cutoff.Value();

The essentials are the constructor (a pot position and a name), one transform, a Ring, and Value(). Everything else is optional for additional features.

Constructing and reading

Transforms (choose one; default is Linear(0, 1))

Ring, pip, and overdraw

The looks themselves are cataloged in LED Animations; these are the attachment points.

CV binding

Host metadata (all optional)

Without any of these the knob still appears in the web editor, named after its constructor name with a display hint derived from its transform.

VirtualButton and ButtonBank#

alchemy/surface/virtual_button.h · alchemy/surface/button_bank.h · docs/buttons.md

VirtualButton is the twin of VirtualKnob: one declaration names a physical button, its gestures, and, when the button carries state, that state's shape (zone count, labels, colors, default). The object itself holds no state. A ButtonBank is its storage backend the way a Pager is a knob's: it persists one byte per stateful button in presets, recognizes tap and hold gestures, paints the button LEDs, and shows up in the web editor as an editable field per button.

static const char* kModes[3] = {"LP", "BP", "HP"};

static VirtualButton flt = VirtualButton(kButtonB3, "Filter")
    .Ident("flt.mode")             /* stable host id               */
    .Selector(kModes)              /* 3 zones, labeled, tap-cycles */
    .Colors(kModeColors)           /* per-zone LED feedback        */
    .Bind(SetFilterMode);          /* fires on gesture AND preset load */

static Page       page_a = Page(0).Knobs(k1, k2).Buttons(flt);
static ButtonBank buttons;

presets.Manage(buttons);
loop.Use(page_a).Use(buttons);

Zones, labels, the tap-cycle gesture, its browser label, the preset byte, and the LEDs all derive from that one declaration. Pages are pure composition: Page::Buttons says which buttons are active on which page, so the same physical button can do different things on different pages by declaring one VirtualButton per page.

Reading the physical button

Declaring the button and its state

Gestures and effects

A stateful button with no declared gesture tap-cycles its zones, and the browser label is derived from the zone labels. Declare gestures only to change that.

The bank

Host metadata

Page and Pager#

alchemy/surface/page.h · alchemy/surface/pager.h

A Page is a page index plus references to knob objects. A Pager is what controls the state: it owns the current page index, stores every (page, pot) value, consumes one button for the advance gesture, and runs pot catch. They are separate because pages are composition (which knobs appear together) and the pager is state (which page is live, what every stored value is).

static VirtualKnob cutoff  = VirtualKnob(kPotTopLeft,     "Cutoff").Exp(80.f, 12000.f);
static VirtualKnob reso    = VirtualKnob(kPotTopRight,    "Reso");
static VirtualKnob drive   = VirtualKnob(kPotMiddleLeft,  "Drive");
static VirtualKnob env_amt = VirtualKnob(kPotMiddleRight, "Env Amt");
static VirtualKnob attack  = VirtualKnob(kPotBottomLeft,  "Attack");
static VirtualKnob release = VirtualKnob(kPotBottomRight, "Release");

static Page filter = Page(0).Knobs(cutoff, reso, drive,
                                   env_amt, attack, release).Name("Filter");
static Page mod    = Page(1).Knobs(rate, depth, shape,
                                   offset, rise, fall).Name("Mod");
static Pager pager(hw.buttons[kButtonB1], 2, kNumPots);

loop.Use(pager).Use(filter).Use(mod);

Page: composition

Pager: state and gestures

Jacks and CvMatrix#

alchemy/hw/cv_jack.h · alchemy/surface/cv_matrix.h

The jack API (hw.j3 .. hw.j10) controls which direction a jack points and what voltage is on it. This is an electrical change to the circuit of the Alchemy Lab. The CvMatrix maps what an incoming CV signal means, for incoming destinations per jack.

/* Electrical: J8 becomes a CV output. A physical switch is flipped in the analog front end. */
hw.j8.EnableCvOutput();
hw.j8.SetVolts(2.5f);

/* Semantic: what arriving CV does. */
static CvMatrix cv_matrix(kNumCvInputs);
cv_matrix.Jack(0).To(cutoff).Atten(0.6f);
cv_matrix.Jack(1).Custom(OnTap, &tap_state);
loop.Use(cv_matrix);

Compare this with the CV conveninence in the VirtualKnob class and only use one.

The jack: direction and volts

Driving CV from the DSP is one line in the binder function. Publish a value from the audio callback, write it to a jack each frame:

static volatile float env_follow = 0.f;   /* published by the audio callback */

/* at boot: hw.j8.EnableCvOutput(); */

static void Bind()
{
    filt.SetCutoff(cutoff.Value());
    hw.j8.SetVolts(5.f * env_follow);
}
loop.OnFrame(Bind);

CvMatrix

Clocks and Timing#

alchemy/control/musical_clock.h · clock_follower.h · cv_edge.h · clock_div.h

The timing toolkit turns an external clock, a tap, or an internal tempo into something leverageable.MusicalClock is a free-running oscillator that integrates a rate and emits bar, beat, continuous phase, and a subdivision event mask. ClockFollower steers that timeline from outside pulses. CvEdge (and its gate twin) turns raw CV into clean, timestamped edges. The ClockDiv tables map a locked tempo onto musical delay divisions.

Pulses never move the phase, only the rate. The timeline is monotonic, so a playhead or gate derived from BeatPhase() never jumps backward and never clicks, even while the follower is pulling tempo. Everything runs in the 1 ms poll; nothing here touches the audio interrupt.

static MusicalClock  clock_; 
static ClockFollower follower(clock_);
static CvEdge        clk_edge;

static void OnPoll(uint32_t t_ms)
{
    const uint32_t now_us = daisy::System::GetUs();

    clk_edge.Tick(loop.Cv(), loop.NumCv(), now_us);
    if (clk_edge.JustRose(kClockCvChan))
        follower.OnPulse(clk_edge.LastRiseUs(kClockCvChan));

    follower.Update(now_us);   /* PI loop + loss detection */
    clock_.Tick(now_us);       /* integrate rate -> events */
}

/* One-time setup, before the loop starts. */
clk_edge.Init(kClockCvChan + 1);        /* defaults to 0 channels    */
follower.SetAutoStart(true);            /* run the timeline on lock  */
follower.Enable(kClockExtPpqnDefault);  /* 24 PPQN; off until enabled */

loop.OnPoll(OnPoll);

That is the whole routing: patch the clock into a CV jack, do the one-time setup, and the three calls in OnPoll carry it from jack to timeline. CvMatrix doesn't impact this: whether you run one or not, and whatever it routes, clock intake never passes through it. Additionally, you can use the audio codec inputs for clock edges.

MusicalClock

Internally the clock runs at 96 PPQN, chosen so every straight, triplet, and dotted subdivision lands on an exact tick. The 20..300 BPM clamp is on SetBpm only; a follower writes the rate directly, so a slow external clock can hold it below 20 BPM. It does not know whether its rate comes from SetBpm or a follower, and everything downstream reads it as the single source of musical truth.

The full CLK_EV set, by family:

const uint32_t ev = clock_.Events();
if (ev & CLK_EV::QUARTER)  StepSequencer();
if (ev & CLK_EV::EIGHTH_T) TripletAccent();
if (ev & CLK_EV::EXT_LOST) ShowUnlockedRing();

ClockFollower: locking to an external clock

A PI-controlled PLL. It receives timestamped pulses from an edge detector and continuously adjusts the clock's rate to match them. It reports lock after three consecutive valid pulses. It ignores pulses that would imply a tempo outside 20..300 BPM. If no pulse arrives for three expected periods in a row, it reports the clock lost; what happens then depends on chosen policy: an effect usually wants Freewheel (keep the last tempo through the dropout), a sequencer wants Freeze (hold position until re-lock) or Stop.

CvEdge and CvGate: clean edges from CV

CV inputs are continuous readings; clocks and gates need edges. CvEdge is Schmitt detection with debounce: a high threshold to trigger, a lower one to release, so a wobbling signal fires once per pulse instead of chattering. JustRose / JustFell / Level map those edges onto poll ticks (rose this tick, fell this tick, currently high), and LastRiseUs timestamps them for clock math. A channel is the index of the CV input being watched: channel n reads entry n of the buffer you pass to Tick.

There are two flavors because of the thresholds: 0 V reads as 0.5 on bipolar-conditioned inputs, and CvEdge sits symmetric around that (0.30 / 0.70), right for pulses. A gate returns to 0 V and never below it, so CvGate puts both thresholds above rest (0.55 / 0.65, no debounce) so gates actually release.

ClockDiv: musical divisions of a locked tempo

Free functions for clock-synced time controls. While a clock is locked, the time pot selects among thirteen musical divisions of the quarter note (64th to double whole, triplets and dotted values included) instead of sweeping seconds. The availability mask excludes divisions your engine cannot produce (too short or too long) so they can never be selected.

Think of these as helper functions to make it easier to work with common clock use cases.

const float quarter_s = 60.f / clock_.Bpm();
const uint16_t avail  = ClockDivAvailableMask(quarter_s, kMinDelayS, kMaxDelayS);

if (follower.Locked() && avail)
{
    const uint8_t zone = ClockDivZoneFromNorm(time_knob.Norm(), avail);
    delay.SetTime(ClockDivSeconds(zone, quarter_s));
}
else
{
    delay.SetTime(time_knob.Value());     /* free mode: seconds */
}

ParamLock#

alchemy/surface/param_lock.h · alchemy/control/lock_length.h

Looping automation, per pot, recorded by gesture: hold the trigger button and nudge a pot, and the motion records into a circular buffer that replays as a loop on top of the stored value. Repeat the gesture (nudge) on a playing pot to remove the automation.

static ParamLock<6>  locks(hw.buttons[kButtonB1]);          /* unpaged, 16 s   */
static ParamLock<12> locks(hw.buttons[kButtonB1], pager);   /* 2 pages x 6     */

static ParamLock<6, LockLength<30>> long_locks(hw.buttons[kButtonB1]);   /* 30 s */

loop.Use(locks);

The first template parameter is the total slot count. Unpaged, it equals the pot count and Delta(p) reads slot p. Paged, it must equal pages × pots, and every (page, pot) pair gets its own independent loop. Playback on inactive pages keeps cycling.

The second is a capacity policy: LockLength<seconds, rate_hz = 30, store = Preset>, defaulting to 16 seconds. Seconds mean seconds: the buffer is clocked in milliseconds, so changing the loop's frame rate never rescales a recording. For locks longer than presets can hold, LockStore::RamOnly drops them from the preset blob entirely.

Reading playback

Control and persistence

Presets#

alchemy/surface/presets.h · alchemy/surface/serializable.h

Sixteen flash slots, each holding the whole surface state. Serialization is handled by every framework surface (Pager, ParamLock, Settings); they already implement the Serializable contract, and Manage() registers each one into the slot payload. Registration order is the on-flash byte layout. Writes are wear-levelled across ping-pong sectors, and every slot is stamped with a schema hash of the managed set, so a firmware whose layout changed reads old slots as empty instead of corrupting state.

static Presets presets(hw.seed.qspi);

presets.Manage(pager);      /* order matters: it IS the layout */
presets.Manage(locks);
presets.Manage(settings);
presets.Init();             /* once, after hw.Init()           */
presets.BootLoad();         /* restore slot 0 at power-on      */

The core calls

Bringing your own state

Anything outside the standard surfaces rides along by deriving from Serializable: report a size, write bytes, read bytes, and return a schema hash that captures the layout's shape. Then Manage() it like the rest.

struct ModState : alchemy::Serializable
{
    float   depth = 0.f;
    uint8_t shape = 0;

    size_t SerializedSize() const override { return 5; }

    void Serialize(uint8_t* out) const override
    {
        std::memcpy(out, &depth, 4);
        out[4] = shape;
    }

    bool Deserialize(const uint8_t* in) override
    {
        std::memcpy(&depth, in, 4);
        shape = in[4];
        return true;
    }

    uint32_t SchemaHash() const override { return 0x4D4F4431; } /* 'MOD1' */
};

static ModState mod_state;
presets.Manage(mod_state);   /* now it saves and loads with everything else */

Bump the schema hash deliberately when a layout change should invalidate existing slots; two builds with the same shape read each other's data.

Settings#

alchemy/surface/settings.h · alchemy/surface/settings_control.h

Helpful default settings behavior, with the enter gesture, up to four pages of declarative controls, their rendering, and their persistence. Hold B2+B3 for two seconds to enter; tap B2 or B3 to leave; B1 cycles settings pages while inside. On exit it re-locks the perf pager so every pot re-catches. Stock options come with, and additional controls can be added.

static Settings settings(hw, &pager);

settings.UseBrightness();               /* page 0, pot 0            */
settings.UsePresets(presets);           /* pots 2 + 3: save / load  */

settings.Page(1).Name("Mod")
        .Pot(0).Selector(3);            /* a custom 3-zone option   */

loop.Use(settings);
presets.Manage(settings);               /* use the serialization    */

Stock options

The preset gesture, exactly

Inside settings, the slot pot sweeps the sixteen slots; the ring shows the selection as four color groups of four arcs. The action pot commits: park it hard counter-clockwise and hold for three seconds to save into the selected slot, hard clockwise and hold to load. A progress arc fills during the hold, a white flash confirms the commit, and the commit calls presets.Save() / Load() directly.

Two protections are built in. Entering settings disarms the action pot: if it was already parked at an edge, nothing fires until you bring it through the neutral middle zone first, so there are no accidental saves on entry. And because loading rewrites the perf pager's values, the load path re-locks every page: pots wait to re-catch, and leaving settings does the same.

Custom controls

Declare controls per (page, pot) through the builder; each returns a typed handle whose setters refine it and whose .Value() reads it back at runtime. Keep the handle if you need the read.

State and appearance

ControlLoop and the Binder#

alchemy/surface/control_loop.h

ControlLoop is the conductor: it owns the main thread, polls hardware every millisecond, runs each attached surface in a fixed canonical order every 16 ms frame, renders the rings, and calls your hooks. You hand it surfaces with Use(); because each overload slots its argument into a fixed role, attach order never matters, because the point of teh ControlLoop is to sequentialy execute in a safe way.

Many developer use cases involve creating your own control loop to do something advanced. Take the control loop, copy it in your main function, and modify as desired.

static ControlLoop loop(hw);

loop.Use(pager).Use(locks).Use(settings).Use(cv_matrix)
    .Use(filter).Use(mod)
    .OnFrame(Bind);

for (;;) loop.Tick();

Construction and cadence

Audio rate and block size

hw.Init() takes the sample rate and the audio block size, defaulting to 48 kHz and the board's standard block. Smaller blocks tighten trigger-to-sound latency and cost more interrupt overhead; higher rates buy bandwidth and spend CPU.

hw.Init(daisy::SaiHandle::Config::SampleRate::SAI_96KHZ, 16);
my_dsp::Init(hw.SampleRate());     /* seed the DSP with the real rate */
hw.StartAudio(AudioCallback);      /* n per block == hw.BlockSize()   */

Attaching surfaces

Hooks and reads

The binder function

You need a function that reads each knob and hands finished values to your DSP. Hang it on OnFrame for control-rate updates, or read Value() straight from the audio callback for per-block freshness; both are correct, and most modules use both. Choose the appropriate rate for your DSP balanced against compute budget.

static void Bind()
{
    synth.SetCutoff(cutoff.Value());
    synth.SetRes   (reso.Value());
    synth.SetMode  (static_cast<int>(mode.Value()));
}

loop.OnFrame(Bind);

What runs when, exactly, and what one frame looks like from the inside: Firmware Anatomy is next, and it opens the machine this page has been enumerating.

Also in the framework: the LED ring vocabulary lives in LED Animations, and the SD card plus the browser link live in HostLink.