Sound Byte Libs 29c5ff3
C++ firmware library for audio applications on 32-bit ARM Cortex-M processors
Loading...
Searching...
No Matches
SBL Namespace Guide

Sound Byte Libs uses a structured namespace hierarchy to separate generated code from static implementations.

Namespace Overview

Namespace Purpose Location
sbl::driver:: MCU driver implementations sbl-hardware/mcu/*/driver/
sbl::hw:: Generated hardware configuration build/generated/sbl/hw/config/
sbl::hw::gpio:: Generated GPIO handles build/generated/sbl/hw/config/gpio.hpp
sbl::hw::adc:: Generated ADC handles build/generated/sbl/hw/config/adc.hpp
sbl::hw::uart:: Generated UART handles build/generated/sbl/hw/config/uart.hpp
sbl::hw::mcu:: MCU metadata build/generated/sbl/hw/config/mcu.hpp
sbl::hw::Board Generated Board abstraction build/generated/sbl/hw/config/board.hpp
sbl::gpio:: GPIO types (PinMode) src/sbl/hal/gpio/types.hpp
sbl::adc:: ADC convenience functions src/sbl/hal/adc/driver.hpp, src/sbl/hal/adc/scan.hpp
sbl::cv:: CV input convenience functions src/sbl/hal/cv/input.hpp
sbl::audio:: Audio output convenience src/sbl/hal/audio/driver.hpp
sbl::button:: Button HAL convenience src/sbl/hal/button/input.hpp
sbl::encoder:: Encoder HAL convenience src/sbl/hal/encoder/input.hpp
sbl::led:: RGB LED HAL convenience src/sbl/hal/led/output.hpp
sbl::pot:: Potentiometer HAL convenience src/sbl/hal/pot/input.hpp
sbl::voct:: V/Oct HAL convenience src/sbl/hal/cv/voct.hpp
sbl::dsp:: DSP atoms (phase, filters, delay, fast_math) src/sbl/dsp/
sbl::dsp::lut:: Lookup table functions src/sbl/dsp/lut.hpp
sbl::signal:: Signal composition (Frame, exp_mod) src/sbl/signal/
sbl::midi:: MIDI parser and input src/sbl/midi/
sbl::widgets::source:: Sound sources (oscillators, noise) src/sbl/widgets/source/
sbl::widgets::proc:: Processing (SVF, VCA, Delay, PlateReverb) src/sbl/widgets/proc/
sbl::widgets::mod:: Modulation (envelope, LFO) src/sbl/widgets/mod/
sbl::log:: Logging utilities (Logger, Level) src/sbl/log/
sbl::defaults:: Sensible buffer size constants src/sbl/common/defaults.hpp
sbl::version:: Library version info (CMake-generated) build/include/sbl/version.hpp
sbl::meta:: Hardware metadata (sloth-generated) build/generated/sbl/hw/meta.hpp
sbl:: Non-generated types (handles) src/sbl/types.hpp

<tt>sbl::driver::</tt> - MCU Drivers

MCU-specific driver implementations. These are static files maintained in the sbl-hardware repository and included via CMake.

#include <sbl/hw/hw.hpp> // Single include for drivers + config
sbl::driver::init();
sbl::driver::Gpio::set_mode(sbl::hw::gpio::status_led, sbl::gpio::PinMode::Output);
sbl::driver::Gpio::write(sbl::hw::gpio::status_led, true);
sbl::driver::Gpio::toggle(sbl::hw::gpio::status_led);
sbl::driver::Timer::busy_wait_ms(500);
sbl::driver::Uart<>::init(sbl::hw::uart::debug); // Debug UART (instance 0)
sbl::driver::Uart<>::write_byte('A');
sbl::driver::Uart<1>::init_rx(sbl::hw::uart::midi); // MIDI UART (instance 1)
hw.hpp
Uber-umbrella header for all target-specific code.

Individual driver headers are also available:

#include <sbl/hw/driver/gpio.hpp>
#include <sbl/hw/driver/timer.hpp>
#include <sbl/hw/driver/uart.hpp>
#include <sbl/hw/driver/adc.hpp> // ADC driver (STM32H7)
#include <sbl/hw/driver/sai.hpp> // SAI/I2S audio driver (STM32H7)
#include <sbl/hw/driver/dma.hpp> // DMA controller (STM32H7)
#include <sbl/hw/driver/dma_buffer.hpp> // SBL_DMA_BUFFER macro (STM32H7)
#include <sbl/hw/driver/init.hpp>

Contents:

  • Gpio - GPIO read/write/mode/toggle operations (handle-first API)
  • Timer - Delay functions and millis counter
  • Uart<N> - Multi-instance UART (template on instance index, default 0)
  • Adc - ADC initialization, polling reads, and DMA scan mode (STM32H7)
  • Sai - SAI/I2S full-duplex audio with DMA (STM32H7)
  • init() - MCU initialization
  • init_audio() - Audio subsystem init: PLL2, SAI GPIO, codec reset (STM32H7)

<tt>sbl::adc::</tt> - ADC Convenience Functions

Convenience namespace for ADC operations:

#include <sbl/hal/adc/driver.hpp>
// Blocking single-channel read (polling mode)
uint16_t value = sbl::adc::read<sbl::driver::Adc>(sbl::hw::adc::knob1);
driver.hpp
ADC driver interface - canonical types for MCU driver implementations.

DMA-based continuous multi-channel scanning:

#include <sbl/hal/adc/scan.hpp>
#include <sbl/hw/driver/dma_buffer.hpp>
SBL_DMA_BUFFER static uint16_t adc_buf[2];
const sbl::AdcHandle channels[] = { sbl::hw::adc::knob1, sbl::hw::adc::knob2 };
// Start continuous DMA scan — ADC runs in background, buffer always fresh
sbl::adc::start_scan<sbl::driver::Adc>(channels, 2, adc_buf);
// Stop scan (polling functions available again after this)
sbl::adc::stop_scan<sbl::driver::Adc>();
scan.hpp
ADC DMA scan interface — continuous multi-channel acquisition.
sbl::AdcHandle
ADC channel handle.
Definition handle.hpp:29

<tt>sbl::cv::</tt> - CV Input Convenience Functions

Composes ADC reads with CvInput smoothing in a single call:

#include <sbl/hal/cv/input.hpp>
sbl::cv::CvInput knob;
// Blocking read + smooth (polling mode)
sbl::cv::read<sbl::driver::Adc>(knob, handle, adc::SampleTime::Slow);
// DMA buffer read + smooth (scan mode — zero CPU overhead)
sbl::cv::read_dma(knob, adc_buf, 0); // channel_index into scan buffer
sbl::components::cv::CvInput
Smoothed CV input with EWMA filtering and range scaling.
Definition input.hpp:51
input.hpp
CV input convenience functions.
sbl::cv::read_dma
uint16_t read_dma(CvInput &input, const uint16_t *buffer, uint8_t channel_index)
Read from DMA scan buffer and feed into CvInput filter.
Definition input.hpp:63

<tt>sbl::audio::</tt> - Audio Output Convenience

Portable audio output that wraps driver-specific details:

#include <sbl/hal/audio/driver.hpp>
void my_callback(int32_t* tx, const int32_t* rx, uint16_t frames) { /* ... */ }
sbl::audio::start<sbl::driver::Sai>(my_callback);
driver.hpp
Audio driver interface - canonical types and convenience functions.

<tt>sbl::button::</tt> - Button HAL Convenience

#include <sbl/hal/button/input.hpp>
sbl::components::control::Button btn;
sbl::button::read<sbl::driver::Gpio>(btn, sbl::hw::gpio::button1);
sbl::components::control::Button
Debounced button with edge detection and held-duration tracking.
Definition button.hpp:35
input.hpp
Button input convenience functions.

<tt>sbl::encoder::</tt> - Encoder HAL Convenience

#include <sbl/hal/encoder/input.hpp>
sbl::components::control::Encoder enc;
sbl::encoder::read<sbl::driver::Gpio>(enc, sbl::hw::gpio::encoder_a, sbl::hw::gpio::encoder_b);
sbl::components::control::Encoder
Quadrature encoder with Gray code state machine and position tracking.
Definition encoder.hpp:31
input.hpp
Encoder input convenience functions.

<tt>sbl::led::</tt> - RGB LED HAL Convenience

#include <sbl/hal/led/output.hpp>
sbl::components::display::RgbLed led;
sbl::led::write<sbl::driver::Gpio>(led, sbl::hw::gpio::led1_r, sbl::hw::gpio::led1_g, sbl::hw::gpio::led1_b);
sbl::components::display::RgbLed
RGB LED state holder with 8-bit per-channel duty cycle.
Definition rgb_led.hpp:56
output.hpp
RGB LED output convenience functions.

<tt>sbl::pot::</tt> - Potentiometer HAL Convenience

#include <sbl/hal/pot/input.hpp>
sbl::components::control::Pot pot;
sbl::pot::read_dma(pot, adc_buf, 0); // DMA scan mode
sbl::components::control::Pot
Potentiometer with EWMA smoothing, deadband, and change detection.
Definition pot.hpp:50
input.hpp
Pot input convenience functions.
sbl::pot::read_dma
uint16_t read_dma(Pot &pot, const uint16_t *buffer, uint8_t channel_index)
Read from DMA scan buffer and feed into Pot.
Definition input.hpp:62

<tt>sbl::voct::</tt> - V/Oct HAL Convenience

#include <sbl/hal/cv/voct.hpp>
sbl::components::cv::VoctInput voct;
sbl::voct::read_dma(voct, adc_buf, 0);
float freq = voct.frequency(); // Hz from calibrated V/Oct
sbl::components::cv::VoctInput
V/Oct pitch CV input with smoothing and calibration.
Definition voct.hpp:88
sbl::components::cv::VoctInput::frequency
float frequency() const
Frequency in Hz (via pitch tables)
Definition voct.hpp:113
voct.hpp
V/Oct input convenience functions.
sbl::voct::read_dma
void read_dma(VoctInput &input, const uint16_t *buffer, uint8_t channel_index)
Read from DMA scan buffer and feed into VoctInput.
Definition voct.hpp:59

<tt>sbl::dsp::</tt> - DSP Atoms (Audio Stack)

Single-concern signal processing primitives. Each atom manipulates one property of sound. No hardware dependencies.

#include <sbl/dsp/phase.hpp>
#include <sbl/dsp/one_pole.hpp>
#include <sbl/dsp/slew.hpp>
#include <sbl/dsp/delay_line.hpp>
#include <sbl/dsp/pitch.hpp>
#include <sbl/dsp/fast_math.hpp>
#include <sbl/dsp/lut.hpp>
sbl::dsp::PhaseAccumulator phase;
phase.set_frequency(440000); // millihertz
phase.advance();
float ratio = sbl::dsp::semitones_to_ratio(7.0f); // Perfect fifth
float freq = sbl::dsp::note_to_frequency(69.0f); // A4 = 440 Hz
float val = sbl::dsp::lut::lookup_linear<1024>(sbl::dsp::lut::sin_1024, phase.value());
float val2 = sbl::dsp::lut::lookup_cubic<1024>(sbl::dsp::lut::sin_1024, phase.value());
// Fast math approximations
float e = sbl::dsp::fast_exp2f(x); // ~8 cycles on M7, <0.1% error
float t = sbl::dsp::fast_tan_pif(f); // [5,4] Pade, ~20 cycles on M7
float s = sbl::dsp::fast_sinf(x); // Taylor series
sbl::dsp::PhaseAccumulator::advance
void advance()
Advance phase by one sample.
Definition phase.hpp:36
delay_line.hpp
fast_math.hpp
sbl::dsp::lut::lookup_linear
uint16_t lookup_linear(const uint16_t *table, uint32_t phase)
Definition lut.hpp:39
sbl::dsp::lut::sin_1024
constexpr float sin_1024[1026]
Definition sin_1024.hpp:10
sbl::dsp::fast_tan_pif
float fast_tan_pif(float f)
Definition fast_math.hpp:68
sbl::dsp::note_to_frequency
float note_to_frequency(float midi_note)
MIDI note to frequency in Hz. A4 = 440 Hz.
Definition pitch.hpp:52
sbl::dsp::fast_sinf
float fast_sinf(float x)
Definition fast_math.hpp:38
sbl::dsp::semitones_to_ratio
float semitones_to_ratio(float semitones)
Definition pitch.hpp:26
sbl::dsp::fast_exp2f
float fast_exp2f(float x)
Definition fast_math.hpp:96
one_pole.hpp

<tt>sbl::signal::</tt> - Signal Composition (Audio Stack)

Composed building blocks that eliminate boilerplate in audio callbacks. Sits between atoms and widgets in the Audio Stack.

#include <sbl/signal/frame.hpp>
#include <sbl/signal/exp_mod.hpp>
// Stereo buffer management
sbl::signal::Frame<48> frame;
uint16_t n = frame.begin(frames);
// ... render into frame.left[], frame.right[] ...
frame.scale(0.5f, n); // headroom
frame.end(tx, n); // interleave to DMA
// Exponential modulation (the "exponential converter IC")
float freq = sbl::signal::exp_mod(1000.0f, lfo_val, 2.0f); // 1kHz ±2 octaves
// Block version for modulation buffers
sbl::signal::exp_mod_block(lfo_buf, freq_out, n, base_hz, depth_oct);
exp_mod.hpp
sbl::signal::exp_mod_block
void exp_mod_block(const float *mod, float *freq_out, uint16_t n, float base, float depth, float lo=20.0f, float hi=20000.0f)
Definition exp_mod.hpp:70
sbl::signal::exp_mod
float exp_mod(float base, float mod, float depth, float lo=20.0f, float hi=20000.0f)
Definition exp_mod.hpp:49
sbl::signal::Frame::begin
uint16_t begin(uint16_t requested)
Definition frame.hpp:50
sbl::signal::Frame::end
void end(int32_t *tx, uint16_t n) const
Definition frame.hpp:66
sbl::signal::Frame::scale
void scale(float gain, uint16_t n)
Definition frame.hpp:76

Design principle: Signals follow [-1.0, 1.0]. Configuration uses engineering units. exp_mod() bridges the gap at the modulation point — exactly as in analog hardware.

<tt>sbl::midi::</tt> - MIDI Parser & Input

Stream-based MIDI parser with running status, real-time passthrough, and channel filtering:

#include <sbl/midi/parser.hpp>
#include <sbl/midi/input.hpp>
sbl::midi::Parser parser;
parser.set_callback(my_handler);
parser.set_channel(0xFF); // Omni
// Poll in main loop — reads UART and feeds parser
sbl::midi::poll<MidiUart>(parser);
sbl::midi::Parser
MIDI byte stream parser — state machine with running status.
Definition parser.hpp:35
sbl::midi::Parser::set_callback
void set_callback(MidiCallback cb)
Set the callback for parsed MIDI events.
Definition parser.hpp:41
sbl::midi::Parser::set_channel
void set_channel(uint8_t ch)
Set channel filter.
Definition parser.hpp:48

<tt>sbl::widgets::</tt> - Widgets (Audio Stack)

User-facing audio components — "module on a panel" abstractions:

#include <sbl/widgets/source/wavetable_osc.hpp>
#include <sbl/widgets/proc/svf.hpp>
#include <sbl/widgets/proc/vca.hpp>
#include <sbl/widgets/mod/envelope.hpp>
#include <sbl/widgets/mod/lfo.hpp>
sbl::widgets::source::WavetableOsc<1024> osc;
sbl::widgets::proc::Svf filter;
sbl::widgets::proc::Vca vca;
sbl::widgets::mod::Envelope<> env = sbl::widgets::mod::Envelope<>::adsr(50.0f, 200.0f, 0.6f, 300.0f);
sbl::widgets::mod::Lfo<1024> lfo;
// Per-sample modulated filtering (LFO -> cutoff, exponential)
lfo.process(lfo_buf, n);
filter.process_modulated(buf, n, lfo_buf, 2000.0f, 2.0f); // 2kHz center, ±2 octaves
sbl::widgets::mod::Envelope::adsr
static Envelope adsr(float attack_ms, float decay_ms, float sustain, float release_ms, float curve=0.0f)
Definition envelope.hpp:35
sbl::widgets::mod::Lfo::process
void process(float *out, uint16_t frames)
Generate modulation signal (bipolar: -depth to +depth)
Definition lfo.hpp:81
sbl::widgets::proc::Svf::process_modulated
void process_modulated(float *buf, uint16_t frames, const float *mod, float center, float depth, float lo=20.0f, float hi=20000.0f)
Process with per-sample exponential cutoff modulation.
Definition svf.hpp:162
wavetable_osc.hpp

<tt>sbl::gpio::</tt> - GPIO Types

GPIO-related types defined in src/sbl/hal/gpio/types.hpp:

sbl::gpio::PinMode::Output
sbl::gpio::PinMode::Input
sbl::gpio::PinMode::InputPullup
sbl::gpio::PinMode::InputPulldown

<tt>sbl::hw::</tt> - Generated Hardware Configuration

Build-time generated headers containing hardware-specific constants resolved from manifests by sloth.

Generated files in build/generated/sbl/hw/config/:

  • gpio.hpp - GPIO handles
  • adc.hpp - ADC handles (if any ADC claims)
  • uart.hpp - UART handles (if any UART claims)
  • board.hpp - Board abstraction (if components defined)
  • mcu.hpp - MCU metadata
  • system.hpp - System configuration
  • meta.hpp - Target/MCU metadata
#include <sbl/hw/hw.hpp> // Includes all config + drivers
constexpr auto led = sbl::hw::gpio::status_led; // GpioHandle{0, 25, false}
constexpr auto midi = sbl::hw::uart::midi; // UartHandle{1, ...31250}

Sub-namespaces:

  • sbl::hw::gpio:: - GPIO handles (e.g., status_led)
  • sbl::hw::adc:: - ADC handles (e.g., knob1, knob2)
  • sbl::hw::uart:: - UART handles (e.g., debug, midi)
  • sbl::hw::system:: - Configuration values (e.g., sysclk_mhz)
  • sbl::hw::mcu:: - MCU metadata (e.g., name, family)
  • sbl::hw::Board - Board struct with typed component members (e.g., board.knob1, board.button1)

<tt>sbl::</tt> - Non-Generated Types

Handle types defined in static headers for IDE/LSP support. These types are used by both generated and driver code.

#include <sbl/types.hpp>
// Handle types
sbl::GpioHandle // { port, pin, active_low }
sbl::AdcHandle // { adc, channel }
sbl::UartHandle // { instance, tx_port, tx_pin, tx_af, rx_port, rx_pin, rx_af, baud }
sbl::PwmHandle // { timer, channel }
sbl::GpioHandle
GPIO pin handle with port, pin number, and polarity.
Definition handle.hpp:29
sbl::PwmHandle
PWM output handle.
Definition types.hpp:33
sbl::UartHandle
UART peripheral handle.
Definition handle.hpp:28
types.hpp
Common types for SBL hardware abstraction.

Handles are passed directly to driver functions (handle-first API):

// The driver handles active-low logic internally
sbl::driver::Gpio::write(sbl::hw::gpio::status_led, true); // LED on
sbl::driver::Gpio::toggle(sbl::hw::gpio::status_led); // Toggle LED

Optional Aliases

For shorter code, include <sbl/aliases.hpp>:

#include <sbl/aliases.hpp>
// Now available directly in sbl::
sbl::Gpio::set_mode(pin, sbl::PinMode::Output);
sbl::Timer::busy_wait_ms(500);
sbl::init();
aliases.hpp
Optional convenience aliases for SBL namespaces.

This is opt-in. The explicit sbl::driver:: form is recommended for clarity in embedded code.

<tt>sbl::defaults::</tt> - Sensible Buffer Defaults

Pre-defined buffer size constants for embedded contexts:

#include <sbl/common/defaults.hpp>
sbl::defaults::SMALL_BUFFER // 12 bytes (short strings)
sbl::defaults::MEDIUM_BUFFER // 64 bytes (typical messages)
sbl::defaults::LARGE_BUFFER // 256 bytes (formatted output)
sbl::defaults::LOG_MESSAGE // 256 bytes (alias for log buffers)
defaults.hpp
Sensible default constants for embedded systems.
sbl::defaults::LOG_MESSAGE
constexpr std::size_t LOG_MESSAGE
Maximum log message length.
Definition defaults.hpp:39
sbl::defaults::LARGE_BUFFER
constexpr std::size_t LARGE_BUFFER
Large buffer size for log messages, etc.
Definition defaults.hpp:34
sbl::defaults::SMALL_BUFFER
constexpr std::size_t SMALL_BUFFER
Small buffer size for number formatting, etc.
Definition defaults.hpp:24
sbl::defaults::MEDIUM_BUFFER
constexpr std::size_t MEDIUM_BUFFER
Medium buffer size for string operations.
Definition defaults.hpp:29

<tt>sbl::version::</tt> - Library Version

CMake-generated version info from git tags:

#include <sbl/version.hpp>
sbl::version::major // 0
sbl::version::minor // 1
sbl::version::patch // 6
sbl::version::string // "0.1.6"
sbl::version::full_string // "0.1.6-48-g79632a7" (git describe)
sbl::version::git_hash // "79632a7"
sbl::version::git_dirty // true/false
sbl::version::number // 106 (for numeric comparisons)
sbl::version::is_at_least(0, 1, 5) // true

<tt>sbl::meta::</tt> - Hardware Metadata

sloth-generated metadata about the target hardware:

#include <sbl/hw/meta.hpp>
sbl::meta::manifest_schema // "0.1"
sbl::meta::target::name // "daisy-seed"
sbl::meta::target::manifest_version // "1.0.0"
sbl::meta::target::hw_revision // "1.0"
sbl::meta::mcu::name // "stm32h750"
sbl::meta::mcu::manifest_version // "1.0.0"

<tt>sbl::log::</tt> - Logging System

Lightweight, zero-overhead logging for embedded development:

#include <sbl/log/log.hpp>
// Define output sink and timestamp provider
struct UartOutput {
static void write(const char* str) { sbl::driver::Uart<>::write_string(str); }
};
struct Timestamp {
static uint32_t now() { return sbl::driver::Timer::millis(); }
};
// Enable macros with compile-time level filtering
#define SBL_LOG_OUTPUT UartOutput
#define SBL_LOG_TIMESTAMP Timestamp
#define SBL_LOG_LEVEL SBL_LOG_LEVEL_INFO
#include <sbl/log/macros.hpp>
// Use in code
SBL_LOG_INFO("System started");
SBL_LOG_DEBUG("Debug info"); // Compiled out if level < DEBUG
SBL_LOG_ERROR("Error: %d", err);
log.hpp
Logging system umbrella header.
macros.hpp
Zero-overhead logging macros with file/line capture.
SBL_LOG_INFO
#define SBL_LOG_INFO(...)
Definition macros.hpp:104
SBL_LOG_DEBUG
#define SBL_LOG_DEBUG(...)
Definition macros.hpp:111
SBL_LOG_ERROR
#define SBL_LOG_ERROR(...)
Main logging macros with compile-time level filtering.
Definition macros.hpp:90

Log levels (compile-time constants for #if compatibility):

  • SBL_LOG_LEVEL_OFF (0) - Disable all logging
  • SBL_LOG_LEVEL_ERROR (1)
  • SBL_LOG_LEVEL_WARN (2)
  • SBL_LOG_LEVEL_INFO (3)
  • SBL_LOG_LEVEL_DEBUG (4)
  • SBL_LOG_LEVEL_TRACE (5)

Output format: I 12345 main.cpp:42| Message

Generated by doxygen 1.9.8