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

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_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 — browser-based Arduino + LED strip emulator, useful for testing shows without hardware
• tweaking4all — LED strip effects — reference for animation patterns (sparkle, rainbow, etc.)
• FastLED color fills reference
• Adafruit LED animation guide
• 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