How timothyhay256/stochastic-volumetric-led-display works
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/.