bgrolleman
11eb2584ef
Arduino Uno + WS2812B LED strip controller with a text-based lightshow system. Shows are defined as .txt files (hex color + fade duration per step), converted to PROGMEM headers by convert_all.py, and navigated at runtime via a debounced button (tap/double-tap/hold). BSD 2-Clause license. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
# Amirine Cosplay Lights
|
|
|
|
Arduino-powered LED strip controller for cosplay costumes.
|
|
Write simple `.txt` files to define light shows — fades, instant switches, pulses — then upload them to the Arduino. A single button lets you cycle through all loaded shows.
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause
|
|
|
|
---
|
|
|
|
## What you need
|
|
|
|
| Item | Notes |
|
|
|------|-------|
|
|
| Arduino Uno or Nano | Any clone works |
|
|
| WS2812B LED strip | NeoPixel-compatible |
|
|
| 5V power supply | See power warning below |
|
|
| Micro USB cable | For uploading code |
|
|
| Momentary push button | Any normally-open tactile button |
|
|
| 470Ω resistor | On the LED data line — protects the first LED |
|
|
| 1000µF capacitor | Across LED power lines — prevents voltage spikes |
|
|
|
|
---
|
|
|
|
## Wiring
|
|
|
|
### LED strip
|
|
|
|
```
|
|
Arduino WS2812B strip
|
|
─────── ─────────────
|
|
GND ──────────────────── GND
|
|
D6 ──── [470Ω] ──────── DIN (data in)
|
|
```
|
|
|
|
Power the strip separately — see the power warning below.
|
|
|
|
### Button
|
|
|
|
```
|
|
Arduino Button
|
|
─────── ──────
|
|
D2 ──────────────────── leg 1
|
|
GND ──────────────────── leg 2
|
|
```
|
|
|
|
Uses the internal pull-up resistor. No external resistor needed. Pin 2 can be changed in `config.h`.
|
|
|
|
### Button behaviour
|
|
|
|
| Press | Action |
|
|
|-------|--------|
|
|
| 1 tap | Next show |
|
|
| 2 taps | Previous show |
|
|
| Hold (~0.8s) | Reset to show 0 (slow blue pulse) |
|
|
|
|
### Power warning — read this
|
|
|
|
At full brightness, each WS2812B LED draws up to 60mA.
|
|
A 60-LED strip at full white = **3.6A** — far more than the Arduino's 5V pin can supply.
|
|
|
|
**Power the strip directly from a 5V supply** (phone charger, power bank, or battery pack):
|
|
- Connect the supply's **5V** and **GND** to the strip's **VCC** and **GND**.
|
|
- Also connect the supply's **GND** to the Arduino's **GND** (shared ground).
|
|
- Do **not** connect the supply's 5V to the Arduino's 5V pin.
|
|
- Place a **1000µF capacitor** between VCC and GND near the strip connector.
|
|
|
|
`MAX_BRIGHTNESS` in `config.h` is set to 150 (out of 255) to limit current draw. Lower it further for battery builds.
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
### 1. Install the FastLED library
|
|
|
|
Arduino IDE: **Sketch → Include Library → Manage Libraries** → search `FastLED` → Install.
|
|
|
|
### 2. Configure your hardware
|
|
|
|
Edit `arduino/cosplay_lights/config.h`:
|
|
- `LED_DATA_PIN` — pin connected to the strip's DIN (default: 6)
|
|
- `BUTTON_PIN` — pin the button is wired to (default: 2)
|
|
- `NUM_LEDS` — total LED count on your strip (default: 60)
|
|
- `MAX_BRIGHTNESS` — global brightness cap (default: 150)
|
|
|
|
### 3. Write or edit show files
|
|
|
|
Show files live in `converter/shows/`. Four are included:
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `blue_pulse.txt` | Slow blue breathing — always show 0 (home/reset) |
|
|
| `example_fade.txt` | Slow color cycle |
|
|
| `example_party.txt` | Fast rainbow flashes |
|
|
| `example_pulse.txt` | Red heartbeat |
|
|
|
|
**Show file format:**
|
|
|
|
```
|
|
// Lines starting with // are comments.
|
|
|
|
#FF0000, 0 // snap to red instantly (0ms = no fade)
|
|
#00FF00, 3000 // 3-second fade to green
|
|
#0000FF, 0 // snap to blue
|
|
```
|
|
|
|
Each line: a hex color and how long (in ms) to fade from the previous color.
|
|
|
|
**Tip — holding a color:** add a second step with the same color, duration = hold time:
|
|
```
|
|
#FF0000, 0 // snap to red
|
|
#FF0000, 2000 // hold red for 2 seconds
|
|
#0000FF, 1500 // fade to blue
|
|
```
|
|
|
|
### 4. Build and upload
|
|
|
|
```bash
|
|
make upload
|
|
```
|
|
|
|
This converts all `.txt` shows, compiles the sketch, and uploads it. The show starts immediately and loops forever. Use the button to switch shows.
|
|
|
|
If you have multiple USB devices and the wrong port is detected:
|
|
```bash
|
|
make port # see what's connected
|
|
make upload PORT=/dev/ttyUSB1 # target a specific port
|
|
```
|
|
|
|
---
|
|
|
|
## Adding your own shows
|
|
|
|
1. Create a `.txt` file in `converter/shows/` using the format above.
|
|
2. Run `make upload` — your new show is automatically included.
|
|
|
|
The order in which shows appear when cycling through with the button is: `blue_pulse` first, then all others sorted alphabetically by filename.
|
|
|
|
---
|
|
|
|
## File overview
|
|
|
|
```
|
|
Amirine_Cosplay_Lights/
|
|
├── arduino/cosplay_lights/
|
|
│ ├── cosplay_lights.ino — main sketch (upload this)
|
|
│ ├── config.h — hardware settings
|
|
│ ├── button.h / .cpp — button debounce and event detection
|
|
│ ├── led_controller.h / .cpp — LED abstraction layer
|
|
│ ├── lightshow_format.h — Step and ShowDef structs
|
|
│ ├── shows.h — master show index (regenerated by make shows)
|
|
│ └── show_*.h — individual show data (regenerated by make shows)
|
|
├── converter/
|
|
│ ├── convert_all.py — converts all shows and regenerates shows.h
|
|
│ ├── convert.py — converts a single show file (for testing)
|
|
│ └── shows/ — .txt show files (edit these)
|
|
├── Makefile — build, upload, and show conversion targets
|
|
├── README.md — this file
|
|
├── DETAILS.md — architecture and modification guide
|
|
├── PLAN.md — original project brief
|
|
└── LICENSE — BSD 2-Clause
|
|
```
|