# VSWR / NanoVNA Hardware Guide

Diese Anleitung beschreibt den VSWR-Hardwarepfad ueber `rms.vswr.native` (empfohlen) und `rms.vswr.nanovna` (legacy-kompatibel).

## Quick Start

```bash
grep -E '^(VSWR_CHECK_CMD|NANOVNA_COMMAND_TEMPLATE|VSWR_TIMEOUT_MS_PER_BAND|VSWR_METADATA_PATH|VSWR_REPORT_JSON_PATH|VSWR_OUTPUT_BASE_DIR|VSWR_IMAGES_BASE_URL)=' /etc/remotestation-arcg/remotestation-arcg.env
sudo systemctl restart remotestation-arcg
curl -sS -H "Authorization: Bearer <token>" -X POST http://127.0.0.1:8080/v1/swr/run-check
curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8080/v1/swr/report
```

## 1) Plugin-Rollen

- `rms.vswr.native`
  - Fuehrt Bandweise oder Batch-VSWR-Runs aus
  - Schreibt strukturierten Report (`swr-report.json`)
  - Nutzt Template mit Platzhaltern (`{band}`, `{startHz}`, `{endHz}`, `{bandDir}`)

- `rms.vswr.nanovna`
  - Einfacher Lauf ueber `VSWR_CHECK_CMD`
  - Liest Status primär aus `VSWR_METADATA_PATH`

## 2) Relevante ENV-Keys (native)

```env
NANOVNA_COMMAND_TEMPLATE=
VSWR_TIMEOUT_MS_PER_BAND=45000
VSWR_BANDS_JSON=

VSWR_REPORT_JSON_PATH=/opt/remotestation-arcg/shared/data/vswr/swr-report.json
VSWR_OUTPUT_BASE_DIR=/opt/remotestation-arcg/shared/data/vswr/output
VSWR_IMAGES_BASE_URL=
VSWR_NATIVE_TRACE_PATH=/opt/remotestation-arcg/shared/data/vswr/native-run.log

VSWR_METADATA_PATH=
VSWR_LEGACY_REPORT_JSON_PATH=
VSWR_OVERVIEW_HTML_PATH=
```

## 3) Bedienung

- Trigger: `POST /v1/swr/run-check`
- Report: `GET /v1/swr/report`

Serverseitige Safety:

- VSWR-Run wird blockiert, solange Station aktiv in Benutzung ist.
- Bei `txActive=true` sind Umschalt-/SWR-Aktionen gesperrt.

## 4) Einstellen und Kalibrieren

1. Sweep-Kommando ausserhalb der App einmal direkt testen.
2. Wenn pro Band separater Lauf genutzt wird: Platzhalter im Template korrekt setzen.
3. Bandgrenzen (`VSWR_BANDS_JSON`) gegen reale Messbereiche abgleichen.
4. Bild-/Reportpfade auf Schreibrechte pruefen.
5. Bei langen Messketten nur moderat `VSWR_TIMEOUT_MS_PER_BAND` erhoehen.

## 5) Fehlerbilder

- `VSWR_CHECK_CMD nicht gesetzt` (legacy plugin): Kommando fehlt.
- `VSWR check failed`: Sweep-Skript/Hardwarelauf fehlgeschlagen.
- `UNKNOWN` fuer Baender: Report/Images fehlen oder Legacy-Fallback nicht verfuegbar.
- Durchlauf dauert zu lange: Timeout/Bandanzahl/Skriptpfad analysieren.

## 6) Sicherheitsregeln

- VSWR nur im sicheren Betriebszustand laufen lassen (TX OFF, definierte RF-Route).
- Keine live-spezifischen sensiblen Hardwaredetails/Secrets im Repo ablegen.