From 81f9bb8870465df46d902e932ad5d7e570849ff0 Mon Sep 17 00:00:00 2001
From: Alex <alex@tesserakt.pro>
Date: Sun, 5 Jul 2026 10:34:49 +0200
Subject: [PATCH] add verbose flag and dev-instructions

---
 dev-instructions.md    | 120 +++++++++++++++++++++++++++++++++++++++++
 scripts/capture_csv.py |  20 ++++++-
 2 files changed, 138 insertions(+), 2 deletions(-)
 create mode 100644 dev-instructions.md

diff --git a/dev-instructions.md b/dev-instructions.md
new file mode 100644
index 0000000..1c3cebe
--- /dev/null
+++ 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.
diff --git a/scripts/capture_csv.py b/scripts/capture_csv.py
index 93d7cfe..7fce842 100755
--- a/scripts/capture_csv.py
+++ b/scripts/capture_csv.py
@@ -78,6 +78,12 @@ def main() -> int:
         default=True,
         help="Send 'log on' to the dryer after connect (default: on)",
     )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Echo captured CSV rows to stdout; other serial lines to stderr",
+    )
     args = parser.parse_args()
 
     port = args.port
@@ -125,22 +131,32 @@ def main() -> int:
 
             line = raw.decode("utf-8", errors="replace").strip()
             if not line.startswith("csv_hdr,") and not line.startswith("csv,"):
+                if args.verbose and line:
+                    print(line, file=sys.stderr)
                 continue
 
             if line.startswith("csv_hdr,"):
                 device_header = line[len("csv_hdr,") :]
-                fh.write("wall_time," + device_header + "\n")
+                row = "wall_time," + device_header
+                fh.write(row + "\n")
                 header_written = True
                 fh.flush()
+                if args.verbose:
+                    print(row)
                 continue
 
             if not header_written:
                 fh.write(FALLBACK_HEADER + "\n")
                 header_written = True
+                if args.verbose:
+                    print(FALLBACK_HEADER)
 
             wall_time = datetime.now(timezone.utc).isoformat(timespec="seconds")
-            fh.write(wall_time + "," + line[len("csv,") :] + "\n")
+            row = wall_time + "," + line[len("csv,") :]
+            fh.write(row + "\n")
             fh.flush()
+            if args.verbose:
+                print(row)
 
 
 if __name__ == "__main__":