# Development environment setup

Instructions for setting up firmware development on a new machine (laptop/desktop). For Raspberry Pi CSV logging, see [pi-instructions.md](pi-instructions.md).

## 1. Get the repo

```bash
git clone <repo-url> voron-filament-dryer
cd voron-filament-dryer
```

`.pio/`, `logs/`, and `compile_commands.json` are gitignored — they are created locally on each machine.

## 2. Install PlatformIO Core (CLI only)

This project uses **PlatformIO from the command line**, not the IDE extension (the extension is explicitly discouraged in `.vscode/extensions.json` because it hangs in Cursor).

**Option A — pip/pipx (simplest on Linux):**

```bash
pip install --user platformio
# or: pipx install platformio
```

**Option B — official installer:**

```bash
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/get-platformio.py -o get-platformio.py
python3 get-platformio.py
```

After install, `pio` should be on your PATH, or at `~/.platformio/penv/bin/pio` (what `.vscode/tasks.json` uses).

**First build** downloads the AVR toolchain, Arduino framework, and Adafruit libs:

```bash
pio run
```

Target: **Arduino Nano (ATmega328P)** — see `platformio.ini`.

## 3. Editor (Cursor / VS Code)

What is already in the repo:

| Piece | Purpose |
|--------|---------|
| `.vscode/tasks.json` | Build, Upload, Monitor, Clean, Upload+Monitor |
| `.vscode/settings.json` | clangd + `compile_commands.json` |
| `.vscode/extensions.json` | **Install clangd**; **do not** install PlatformIO IDE |

**One-time after clone** — regenerate IntelliSense DB (paths are machine-specific):

- Run task: **PlatformIO: Update IntelliSense DB**
- Or: `pio run -t compiledb`

**Daily workflow:**

- **Ctrl+Shift+B** → Build
- **Tasks: Run Task** → Upload / Monitor / Upload and Monitor

## 4. USB serial (upload + monitor)

Connect the Nano over USB, then:

```bash
pio device list          # find port, e.g. /dev/ttyUSB0 or /dev/ttyACM0
pio run -t upload        # auto-detects port if only one device
pio device monitor       # 115200 baud (set in platformio.ini)
```

**Linux permissions** — add your user to the serial group, then log out/in:

| Distro | Group |
|--------|--------|
| Arch / CachyOS | `uucp` |
| Debian / Ubuntu / Raspberry Pi OS | `dialout` |

```bash
# Arch example
sudo usermod -aG uucp $USER
```

If upload fails with "permission denied", that is usually the missing step.

**Optional** — fixed port in `platformio.ini`:

```ini
upload_port = /dev/ttyUSB0
monitor_port = /dev/ttyUSB0
```

## 5. Optional: CSV capture on the dev machine

Only if you want logging from the laptop instead of the Pi:

```bash
pip install -r scripts/requirements.txt
python3 scripts/capture_csv.py -p /dev/ttyUSB0
```

Only one process can hold the serial port (Pi logger **or** dev monitor, not both).

## 6. What you do not need

- Arduino IDE
- PlatformIO VS Code / Cursor extension
- Committing `.pio/` or `compile_commands.json`
- Anything on the Pi for **building** firmware (Pi is only for `capture_csv.py` if you use it there)

## Quick sanity checklist

```bash
pio --version
pio run
pio run -t compiledb    # for clangd
pio run -t upload       # Nano plugged in
```

If `tasks.json` cannot find `pio`, either add `~/.platformio/penv/bin` to PATH or change the task `command` to wherever `which pio` points on that machine.