# benediktschoeffmann/pikocore architecture

> Architecture diagram of the GitHub repository benediktschoeffmann/pikocore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benediktschoeffmann/pikocore
- Repository: https://github.com/benediktschoeffmann/pikocore

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment & Build Pipeline
    subgraph "Host Environment & Build" 
        direction TB
        AudioFiles["Audio Files (.flac)"]:::host
        Audio2H["audio2h (Go CLI)"]:::host
        EasingGen["Easing & Filter Generators"]:::host
        BuildSys["Make/CMake Build Pipeline"]:::host
    end

    %% Firmware Components
    subgraph "Firmware (Pico)" 
        direction TB
        CoreApp["Firmware Core (main.cpp)"]:::fw
        GeneratedAudio["Generated Audio Data"]:::fw
        Sequencer["Sequencer Module"]:::fw
        MIDIClock["MIDI/Clock In (PIO)"]:::fw
        EasingMod["Easing/Filter Module"]:::fw
        AudioMangle["Audio Mangling Subsystem"]:::fw
        LEDDrv["LED Driver (PIO)"]:::fw
    end

    %% Hardware
    subgraph "Hardware" 
        direction TB
        Pico["Raspberry Pi Pico"]:::hw
        WS2812["WS2812 LED Strip"]:::hw
        PWMOut["Audio PWM Out"]:::hw
        Controls["Knobs/Buttons"]:::hw
    end

    %% Build-Time Data Flow
    AudioFiles -->|"input"| Audio2H
    EasingGen -->|"generate data"| Audio2H
    Audio2H -->|"produces header"| GeneratedAudio
    CoreApp -->|"source"| BuildSys
    GeneratedAudio --> BuildSys
    BuildSys -->|"compiles firmware"| CoreApp

    %% Run-Time Data Flow
    CoreApp --> Sequencer
    Sequencer -->|"triggers"| AudioMangle
    Sequencer -->|"triggers"| LEDDrv
    Sequencer -->|"clock data"| MIDIClock
    EasingMod --> AudioMangle
    EasingMod --> LEDDrv
    GeneratedAudio --> AudioMangle
    AudioMangle -->|"PWM signal"| PWMOut
    LEDDrv -->|"PIO stream"| WS2812
    Controls --> Sequencer

    %% Hardware Integration
    AudioMangle --> Pico
    LEDDrv --> Pico
    MIDIClock --> Pico
    Sequencer --> Pico
    Controls --> Pico
    Pico --> WS2812
    Pico --> PWMOut

    %% Click Events
    click Audio2H "https://github.com/benediktschoeffmann/pikocore/blob/main/audio2h/main.go"
    click EasingGen "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/generate_easing.py"
    click EasingGen "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/biquad.py"
    click BuildSys "https://github.com/benediktschoeffmann/pikocore/tree/main/Makefile"
    click BuildSys "https://github.com/benediktschoeffmann/pikocore/blob/main/CMakeLists.txt"
    click BuildSys "https://github.com/benediktschoeffmann/pikocore/blob/main/pico_sdk_import.cmake"
    click BuildSys "https://github.com/benediktschoeffmann/pikocore/blob/main/target_compile_definitions.cmake"
    click CoreApp "https://github.com/benediktschoeffmann/pikocore/blob/main/main.cpp"
    click Sequencer "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/sequencer.h"
    click MIDIClock "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/onewiremidi.h"
    click MIDIClock "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/onewiremidi.pio"
    click LEDDrv "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/WS2812.cpp"
    click LEDDrv "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/WS2812.hpp"
    click LEDDrv "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/WS2812.pio"
    click LEDDrv "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/led.h"
    click LEDDrv "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/ledarray.h"
    click EasingMod "https://github.com/benediktschoeffmann/pikocore/tree/main/doth/easings"
    click AudioMangle "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/dither.h"
    click AudioMangle "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/trigger_out.h"
    click AudioMangle "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/runningavg.h"
    click AudioMangle "https://github.com/benediktschoeffmann/pikocore/blob/main/doth/delay.h"
    click CoreApp "https://github.com/benediktschoeffmann/pikocore/blob/main/main.cpp"
    click BuildSys "https://github.com/benediktschoeffmann/pikocore/blob/main/target_compile_definitions.cmake"

    %% Styles
    classDef host fill:#D0E6FF,stroke:#1C6EF2,color:#000
    classDef fw fill:#DFF2D8,stroke:#4CAF50,color:#000
    classDef hw fill:#F0F0F0,stroke:#888,color:#000
```
