Amirine_Cosplay_Lights/GETTING_STARTED.md

Getting Started

Step-by-step setup guide for Windows and macOS.

SPDX-License-Identifier: BSD-2-Clause

---

What you're installing

Tool	Why
Python 3	Converts your .txt show files into Arduino code
Arduino CLI	Compiles and uploads the sketch to the Arduino
FastLED library	LED strip control (installed via Arduino CLI)
OneButton library	Button gesture detection (installed via Arduino CLI)

On Windows you'll also install make so the one-liner make upload command works.
On macOS make is already available once you install the developer tools.

---

Windows

1. Install Python

1. Go to https://www.python.org/downloads/ and download the latest Python 3 installer.
2. Run the installer.
   Important: on the first screen, tick "Add python.exe to PATH" before clicking Install Now.
3. Open Command Prompt (search "cmd") and verify:

   python --version
   

   You should see something like Python 3.12.3.

2. Install Arduino CLI

Open Command Prompt and run:

winget install ArduinoSA.ArduinoCLI

Close and reopen Command Prompt, then verify:

arduino-cli version

If winget is not available, download the Windows .zip from
https://arduino.github.io/arduino-cli/latest/installation/
extract it, and add the folder to your PATH.

3. Install the AVR board package

arduino-cli core update-index
arduino-cli core install arduino:avr

This downloads everything needed to compile for Arduino Uno/Nano. It may take a minute.

4. Install the required libraries

arduino-cli lib install "FastLED"
arduino-cli lib install "OneButton"

5. Install make

The make upload command requires make. Install it with:

winget install GnuWin32.Make

After installation, add C:\Program Files (x86)\GnuWin32\bin to your PATH:

1. Search for "Edit the system environment variables".
2. Click Environment Variables.
3. Under User variables, select Path and click Edit.
4. Click New and paste C:\Program Files (x86)\GnuWin32\bin.
5. Click OK on all dialogs.

Close and reopen your terminal, then verify:

make --version

Alternative — skip make entirely:
If you'd rather not install make, you can run the three steps manually in Command Prompt from the project folder:

python converter\convert_all.py
arduino-cli compile --fqbn arduino:avr:uno --build-path build arduino/cosplay_lights
arduino-cli upload --fqbn arduino:avr:uno --port COM3 --input-dir build arduino/cosplay_lights

Replace COM3 with your actual port (see step 6 below).

6. Find your Arduino port (Windows)

Plug in the Arduino via USB, then run:

arduino-cli board list

Look for a line showing arduino:avr:uno — the port will be something like COM3 or COM4.

7. Upload

From the project folder:

make upload

Or with a specific port:

make upload PORT=COM3

---

macOS

1. Install developer tools

Open Terminal (Spotlight → "Terminal") and run:

xcode-select --install

Click Install in the dialog that appears. This gives you git, make, and other command-line tools. Skip this step if you already have them.

2. Install Python

macOS ships with an older Python, so install a current version.

Option A — using Homebrew (recommended):

If you don't have Homebrew, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install Python:

brew install python

Option B — installer:
Download from https://www.python.org/downloads/ and run the .pkg.

Verify:

python3 --version

3. Install Arduino CLI

Option A — Homebrew:

brew install arduino-cli

Option B — installer script:

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

Then move the binary somewhere on your PATH, e.g. sudo mv bin/arduino-cli /usr/local/bin/.

Verify:

arduino-cli version

4. Install the AVR board package

arduino-cli core update-index
arduino-cli core install arduino:avr

5. Install the required libraries

arduino-cli lib install "FastLED"
arduino-cli lib install "OneButton"

6. Find your Arduino port (macOS)

Plug in the Arduino via USB, then run:

arduino-cli board list

The port will look like /dev/cu.usbmodem14101 or /dev/cu.usbserial-*.

7. Upload

From the project folder:

make upload

Or with a specific port:

make upload PORT=/dev/cu.usbserial-14101

---

You're set up

Once the upload finishes, the lights start immediately. Use the button to cycle through shows.
See README.md for how to write your own show files and configure the hardware.