Add getting started guide for Windows and macOS

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>

GETTING_STARTED.md

@@ -0,0 +1,213 @@
+# 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.

README.md

@@ -72,6 +72,8 @@ A 60-LED strip at full white = **3.6A** — far more than the Arduino's 5V pin c
 
 ## 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:
@@ -187,6 +189,7 @@ Amirine_Cosplay_Lights/
 │   └── 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