Amirine_Cosplay_Lights/README.md

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

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:

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