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))

For four choices, the boundaries are 0.25, 0.5, and 0.75. Values below 0.25 select option 0; values from 0.25 up to 0.5 select option 1; values from 0.5 up to 0.75 select option 2; and values from 0.75 through 1 select option 3.

Use a named label array with one label per choice. The labels describe the choices in the editor and manual; they do not change the selection boundaries.

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 · docs/pages-and-layers.md

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, runs pot catch, and decides which page is showing. 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).

Cycling is one way to reach a page. A module often wants others: a page shown only while a button is held, for secondary parameters like output levels, or a pair of sub-pages that one button toggles between. Built as its own surface, such a layer would have to redo everything a page already gets: pot catch, presets, param-lock banks, CV routing, ring rendering, and the web editor tab. So the SDK has no layer concept. A layer is a page selected by holding a button. The pager owns the page pool, and how each button navigates it is declared: Cycle advances on a release, Shift shows a page while held, Latch toggles a pair.

enum : uint8_t { kPageFilter, kPageMod, kPageLevels, kNumAppPages };

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(kPageFilter).Knobs(cutoff, reso, drive,
                                             env_amt, attack, release).Name("Filter");
static Page mod    = Page(kPageMod).Knobs(rate, depth, shape,
                                          offset, rise, fall).Name("Mod");
static Page levels = Page(kPageLevels).Knobs(out_level, mix, tone).Name("Levels");

static Pager pager = Pager(kNumAppPages, kNumPots)
    .Cycle(hw.buttons[kButtonB1], kPageFilter, kPageMod)   /* release advances */
    .Shift(hw.buttons[kButtonB2], kPageLevels);            /* page while held  */

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

Knobs on the layer are ordinary VirtualKnobs on an ordinary Page. presets.Manage(pager) persists its values with everything else, a ParamLock banks it, a CvMatrix routes to it, the rings draw it while it is held, and the web editor shows it as a tab. None of that is layer-specific code. The classic constructor Pager(hw.buttons[kButtonB1], 2, kNumPots) still works and means Pager(2, kNumPots).Cycle(hw.buttons[kButtonB1]): an empty cycle list is every page in order.

Page: composition

RGB page colors

Page::Color accepts a CSS string or LedPanel::Rgb. The RGB overload stores the color as #rrggbb in the page, including when the page is copied or assigned.

static constexpr LedPanel::Rgb kFilter = {0xc9, 0xa8, 0x4c};
static Page filter_page = Page(0).Name("Filter").Color(kFilter);
static Page delay_page = Page(1).Name("Delay").Color({0x70, 0x90, 0xc0});

Page::Color sets the browser tab and manual color. Pager::SetPageColor sets the physical page-button tint. CSS strings passed to Color(const char*) must remain alive while the page is used.

Hiding a control from the editor and manual

Use Page::HidePot() when a physical pot position should not appear as an editable control on that page.

page.HidePot(kPotBottomRight);         // hide P6
page.HidePot(kPotBottomRight, false);  // show P6 again

const bool hidden = page.PotHidden(kPotBottomRight);

Pot indices are zero-based. Hiding a position preserves its place on the physical panel and does not move the remaining controls.

Visibility is presentation metadata. The stored value remains in presets and factory defaults. The control can still participate in firmware processing and LED rendering; hiding it does not disable its hardware binding or DSP behavior.

An unassigned position is not automatically an explicitly hidden position. Declare visibility when you want the editor and manual to omit that control.

The control loop picks up runtime page composition changes on its next tick. Published browser metadata changes only after the firmware requests a descriptor refresh:

host.RequestDescriptorRefresh();

Runtime refresh requires stable field identities and storage layout. Use it for presentation changes, not for changing the shape of an existing preset.

Pager: navigation

One binding per button, at most four bindings, and one Shift layer active at a time. A binding that names an out-of-range page is rejected silently, the same rule GoToPage follows.

Pager: state

// One-time change during normal operation: page 0, top-left pot, 75%.
pager.SetStored(0, kPotTopLeft, 0.75f, loop.Phys());

Startup pickup

Call SetStored before the first control frame to set a pot's initial normalized value. Pickup initializes against the first live physical reading and preserves the stored value until the pot catches it.

// During setup, before the first loop.Tick():
pager.SetStored(0, kPotTopLeft, 0.75f, loop.Phys());

Set factory values before presets.Init() and presets.BootLoad(). The factory snapshot then includes those values, and a saved boot preset can replace them. Unseeded pots start from their physical positions. During normal operation, pass the current loop.Phys() readings to re-arm pickup.

Shift layers and the release contract

Two rules make a hold-to-show page work with no bookkeeping in the app.

Catch does the isolation. On the press edge the layer's page re-arms pot catch, so every pot is detached until it crosses its stored value on the layer. Motion during the press cannot move a base-page parameter. On release the pager returns to the page the press left and re-arms catch again, because the pot now sits wherever the layer edit parked it. Catch only ever runs on the active page, so the pages under a hold are untouched by construction: nothing is snapshotted and nothing is restored.

The release says what the hold was. A Shift button is usually also a tap button: tap to mute, hold and turn to edit the layer. Neither is known at press time, so the decision is made at release. A hold that caught no pot and moved none past the catch tolerance is clean and does not claim its release, and the tap fires. A hold that edited claims it, and a ButtonBank gesture declared on the same button stays quiet. App code outside the bank reads pager.HoldUsed(btn) instead. Releases process before that frame's catch, so a last-millisecond nudge cannot both edit the layer and pass for a clean tap.

That is the whole declaration for tap-to-mute plus hold-to-edit on one button:

static Pager pager = Pager(kNumAppPages, kNumPots)
    .Cycle(hw.buttons[kButtonB1])
    .Shift(hw.buttons[kButtonB2], kPageLevels);

static VirtualButton mute = VirtualButton(kButtonB2, "Mute")
    .Ident("out.mute").Toggle().Bind(SetMute);

static Page filter = Page(kPageFilter).Knobs(cutoff, reso, drive).Buttons(mute);

Arbitration

Three buttons serve navigation, ButtonBank gestures, the ParamLock trigger, and the Settings chord at once. The pager settles the collisions in one place so firmware never has to.

Locks bank at the press edge. ParamLock latches its slot bank when the trigger goes down, so a recording targets the page visible at press time. A layer released mid-hold, or a host-driven GoToPage, cannot retarget a recording in flight.

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);

From volts to a control value

CV modulation is added in normalized control space before the knob’s output transform is applied.

On Alchemy Lab V2, J3–J8 nominally map −10 V to 0, 0 V to 0.5, and +10 V to 1. A +5 V input therefore reads approximately 0.75. These are normalized readings; use Volts() when your application needs calibrated input voltage.

With bipolar modulation enabled, the SDK subtracts 0.5 from the normalized input, then applies the attenuation multiplier:

modulation = (normalized_input - 0.5) × attenuation

The result is added to the knob position and other modulation, then constrained to the control’s range.

For a centered Linear(-5, 5) control, +5 V at the input contributes 0.25 normalized units with unity attenuation. The resulting control value is +2.5. An attenuation multiplier of 2 makes that same input reach +5.

Atten(1) preserves the normalized contribution. Atten(-1) inverts it, Atten(0) removes it, and values above 1 increase its depth. This multiplier does not mean that one input volt becomes one output volt.

Bipolar(false) forwards the normalized input without subtracting 0.5. It does not remap a 0–5 V source onto 0–1: nominally, that source still occupies 0.5–0.75. Use an explicit mapping when your application needs a different voltage range.

The per-knob .Cv(index, attenuation, bipolar) binding uses the same normalized-space model. When a CvMatrix is attached to the control loop, it owns CV routing and the per-knob .Cv() bindings are ignored.

CvMatrix

Clocks and Timing#

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

One timestamp for the poll

MusicalClock advances a musical timeline from elapsed time. ClockFollower adjusts its rate from incoming pulses, and CvEdge timestamps transitions on the CV inputs.

All three must use the same microsecond timebase. Inside a ControlLoop poll hook, use loop.PollTimeUs(). Do not substitute daisy::System::GetUs(): dividing a wrapping hardware counter into microseconds gives it a different wrap period from the one these consumers expect.

This example receives a unipolar clock on J3:

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

static constexpr uint8_t kClockCvChan = 0u; // J3

static void OnPoll(uint32_t /*t_ms*/)
{
    const uint32_t now_us = loop.PollTimeUs();

    clk_edge.Tick(loop.Cv(), loop.NumCv(), now_us);

    if (clk_edge.JustRose(kClockCvChan))
        follower.OnPulse(clk_edge.LastRiseUs(kClockCvChan));

    follower.Update(now_us);
    clock_.Tick(now_us);
}

After hardware initialization and before starting the control loop:

CvEdge::Config cfg;
cfg.lo_threshold = 0.55f;
cfg.hi_threshold = 0.65f;
cfg.debounce_us = 500u;

clk_edge.Init(kNumCvInputs, cfg);
follower.SetAutoStart(true);
follower.Enable(kClockExtPpqnDefault);

loop.OnPoll(OnPoll);

The thresholds are above the nominal 0 V input value of 0.5 and suit a clock that rises from 0 V to +5 V. Choose thresholds for the actual source rather than treating one pair as suitable for every signal.

CvMatrix routing does not consume this clock input. The edge detector reads the sampled CV values independently.

Timing in a custom loop

A firmware with its own loop can use TickTimebase:

#include "alchemy/control/tick_timebase.h"

static alchemy::TickTimebase clock_time;

static void InitClockTime()
{
    clock_time.Init(
        daisy::System::GetTickFreq(),
        daisy::System::GetTick());
}

static uint32_t ReadClockTimeUs()
{
    return clock_time.Update(daisy::System::GetTick());
}

Call InitClockTime() after hardware initialization. At each poll, call ReadClockTimeUs() once and pass that value to the related edge detectors, follower, and musical clock.

Update the timebase from one context only. Calls must be closer together than one full raw-counter wrap, about 17.9 seconds at 240 MHz. If the timer restarts or changes frequency, reinitialize the timebase and its timing consumers together.

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.

Thresholds are expressed in normalized input values, not volts. On V2, an unpatched J3–J8 input rests near 0.5. A unipolar 0 V to +5 V pulse therefore moves approximately between 0.5 and 0.75.

For that source, thresholds such as 0.55 low and 0.65 high allow the detector to return to its low state between pulses. A low threshold of 0.30 would not be crossed by a signal that returns only to 0 V.

Use thresholds on opposite sides of the actual switching region, with enough separation to reject noise. CvGate is appropriate when the held level matters. J1/J2 use the separate codec-input RisingEdge() detector and cannot recover a sustained DC gate level.

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 · alchemy/control/lock_types.h · docs/param-locks.md

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. Recording arms at 0.5% of travel. A 3% move on a pot that is already looping clears it. Two behaviors are optional: a Clocked mode that restarts each loop on the musical grid, and an exit policy that decides where the knob's value lands when the button is released. Capacity is a compile-time declaration.

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.

Behavior

Everything here is optional. The declaration alone gives: arm at 0.5%, clear at 3%, Latch exit, a solid red pip while recording, a blinking red pip during playback, free-running loops. Each call overrides one setting; the values shown are the defaults.

locks.UseClock(clock_)                                  /* enables Clocked mode  */
     .SnapGrid(LockGrid::Straight | LockGrid::Triplet)  /* | LockGrid::Dotted    */
     .ArmThreshold(0.005f)
     .ClearThreshold(0.03f)
     .ExitMode(LockExit::Latch)                         /* or LockExit::Return   */
     .RecordStyle({0xFF, 0x00, 0x00}, LockAnim::Solid)
     .PlayStyle  ({0xFF, 0x00, 0x00}, LockAnim::Blink);

Clocked mode

A free loop replays at the wall-clock length it was recorded, so against a sequencer it drifts within a few bars. In Clocked mode a finished recording snaps its loop boundary to the nearest musical duration: record roughly one bar of motion and the loop restarts on exactly one bar, and keeps restarting there through tempo changes. Only the boundary snaps, and three properties follow:

Motion is never resampled. Playback runs at the recorded speed. A take longer than the snapped length is truncated: samples past the boundary are never reached. A shorter take holds its final value until the restart. At a stable tempo either correction is the few milliseconds by which the take missed the grid.

The boundary follows the clock. The loop starts where the gesture ended; the start is not quantized to the bar. Restart times are computed from the clock's absolute position rather than accumulated, so tempo changes and follower drift move the restart and never the motion speed. If the clock slows, the motion plays out, holds its final value, and restarts on the later grid. If it speeds up, each pass replays only the front of the take.

A stopped transport freezes clocked loops. Free loops keep running. On signal loss, behavior follows the follower's loss policy.

The take's duration is measured in clock ticks, a stamp at arm and a delta at release, so control-loop frame jitter cannot shift the snap and a tempo change made during the recording is accounted for. The grid is nearest-by-ratio across the enabled note families, from a 16th to a whole note, plus integer bar counts above one bar.

The mode is consulted at record time only. Every slot stores which timing it was captured under, so changing the setting never re-times an existing lock, and one preset can mix free and clocked slots. Storing musical ticks rather than milliseconds has two more consequences: a lock saved as two bars restarts every two bars at any later tempo, and slots restored from a preset anchor at the clock's origin, so slots of equal musical length restart together. If Clocked is selected but the clock is not running when a recording ends, or no clock was wired, that slot falls back to free and replays at its recorded length. Recording is never refused.

LED styles

The stock overlay is a pip at 6 o'clock on any ring whose slot is active. RecordStyle and PlayStyle set its color and animation. The animations have no tuning parameters; for anything else, skip the stock Render() and draw the ring yourself from IsActive(), IsRecording(), and PlayPhase().

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

Settings stores and renders up to eight pages of controls. Hold B2+B3 for two seconds to enter, press B1 to cycle pages, and tap B2 or B3 to leave. On exit, the performance pager re-arms pot pickup.

static Settings settings(hw, &pager);

settings.UseBrightness();               /* page 0, pot 0            */
settings.UsePresets(presets);           /* pots 2 + 3: save / load  */
settings.UseLocks(locks);               /* pots 4 + 5: sync / exit  */

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

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

Page indices are 0–7. HostLink describes each declared page. midi::MonoSettings uses two consecutive pages for MIDI Notes and MIDI Control; see MIDI settings for setup and applying their values in the audio callback.

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()   */

Starting the audio path without application DSP

On Alchemy Lab V2, hw.StartAudio() can run without an application callback:

hw.Init();
hw.StartAudio();

The SDK still processes J1/J2 trigger detection and fills J9/J10 channels claimed for CV output. Unclaimed audio outputs are cleared.

Use hw.StartAudio(AudioCallback) when the application processes audio. A claimed codec CV output is filled by the SDK after that callback returns, replacing the samples written to that channel. DisableCvOutput() returns the channel to the application callback.

The audio callback, control polling, and LED frame are separate schedules. At 48 kHz with 24-sample blocks, the audio callback runs 2,000 times per second. The default control loop polls approximately every millisecond and renders approximately every 16 ms.

Keep formatted diagnostics and blocking peripheral operations on the main/control thread. A diagnostics gauge can publish a scalar from the audio callback without formatting or transmitting USB data there.

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.