Template-based C++ firmware for ARM Cortex-M processors

Application structure

We build with a painter's workshop as our guiding abstraction. In this concept, the hardware is the canvas, Sound Byte Libs is the toolkit (paint, brushes, palette knives, etc), and the application is the artwork.

Layer-based API structure

Sound Byte Libs uses a layer-based architecture where each layer builds on those below it:

Widgets (Layer 5)
  ↓
Components (Layer 4)
  ↓  
Patterns (Layer 3)
  ↓
Primitives (Layer 2)
  ↓  
HAL (Layer 1)

Layer 1: HAL (Hardware Abstraction)

Location: src/sbl/hal/

Direct hardware access templates that resolve to platform-specific implementations:

GPIO ports and pins
Timers and PWM
Interrupt controllers
Memory barriers
System-level hardware interfaces

Layer 2: Primitives (Basic Building Blocks)

Location: src/sbl/primitives/

Essential data structures and algorithms with no hardware dependencies:

primitives/buffers/ - Ring buffers, FIFOs
primitives/containers/ - Fixed arrays, lists
primitives/math/ - Integer math, fixed-point utilities
primitives/io/ - Lightweight printf implementation

Layer 3: Patterns (Reusable Design Patterns)

Location: src/sbl/patterns/

Template-based patterns that combine primitives with HAL:

patterns/timing/ - Non-blocking delays, interval timers
patterns/synchronization/ - Critical sections, atomic operations
patterns/events/ - Event broadcasting, observers

Layer 4: Components (Functional Units)

Location: src/sbl/components/

Mid-level functional components for common hardware interfaces:

components/display/ - LEDs, basic displays
components/cv/ - Trigger generators, gate handlers
components/input/ - Buttons, encoders

Layer 5: Application Integration

Applications combine components and patterns to build complete functionality. The library provides building blocks; applications compose them according to their specific needs.

Cross-cutting Concerns

Common (src/sbl/common/): Shared constants, sensible defaults, cross-layer utilities

Utils (src/sbl/utils/): Development and debugging tools like logging

Validation (src/sbl/validation/): Compile-time validation and error messaging

Template-based HAL

When you build, templates resolve to concrete platform types. A GPIO template becomes STM32 HAL calls, RP2040 SDK calls, or SAMD peripheral access - whatever your specific ARM Cortex-M platform provides.

Minimal runtime dispatch, optimized for ARM Cortex-M with direct hardware access wrapped in clean APIs.

Platform Neutrality

The core library contains zero platform-specific code. No #ifdef blocks, no hardcoded platform names, no conditional compilation.

MCU driver implementations are maintained separately in the sbl-hardware repository. The build system discovers them via sloth resolution from sbl.json.

This approach provides architectural integrity. Every MCU is equal - there are no defaults or preferred platforms baked into the core library.

Configuration System

Applications define hardware through sbl.json, which points to a mainboard manifest. The sloth tool resolves the manifest chain and generates <sbl/hw/hardware.hpp> with compile-time constants.

See namespaces.md for the namespace structure.

Memory Management

Static allocation only.

Platform Support

MCU drivers are maintained in sbl-hardware and implement the HAL interfaces. Exclusively supports 32-bit ARM Cortex-M processors.

Hardware Manifest System

Hardware is described using JSON manifests that define connections and generate type-safe handles at build time. The manifest system supports:

Mainboards - Primary boards with MCU running SBL (e.g., Raspberry Pi Pico, STM32 dev boards)
Modules - Expansion boards or ICs that attach to mainboards (e.g., LED panels, DAC chips)

Mainboards expose pins and buses; modules claim them. The resolver walks the attaches_to chain to map logical pin names to physical MCU registers with conflict detection.

See the Hardware Schema Documentation for schema definitions and diagrams.

Platform Contract Validation

Sound Byte Libs enforces platform implementations through compile-time SFINAE validation. Every platform must satisfy interface contracts with clear error messages guiding implementation.

Project Structure

Typical audio application setup:

your-app-name/
├── hardware/                   # Schematics, PCB
└── firmware/
    ├── main.cpp                # Application entry point
    ├── sbl.json                # Hardware target configuration
    └── CMakeLists.txt          # Build configuration

Environment variables point to library locations:

SBL_PATH - Path to sound-byte-libs
SBL_HW_PATH - Path to sbl-hardware