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](README.md) for how to write your own show files and configure the hardware.