Amirine_Cosplay_Lights/PLAN.md

Project Plan — Amirine Cosplay Lights

This file records the original design brief and decisions so future contributors can understand why things are built the way they are.

---

Goals

1. Light show player — load .txt files that define a sequence of colors with transition durations. Steps fade from the previous color to the next over the specified time. Setting duration to 0ms gives an instant switch; high values (e.g. 5000ms) give a slow fade.

2. Multi-show navigation — all shows are compiled into the firmware. A single button lets you cycle through them:

   • 1 tap — next show
   • 2 taps — previous show
   • Hold — reset to show 0 (blue breath)

3. Arduino + WS2812B — runs on an Arduino Uno with a WS2812B (NeoPixel) LED strip.

4. Open source — BSD 2-Clause license. Free for any use, personal or commercial.

5. Designed for expansion — the LED controller layer (led_controller.h/.cpp) is structured so that new patterns (chase, sparkle, gradient) can be added later without touching show playback logic.

---

Hardware confirmed

• Board: Arduino Uno
• LED strip: WS2812B (NeoPixel), data pin 6, ~60 LEDs, GRB color order
• Button: momentary push button on pin 2, wired to GND (INPUT_PULLUP)
• Color format: hex codes (#RRGGBB)
• Show loading: compiled into firmware via Arduino IDE / arduino-cli

---

Workflow

Write/edit .txt files in converter/shows/
            ↓
        make upload
  (runs make shows → make build → arduino-cli upload)
            ↓
   Show starts immediately, button navigates

---

Design principles

• Small, clearly named functions — each function does one thing.
• Comments explain the why — not the what.
• PROGMEM for all show data — Arduino Uno has only 2KB RAM; all Step arrays and the SHOWS[] index live in flash.
• Single config file — all hardware values are in config.h; porting to a different board or strip type requires edits in one place.
• generate-don't-maintain — shows.h and show_*.h are generated files; the source of truth is the .txt files in converter/shows/.

---

Future ideas (not yet implemented)

• Per-LED patterns — chase, sparkle (random white flashes over a base color), gradient segments. The led_controller.cpp pattern system already has the hook: add a #define PATTERN_SPARKLE in config.h and implement the branch in leds_apply_color()
• Multiple strip support
• Battery power optimization (auto-dim, sleep)
• SD card loading (no recompile needed for new shows)
• WiFi loading via ESP32 (browser-based show upload)
• Multiple buttons for direct show selection
• Show name displayed on a small OLED