How benediktschoeffmann/pikocore works
Project Type and Purpose
• Type: Embedded firmware project with a host‐side tool.
• Purpose: Provides firmware (“pikocore”) for the Raspberry Pi Pico that mangles and sequences audio (lo-fi music effects) and drives LEDs, plus a Go CLI tool (audio2h) that converts audio files into C headers for inclusion in the firmware image.
Main Components
A. Host Environment & Build Pipeline
1. audio2h (Go CLI tool)
• Converts .flac or other audio files in audio2h/demo/ to C arrays (.h) for embedding.
• Dependencies: Go modules (go.mod), Python scripts (generate_easing.py, biquad.py) for filter and easing data.
2. Build System
• Makefile, CMakeLists.txt, target_compile_definitions.cmake, pico_sdk_import.cmake
• Invokes Pico SDK, GCC toolchain, CMake, and Python to generate final UF2 image.
3. Host Tooling
• make prereqs installs clang-format, cmake, gcc, python, pico SDK, etc.
B. Firmware (C++ / PIO)
1. Core Application (main.cpp, main.go test harness)
• Initializes subsystems: sequencer, easing, audio playback, MIDI/clock input, LED driver.
2. Subsystem Modules
• Sequencer (doth/sequencer.h): Controls timing, BPM, gate, and triggers.
• MIDI & Clock In (onewiremidi.h/.pio): Optional MIDI input or clock input via PIO.
• LED Control (WS2812.cpp/.pio, led.h, ledarray.h): Drives addressable LEDs using PIO.
• Easing & Filters (doth/easings/*, biquad.py): Generates LFOs, distortion, probability functions for audio mangling.
• Audio Mangling (dither.h, trigger_out.h, runningavg.h, doth/dither.h): Implements lo-fi effects.
3. Configuration (target_compile_definitions.cmake)
• Compile‐time flags: WS2812_ENABLED, MIDI_IN_ENABLED, memory size (2MB vs.16MB Pico).
C. Hardware
• Raspberry Pi Pico
• Peripherals: WS2812 LED strip, audio DAC (on-chip PWM), input button/knobs (GPIO & PIO).
• External: Power, audio input, MIDI interface (optional).
Relationships & Data Flow
1. Design-Time
• Artist runs make audio -> audio2h reads .flac -> embeds data in generated_audio.h.
• CMake/Pico SDK compiles C++ + generated headers -> firmware .uf2.
2. Run-Time on Pico
• Clock/MIDI → Sequencer → triggers events
• Sequencer/Easing → Configure audio mangling parameters
• Audio Data (embedded) + parameters → Audio mangling algorithms → PWM audio output
• Sequencer/Easing → LED driver → PIO → WS2812 LEDs
• User input (knobs/buttons) → influences sequencer/Easing parameters
Architectural Patterns & Design Principles
• Modular C++ Subsystems: Each feature (LED, MIDI, audio filters) lives in its own header/.cpp or PIO file.
• Separation of Concerns: Host tool (audio2h) is completely separate from firmware.
• Data-Embedded Firmware: Uses generated C arrays for static audio content.
• PIO Offload: Time-critical LED/MIDI I/O handled by PIO state machines.