# 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