66 lines
2.7 KiB
Markdown
66 lines
2.7 KiB
Markdown
# 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
|