# 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 wire colors
───────                 ──────────────────────────
5V  ──────────────────── red   (VCC)
GND ──────────────────── white (GND)
D5  ──── [470Ω] ──────── green (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 |
| 3 taps | Lights off (any tap or hold resumes) |
| Hold (~0.8s) | Reset to show 0 (blue breath) |

### 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

> **New to this?** See [GETTING_STARTED.md](GETTING_STARTED.md) for step-by-step instructions on installing Python, Arduino CLI, and all dependencies on Windows or macOS.

### 1. Install required libraries

Arduino IDE: **Sketch → Include Library → Manage Libraries**, then install both:

- **FastLED** — LED strip control and color math
- **OneButton** — button debounce and gesture detection

### 2. Configure your hardware

Edit `arduino/cosplay_lights/config.h`:
- `LED_DATA_PIN` — pin connected to the strip's DIN (default: 5)
- `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/`. These are included:

| File | Description | Mode |
|------|-------------|------|
| `blue_breath.txt` | Slow blue breathing — always show 0 (home/reset) | loop |
| `001_heartbeat.txt` | 3 heartbeats in bright red, then auto-advances to breathing | single |
| `002_breath_red.txt` | Breathing between dark maroon and bright red, 5s cycle | loop |
| `003_solid_red.txt` | Constant deep red | loop |
| `example_fade.txt` | Slow color cycle | loop |
| `example_party.txt` | Fast rainbow flashes | loop |
| `example_pulse.txt` | Red heartbeat | loop |

**Show modes:**

- `loop` — repeats indefinitely until the button is pressed
- `single` — plays once, then automatically advances to the next show

Set the mode with a comment anywhere in the `.txt` file:
```
// mode: single
```
If no mode line is present, the show loops.

**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_breath` first (always show 0), then all others sorted alphabetically by filename. Prefix filenames with numbers (`001_`, `002_`, …) to control order.

---

## File overview

---

## Resources

- [Wokwi](https://wokwi.com/projects/new/arduino-uno) — browser-based Arduino + LED strip emulator, useful for testing shows without hardware
- [tweaking4all — LED strip effects](https://www.tweaking4all.nl/hardware/arduino/adruino-led-strip-effecten/) — reference for animation patterns (sparkle, rainbow, etc.)
- [FastLED color fills reference](https://fastled.io/docs/da/de3/group___color_fills.html)
- [Adafruit LED animation guide](https://learn.adafruit.com/circuitpython-led-animations/basic-animations)
- [htmlcolorcodes.com](https://htmlcolorcodes.com/) — hex color picker for choosing show colors

---

## File overview

```
Amirine_Cosplay_Lights/
├── arduino/cosplay_lights/
│   ├── cosplay_lights.ino      — main sketch (upload this)
│   ├── config.h                — hardware settings
│   ├── 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
├── GETTING_STARTED.md          — first-time setup for Windows and macOS
├── DETAILS.md                  — architecture and modification guide
├── PLAN.md                     — original project brief
└── LICENSE                     — BSD 2-Clause
```