bgrolleman
db4c76a110
Covers Python, Arduino CLI, AVR core, FastLED/OneButton libraries, make, and port detection — with platform-specific install paths and a make-free fallback for Windows. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
197 lines
7.1 KiB
Markdown
197 lines
7.1 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 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
|
|
```
|