# timothyhay256/stochastic-volumetric-led-display architecture

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

- Interactive diagram: https://gitdiagram.com/timothyhay256/stochastic-volumetric-led-display
- Repository: https://github.com/timothyhay256/stochastic-volumetric-led-display

## Overview

##### Project Type and Purpose
- This is a hybrid full-stack / embedded system. On the host side you have a Rust-based CLI/library that scans, configures, animates and streams LED data. On the client side you have two targets:
- Microcontrollers (ESP32/ESP8266 via PlatformIO + FastLED) that actually drive the LED strips.
- A Unity (or Houdini) project that loads a 3D representation of your LEDs and applies volumetric effects.
- The overall goal is to scan a 3D arrangement of addressable RGB LEDs, generate a spatial mapping, then render and animate them either in software (Unity/Houdini) or push animations back to the hardware controllers.

##### File-Structure Analysis
Top-level:
- .github & CI pipelines – cross-platform Rust builds.
- docs/ – calibration, config, LEDs, Unity integration, usage guides.
- esp-code/ – many independent PlatformIO subprojects (esp_demo, read_vled_esp32, receive_esp32_udp, etc.). Each folder is a self-contained firmware target with its own src/, include/, test/, platformio.ini.
- src/ – the Rust workspace/library + binary:
– main.rs (CLI entrypoint)
– lib.rs & modules (driver_wizard, scan, read_vled, led_manager, utils, demo, speedtest, unity).
- svled.toml, Cargo.toml/Cargo.lock – Rust configuration
- rustfmt.toml – style guidelines

##### README Insights
- The CLI can scan LEDs over serial/UDP, build a volumetric model, save “animations” either to disk or flash them to ESP controllers.
- It supports multiple controllers in parallel for high-throughput LED driving (20k LEDs/sec across 40 controllers).
- The host-side output can be consumed by Unity or Houdini for 3D effects.

##### Main Components & Interactions
a. Host-side Rust Application
- driver_wizard & scan modules – handle device discovery, calibration, spatial mapping.
- read_vled & speedtest – I/O performance and diagnostics.
- led_manager – high-level API to generate and sequence animations.
- unity module – exports mapping/animation data in Unity-friendly format (JSON or binary).
- CLI (main.rs) – orchestrates user commands, reads svled.toml, invokes subcommands.
b. Configuration & Persistence
- svled.toml – global config (device IDs, scanning params).
- docs/config.md – describes all options.
- Animation files – saved to disk (per docs/saving_animations.md).
c. Microcontroller Firmware
- Multiple PlatformIO projects under esp-code/ – each implements a specific demo or I/O mode (serial, UDP, webserver).
- FastLED library – drives LED strips.
- Communication interface (serial or UDP) – receives animation frames/commands.
d. Unity Client
- unity-project/ – C# scripts read mapping + animation stream (via file or network).
- Renders 3D particles/meshes aligned to real LEDs.
e. CI/CD & Tooling
- .github/workflows – cross-compile Rust for Linux, macOS, Windows, Raspbian.
- rustfmt.toml – code style.

##### Architectural Patterns & Principles
- Modular CLI with subcommands (scan, demo, read_vled, speedtest, unity export).
- Plugin-like firmware targets for different ESP demos (each in its own folder).
- Clear separation of concerns: Device discovery → Mapping → Animation creation → Rendering/Flashing.
- Use of config files for reproducibility and repeatable builds (Cargo.toml, svled.toml, platformio.ini).

##### Essential Elements
– Callouts for key files: Cargo.toml, svled.toml, platformio.ini, docs/.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Host Application"
        CLI["Rust CLI\n(main.rs)"]:::host
        Lib["Rust Library\n(lib.rs)"]:::host
        DW["driver_wizard\n(src/driver_wizard.rs)"]:::host
        SC["scan\n(src/scan.rs)"]:::host
        RV["read_vled\n(src/read_vled.rs)"]:::host
        SP["speedtest\n(src/speedtest.rs)"]:::host
        LM["led_manager\n(src/led_manager.rs)"]:::host
        UEX["unity exporter\n(src/unity.rs)"]:::host
        UT["utils\n(src/utils.rs)"]:::host
    end

    subgraph "Configuration & Storage"
        CFG["svled.toml"]:::config
        CARGO["Cargo.toml/Cargo.lock"]:::config
        RFM["rustfmt.toml"]:::config
        DOCC["docs/"]:::config
        CI[".github/workflows\n.rpi-xcompile Dockerfile"]:::config
    end

    subgraph "Microcontroller Fleet"
        ESP1["esp_demo"]:::embedded
        ESP2["esp_main"]:::embedded
        ESP3["read_vled_esp32"]:::embedded
        ESP4["receive_esp32_udp"]:::embedded
        ESP5["receive_esp8266_udp_neopixel"]:::embedded
        ESP6["receive_esp_serial"]:::embedded
        ESP7["receive_esp_serial_parallel"]:::embedded
        ESP8["receive_esp_serial_parallel_async"]:::embedded
        ESP9["Tests"]:::embedded
        LED["LED Strips"]:::embedded
    end

    UnityApp["Unity 3D Visualization\n(unity-project/)"]:::unity

    CFG -->|reads config| CLI
    CARGO -->|builds| CLI
    RFM -->|formats| CLI
    DOCC -->|docs for| CLI
    CI -->|build pipelines| CLI

    CLI -->|invokes| DW
    CLI -->|invokes| SC
    CLI -->|invokes| RV
    CLI -->|invokes| SP
    CLI -->|invokes| LM
    CLI -->|export| UEX

    DW --> SC
    SC -->|produces mapping| UEX

    CLI -->|UDP/Serial| ESP1
    CLI -->|UDP/Serial| ESP2
    CLI -->|UDP/Serial| ESP3
    CLI -->|UDP/Serial| ESP4
    CLI -->|UDP/Serial| ESP5
    CLI -->|UDP/Serial| ESP6
    CLI -->|UDP/Serial| ESP7
    CLI -->|UDP/Serial| ESP8
    CLI -->|UDP/Serial| ESP9

    ESP1 --> LED
    ESP2 --> LED
    ESP3 --> LED
    ESP4 --> LED
    ESP5 --> LED
    ESP6 --> LED
    ESP7 --> LED
    ESP8 --> LED
    ESP9 --> LED

    CLI -->|export JSON mapping| UnityApp

    classDef host fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef embedded fill:#90EE90,stroke:#333,stroke-width:1px
    classDef unity fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px

    click CLI "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/main.rs"
    click Lib "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/lib.rs"
    click DW "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/driver_wizard.rs"
    click SC "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/scan.rs"
    click RV "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/read_vled.rs"
    click SP "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/speedtest.rs"
    click LM "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/led_manager.rs"
    click UEX "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/unity.rs"
    click UT "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/src/utils.rs"
    click CFG "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/svled.toml"
    click CARGO "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/Cargo.toml"
    click RFM "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/rustfmt.toml"
    click DOCC "https://github.com/timothyhay256/stochastic-volumetric-led-display/blob/main/docs/config.md"
    click CI "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/.github/workflows/"
    click ESP1 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/esp_demo/"
    click ESP2 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/esp_main/"
    click ESP3 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/read_vled_esp32/"
    click ESP4 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/receive_esp32_udp/"
    click ESP5 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/receive_esp8266_udp_neopixel/"
    click ESP6 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/receive_esp_serial/"
    click ESP7 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/receive_esp_serial_parallel/"
    click ESP8 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/receive_esp_serial_parallel_async/"
    click ESP9 "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/esp-code/Tests/"
    click UnityApp "https://github.com/timothyhay256/stochastic-volumetric-led-display/tree/main/unity-project/"
```
