add per-hardware plugin operation guides in docs

README.md

@@ -51,6 +51,7 @@ Google example (plugin settings):
 Station & Access
 - `rms.station.shell`: station activation/deactivation command execution
 - `rms.station.access.policy`: export effective access list for OpenWebRX policies
+- Hardware guide: `docs/hardware-station-shell-guide.md`
 
 OpenWebRX+
 - `rms.openwebrx.bandmap`: managed band/profile integration
@@ -61,16 +62,18 @@ TX/PTT/Audio
 - `rms.tx.state.file`: file-based TX state provider
 - `rms.tx.audio.core`: core TX audio session management
 - `rms.microham`: microHAM provider for PTT/audio related capabilities
+- Hardware guides: `docs/hardware-tx-control-guide.md`, `docs/hardware-microham-guide.md`
 
 RF/Hardware
 - `rms.rfroute.shell`: RF route switching via shell commands
 - `rms.rotor.hamlib`: rotor control via hamlib/rotctl
-- Rotor operational guide (ROT1Prog): `docs/rotor-rot1prog-guide.md`
+- Hardware guides: `docs/hardware-rfroute-guide.md`, `docs/rotor-rot1prog-guide.md`
 
 VSWR
 - `rms.vswr.native`: native VSWR command provider
 - `rms.vswr.nanovna`: NanoVNA-based VSWR provider
 - `rms.vswr.report_reader`: reads and serves VSWR report artifacts
+- Hardware guide: `docs/hardware-vswr-nanovna-guide.md`
 
 Ops/Help
 - `rms.debug.remote`: remote debug snapshot/log provider

docs/hardware-microham-guide.md

@@ -0,0 +1,84 @@
+# microHAM U3 (PTT + TX Audio)
+
+Diese Anleitung beschreibt Betrieb, Einstellung und Basis-Kalibrierung der microHAM-Anbindung ueber das Plugin `rms.microham`.
+
+## Quick Start
+
+```bash
+ls -l /dev/rms-microham-u3
+arecord -l
+ffmpeg -version
+
+grep -E '^(MICROHAM_DEVICE|MICROHAM_PTT_COMMANDS_ENABLED|MICROHAM_AUDIO_ALSA_DEVICE|MICROHAM_AUDIO_INPUT_MIME)=' /etc/remotestation-arcg/remotestation-arcg.env
+sudo systemctl restart remotestation-arcg
+curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8080/v1/openwebrx/tx/status
+```
+
+## 1) Hardware und Voraussetzungen
+
+- Device: typischerweise `/dev/rms-microham-u3`
+- Audio-Backend: `ffmpeg` + gueltiges ALSA Capture-Device (`MICROHAM_AUDIO_ALSA_DEVICE`)
+- Optional fuer Batch-PTT-Down mit Frequenz/Mode: `rigctl`
+
+## 2) Relevante ENV-Keys
+
+```env
+MICROHAM_DEVICE=/dev/rms-microham-u3
+
+MICROHAM_PTT_COMMANDS_ENABLED=true
+MICROHAM_PTT_DOWN_CMD=
+MICROHAM_PTT_UP_CMD=
+MICROHAM_PTT_TIMEOUT_MS=5000
+
+MICROHAM_PTT_APPLY_BAND_STATE=true
+MICROHAM_PTT_RIGCTL_MODEL=3023
+MICROHAM_PTT_RIGCTL_BAUD=19200
+MICROHAM_PTT_RIGCTL_SETCONF=rts_state=OFF,dtr_state=OFF
+
+MICROHAM_AUDIO_ENABLED=true
+MICROHAM_AUDIO_ALSA_DEVICE=plughw:CARD=CODEC,DEV=0
+MICROHAM_AUDIO_INPUT_MIME=webm
+MICROHAM_AUDIO_CHUNK_MS=100
+MICROHAM_AUDIO_STOP_ON_DISCONNECT=true
+MICROHAM_AUDIO_SESSION_TIMEOUT_MS=120000
+MICROHAM_AUDIO_FFMPEG_PATH=/usr/bin/ffmpeg
+MICROHAM_AUDIO_FFMPEG_EXTRA_ARGS=
+```
+
+## 3) Bedienung (Runtime)
+
+- PTT down: `POST /v1/openwebrx/ptt/down`
+- PTT up: `POST /v1/openwebrx/ptt/up`
+- TX Status inkl. PTT-Konfiguration: `GET /v1/openwebrx/tx/status`
+- Audio-WS (Plugin-Pfad): `/v1/openwebrx/plugin/audio/ws`
+
+Hinweis: PTT und TX-Power sind getrennt. TX-Power kommt aus `tx.control`, PTT aus `rms.microham`.
+
+## 4) Einstellen und Kalibrieren
+
+### PTT
+
+1. Erst sichere `pttUp`/`pttDown` Kommandos setzen.
+2. `MICROHAM_PTT_COMMANDS_ENABLED=true` aktivieren.
+3. Falls Band-/Mode-konsistentes PTT gewuenscht: `MICROHAM_PTT_APPLY_BAND_STATE=true`.
+4. Bei Instabilitaet `MICROHAM_PTT_TIMEOUT_MS` moderat erhoehen (nicht exzessiv).
+
+### Audio
+
+1. `MICROHAM_AUDIO_ALSA_DEVICE` mit `arecord -l` auf reales Capture-Device setzen.
+2. `MICROHAM_AUDIO_INPUT_MIME` auf den Client abstimmen (`webm` oder `ogg`).
+3. Bei Dropouts/Artefakten:
+   - `MICROHAM_AUDIO_CHUNK_MS` leicht erhoehen (z. B. 100 -> 120/140)
+   - zusaetzliche ffmpeg-Args nur kontrolliert setzen.
+
+## 5) Typische Fehlerbilder
+
+- `MICROHAM_PTT_COMMANDS_ENABLED must be true`: PTT nicht aktiviert.
+- `MICROHAM_PTT_DOWN_CMD missing`/`UP_CMD missing`: Kommandos fehlen (wenn kein Batch-Pfad genutzt).
+- `invalid microham device path`: ungueltiger Device-String.
+- Audio startet nicht: `ffmpeg` fehlt oder ALSA-Device falsch.
+
+## 6) Sicherheitsregeln
+
+- Immer zuerst PTT-up/Fail-safe testen, dann PTT-down.
+- Keine Live-Credentials oder host-spezifische sensible Werte in dieses Repo schreiben.

docs/hardware-rfroute-guide.md

@@ -0,0 +1,62 @@
+# RF Route Hardware (Relais / Antennenpfad)
+
+Diese Anleitung beschreibt die RF-Route-Steuerung ueber `rms.rfroute.shell`.
+
+## Quick Start
+
+```bash
+grep -E '^(RFROUTE_CMD_TX|RFROUTE_CMD_RX|RFROUTE_CMD_DRAHT|RFROUTE_CMD_BEAM|RFROUTE_CMD_WRTC|RFROUTE_TIMEOUT_MS)=' /etc/remotestation-arcg/remotestation-arcg.env
+sudo systemctl restart remotestation-arcg
+```
+
+## 1) Unterstuetzte Routen
+
+Das Plugin kennt diese Route-Keys:
+
+- `tx`, `rx`
+- `on`, `off`
+- `draht`, `beam`, `wrtc`
+
+Je Route wird ein Shell-Kommando aus ENV ausgefuehrt.
+
+## 2) Relevante ENV-Keys
+
+```env
+RFROUTE_CMD_TX=
+RFROUTE_CMD_RX=
+RFROUTE_CMD_ON=
+RFROUTE_CMD_OFF=
+RFROUTE_CMD_DRAHT=
+RFROUTE_CMD_BEAM=
+RFROUTE_CMD_WRTC=
+RFROUTE_TIMEOUT_MS=15000
+RFROUTE_DEFAULT=rx
+```
+
+## 3) Bedienung
+
+Die Route wird serverseitig ueber Capability `rfroute.set` gesetzt. In der UI erscheinen die Optionen als Schaltergruppe.
+
+Wichtig im Betrieb:
+
+- Umschalten ist bei aktivem TX serverseitig gesperrt (TX-Safety).
+- Im OpenWebRX-Flow werden Route-Folgen und Fail-Safe-Wechsel (z. B. auf `rx`) zusaetzlich serverseitig erzwungen.
+
+## 4) Einstellen / Kalibrieren
+
+1. Jede Route einzeln auf Shell-Ebene verifizieren.
+2. Sicherstellen, dass `rx` ein echter Empfangspfad ist.
+3. Sicherstellen, dass `tx` nur im gewuenschten TX-Pfad landet.
+4. Bei Multi-Antennen (`draht/beam/wrtc`) klare Mapping-Tabelle pflegen.
+5. Timeouts nur bei echten Geraetelatenzen erhoehen.
+
+## 5) Fehlerbilder
+
+- `RFROUTE_CMD_<ROUTE> fehlt`: Kommando fuer angeforderte Route fehlt.
+- `rfroute command failed`: Shell-Kommando liefert Fehlercode/Stderr.
+- Route schaltet, aber Wirkung falsch: Relais-Mapping (Hardwareverdrahtung) pruefen.
+
+## 6) Sicherheitsregeln
+
+- Keine Schaltkommandos committen, die sensible Host-/Credential-Daten enthalten.
+- TX/RX-Safety-Pfade regelmaessig mit realer Hardware pruefen.

docs/hardware-station-shell-guide.md

@@ -0,0 +1,46 @@
+# Station Hardware via Shell Scripts
+
+Diese Anleitung beschreibt die stationseitige Hardware-Orchestrierung ueber `rms.station.shell`.
+
+Das Plugin selbst steuert keine einzelne Komponente direkt, sondern ruft Aktivierungs-/Deaktivierungs-Skripte auf, die typischerweise Relais, Netzteile, TRX und Nebenkomponenten schalten.
+
+## Quick Start
+
+```bash
+grep -E '^(SCRIPT_ROOT|SCRIPT_ACTIVATE|SCRIPT_DEACTIVATE|STATION_SCRIPT_TIMEOUT_MS)=' /etc/remotestation-arcg/remotestation-arcg.env
+sudo systemctl restart remotestation-arcg
+```
+
+## 1) Relevante ENV-Keys
+
+```env
+SCRIPT_ROOT=/opt/remotestation
+SCRIPT_ACTIVATE=/opt/remotestation/bin/activate.sh
+SCRIPT_DEACTIVATE=/opt/remotestation/bin/deactivate.sh
+STATION_SCRIPT_TIMEOUT_MS=180000
+```
+
+## 2) Verhalten
+
+- `station.activate` ruft `SCRIPT_ACTIVATE` auf.
+- `station.deactivate` ruft `SCRIPT_DEACTIVATE` auf.
+- Falls Standardskript fehlt, versucht das Plugin Runtime-Fallbacks unter `SCRIPT_ROOT/src/...`.
+- Wenn kein Skript konfiguriert ist, wird Aktion als `skipped` behandelt.
+
+## 3) Einstellen
+
+1. Skripte separat shellseitig testen.
+2. `SCRIPT_ROOT` so setzen, dass Fallback-Pfade konsistent sind.
+3. Timeouts an reale Schaltzeiten anpassen.
+4. In Skripten idempotent arbeiten (mehrfaches Ausfuehren darf nicht zerstoeren).
+
+## 4) Fehlerbilder
+
+- `${KEY} failed`: Skriptfehler (Exit != 0 / stderr).
+- Standardskript fehlt: Plugin meldet Skip/Fallback.
+- Timeout: `STATION_SCRIPT_TIMEOUT_MS` zu niedrig oder Skript haengt.
+
+## 5) Sicherheitsregeln
+
+- Skripte muessen TX/PTT-Fail-safe beachten.
+- Keine produktiven Zugangsdaten in Skripten oder Repo ablegen.

docs/hardware-tx-control-guide.md

@@ -0,0 +1,62 @@
+# TX Power Control Hardware
+
+Diese Anleitung beschreibt die TX-Power-Steuerung ueber `rms.tx.control.native`.
+
+## Quick Start
+
+```bash
+grep -E '^(TX_ENABLE_CMD|TX_DISABLE_CMD|TX_STATUS_CMD|TX_CONTROL_TIMEOUT_MS|TX_STATE_PATH)=' /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/openwebrx/tx/enable
+curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8080/v1/openwebrx/tx/status
+curl -sS -H "Authorization: Bearer <token>" -X POST http://127.0.0.1:8080/v1/openwebrx/tx/disable
+```
+
+## 1) Funktionsprinzip
+
+- `enableTx` fuehrt `TX_ENABLE_CMD` aus.
+- `disableTx` fuehrt `TX_DISABLE_CMD` aus.
+- `getTxState` nutzt bevorzugt `TX_STATUS_CMD`; Fallback ist `TX_STATE_PATH` (JSON).
+
+Default-Kommandos (wenn nicht ueberschrieben):
+
+- `/opt/remotestation/bin/tx-control.sh enable`
+- `/opt/remotestation/bin/tx-control.sh disable`
+- `/opt/remotestation/bin/tx-control.sh status`
+
+## 2) Relevante ENV-Keys
+
+```env
+TX_ENABLE_CMD=
+TX_DISABLE_CMD=
+TX_STATUS_CMD=
+TX_CONTROL_TIMEOUT_MS=20000
+TX_STATE_PATH=/opt/remotestation-arcg/shared/data/tx-state.json
+```
+
+## 3) Bedienung
+
+- API:
+  - `POST /v1/openwebrx/tx/enable`
+  - `POST /v1/openwebrx/tx/disable`
+  - `GET /v1/openwebrx/tx/status`
+
+Hinweis: TX-Power ist getrennt von PTT. PTT wird ueber `rms.microham` verwaltet.
+
+## 4) Einstellen und Kalibrieren
+
+1. Enable/Disable-Kommandos zuerst auf Shell-Ebene pruefen.
+2. `TX_STATUS_CMD` auf klaren Rueckgabewert trimmen (`on/off`, `1/0`, `true/false`).
+3. Wenn Statuskommando nicht stabil ist, JSON-Fallback (`TX_STATE_PATH`) bewusst nutzen.
+4. Zeitlimit `TX_CONTROL_TIMEOUT_MS` nur bei echter Hardwarelatenz anpassen.
+
+## 5) Fehlerbilder
+
+- `TX enable command missing` / `TX disable command missing`: ENV fehlt.
+- `TX enable failed` / `TX disable failed`: Kommando liefert Fehler.
+- Status falsch trotz Schalten: `TX_STATUS_CMD` und Zustandsquelle pruefen.
+
+## 6) Sicherheitsregeln
+
+- Verwende fail-safe Standard: bei Unsicherheit TX auf OFF.
+- Keine produktiven Schalt-Backends oder Zugangsdaten ins Repo committen.

docs/hardware-vswr-nanovna-guide.md

@@ -0,0 +1,70 @@
+# 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.