From db4c76a1101a7124fb209beac59c6b517362b18a Mon Sep 17 00:00:00 2001 From: Bas Grolleman Date: Sun, 24 May 2026 19:38:39 +0200 Subject: [PATCH] Add getting started guide for Windows and macOS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- GETTING_STARTED.md | 213 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 + 2 files changed, 216 insertions(+) create mode 100644 GETTING_STARTED.md diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md new file mode 100644 index 0000000..a740084 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 80920ab..3de0ca6 100644 --- a/README.md +++ b/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