add verbose flag and dev-instructions

2026-07-05 10:34:49 +02:00
parent 9ccd84e6df
commit 81f9bb8870
2 changed files with 138 additions and 2 deletions
--- a/dev-instructions.md
+++ b/dev-instructions.md
@@ -0,0 +1,120 @@
+# 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.