# raphaelmeyer/pico-synth architecture

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

- Interactive diagram: https://gitdiagram.com/raphaelmeyer/pico-synth
- Repository: https://github.com/raphaelmeyer/pico-synth

## Overview

##### Main System Type and Purpose
- This is an embedded-firmware project for Raspberry Pi Pico, implementing a polyphonic audio synthesizer (“pico-synth”) plus a USB MIDI/display adapter (“midi-adapter”), with host-side simulation and test harnesses.

##### Main Components
A. Hardware
- Raspberry Pi Pico boards (two flavors: synth and midi-adapter)
- Audio codec (ADAU3678 via I2S)
- (ST7735R via SPI)
- Input controls (buttons, rotary encoder via GPIO)
- USB (MIDI adapter)

B. Firmware Targets
1. pico-synth
– Synth engine (oscillators, ADSR envelope, wave generation)
– Control logic (parameter management, event dispatch)
– Device drivers (I2S, GPIO, random)
– UI for built-in display
2. midi-adapter
– USB/MIDI interface (TinyUSB)
– SPI master to synth board
– Display driver (ST7735) and UI

C. Shared Libraries (Layered, reused by both firmware and host)
– synth core (oscillator, envelope, tick-counter)
– control module (midi_control, focus management)
– messaging (sender/receiver types)
– UI abstractions (wave form selection, range input)
– Types/definitions

D. Host Side
1. Simulation UI (uisim)
– LVGL-based driver stub (x11.cc) to render UI on desktop
– Reuses shared UI and synth code
2. Snapshot tests & Specs
– GoogleTest-style tests under source/host/specs and source/host/snapshots
– Automated golden-file comparisons for synth behavior
3. Build & Task orchestration
– CMake + Go-Task (Taskfile.yml)

##### Relationships & Data Flows
- Firmware builds include shared libraries + device drivers → two binaries (pico-synth.uf2, midi-adapter.uf2)
- pico-synth firmware reads control events (GPIO/SPI) → control module → synth engine → I2S → audio codec
- midi-adapter firmware acts as USB-MIDI ↔ SPI gateway, updates UI on ST7735
- Host simulation links shared UI + synth components → renders on X11 for local testing
- Snapshot tests invoke synth engine directly, compare output dumps

##### Architectural Patterns & Design Principles
- Layered architecture / clean separation:
1. Hardware Abstraction Layer (device drivers in source/pico/device and shared/message)
2. Domain layer (synth core, control logic)
3. Presentation layer (UI abstractions, LVGL simulation)
- Reuse of shared code to avoid duplication across host and embedded targets
- Test-driven approach via snapshot tests and mock drivers

##### Technologies & Frameworks
- CMake (multi-target build, pico-SDK integration)
- Go-Task for higher-level build orchestration
- clang + arm-none-eabi toolchain
- TinyUSB (USB/MIDI)
- ADAU3678 I2S audio, ST7735 SPI display
- LVGL for host UI simulation
- GoogleTest (specs)

##### Essential Elements
- Protocol/interface labels (SPI, I2S, USB-MIDI, GPIO)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Layer
    subgraph "Host Layer"
        direction TB
        HostUISim["Host Simulation UI\n(LVGL stub, X11)"]:::host
        HostSpecs["GoogleTest-Style Specs"]:::host
        HostSnapshots["Snapshot Tests & Harness"]:::host
        Build["Build & Task Orchestration\n(CMake, Taskfile)"]:::host
    end

    %% Shared Core Layer
    subgraph "Shared Core"
        direction TB
        SharedSynth["Synth Core\n(oscillators, envelopes,\nwave gen, tick counter)"]:::shared
        SharedControl["Control Module\n(midi_control, focus,\nevent dispatch)"]:::shared
        SharedMsg["Messaging\n(sender/receiver types)"]:::shared
        SharedUI["UI Abstractions\n(waveform selection,\nrange input)"]:::shared
        SharedTypes["Types & Definitions"]:::shared
    end

    %% Embedded Layer
    subgraph "Embedded Layer"
        direction TB
        subgraph "Firmware Targets"
            direction TB
            PSynth["pico-synth Firmware"]:::firmware
            MAdapter["midi-adapter Firmware"]:::firmware
        end
        subgraph "Hardware Abstraction Layer"
            direction TB
            HAL_Display["Display Driver\n(ST7735)"]:::hardware
            HAL_I2S["I2S Audio Codec Driver\n(ADAU3678)"]:::hardware
            HAL_GPIO["GPIO Driver\n(Buttons, Encoder)"]:::hardware
            HAL_Random["Random Source Driver"]:::hardware
        end
        subgraph "Physical Hardware"
            direction TB
            PicoSynthBoard["Raspberry Pi Pico\n(synth)"]:::hardware
            PicoMidiBoard["Raspberry Pi Pico\n(midi-adapter)"]:::hardware
            AudioCodec["Audio Codec\n(ADAU3678)"]:::hardware
            DisplayHW["Display\n(ST7735R)"]:::hardware
            Controls["Buttons & Encoder"]:::hardware
            USBPort["USB MIDI Port"]:::hardware
        end
    end

    %% Dependencies: Shared to Host
    SharedSynth -->|reused by| HostUISim
    SharedUI -->|reused by| HostUISim
    SharedSynth -->|tested by| HostSnapshots
    SharedSynth -->|tested by| HostSpecs

    %% Dependencies: Shared to Embedded
    SharedSynth -->|build dep| PSynth
    SharedControl -->|build dep| PSynth
    SharedMsg -->|build dep| PSynth
    SharedUI -->|build dep| PSynth
    SharedTypes -->|build dep| PSynth

    SharedSynth -->|build dep| MAdapter
    SharedControl -->|build dep| MAdapter
    SharedMsg -->|build dep| MAdapter
    SharedUI -->|build dep| MAdapter
    SharedTypes -->|build dep| MAdapter

    %% Firmware to HAL
    PSynth -->|uses SPI| HAL_Display
    PSynth -->|uses I2S| HAL_I2S
    PSynth -->|uses GPIO| HAL_GPIO
    PSynth -->|uses Random| HAL_Random

    MAdapter -->|uses SPI| HAL_Display
    MAdapter -->|uses SPI| HAL_I2S

    %% HAL to Physical
    HAL_Display -->|SPI| DisplayHW
    HAL_I2S -->|I2S| AudioCodec
    HAL_GPIO -->|GPIO| Controls
    HAL_Random -->|RNG| PicoSynthBoard

    %% Pico Boards connectivity
    PSynth -->|runs on| PicoSynthBoard
    MAdapter -->|runs on| PicoMidiBoard
    MAdapter -->|USB-MIDI| USBPort
    MAdapter -->|SPI| PicoSynthBoard

    %% Build orchestration
    Build -->|orchestrates| PSynth
    Build -->|orchestrates| MAdapter
    Build -->|configures| HostUISim
    Build -->|configures| HostSpecs
    Build -->|configures| HostSnapshots

    %% Click Events
    click PSynth "https://github.com/raphaelmeyer/pico-synth/tree/main/source/pico/pico-synth/"
    click MAdapter "https://github.com/raphaelmeyer/pico-synth/tree/main/source/pico/midi-adapter/"
    click HAL_Display "https://github.com/raphaelmeyer/pico-synth/tree/main/source/pico/device/display/"
    click HAL_I2S "https://github.com/raphaelmeyer/pico-synth/tree/main/source/pico/device/i2s/"
    click HAL_GPIO "https://github.com/raphaelmeyer/pico-synth/tree/main/source/pico/device/io/"
    click HAL_Random "https://github.com/raphaelmeyer/pico-synth/tree/main/source/pico/device/random/"
    click SharedSynth "https://github.com/raphaelmeyer/pico-synth/tree/main/source/shared/synth/"
    click SharedControl "https://github.com/raphaelmeyer/pico-synth/tree/main/source/shared/control/"
    click SharedMsg "https://github.com/raphaelmeyer/pico-synth/tree/main/source/shared/message/"
    click SharedUI "https://github.com/raphaelmeyer/pico-synth/tree/main/source/shared/ui/"
    click SharedTypes "https://github.com/raphaelmeyer/pico-synth/tree/main/source/shared/types/"
    click HostUISim "https://github.com/raphaelmeyer/pico-synth/tree/main/source/host/simulation/uisim/"
    click HostSnapshots "https://github.com/raphaelmeyer/pico-synth/tree/main/source/host/snapshots/"
    click HostSpecs "https://github.com/raphaelmeyer/pico-synth/tree/main/source/host/specs/"
    click Build "https://github.com/raphaelmeyer/pico-synth/blob/main/source/CMakeLists.txt"

    %% Styles
    classDef firmware fill:#ADD8E6,stroke:#000
    classDef shared fill:#90EE90,stroke:#000
    classDef host fill:#FFFF99,stroke:#000
    classDef hardware fill:#D3D3D3,stroke:#000
```
