From aa9390ce5e14283f88c8fead68b2b3331e184276 Mon Sep 17 00:00:00 2001 From: OE6DXD Date: Wed, 18 Mar 2026 00:05:37 +0100 Subject: [PATCH] add per-hardware plugin operation guides in docs --- README.md | 5 +- docs/hardware-microham-guide.md | 84 ++++++++++++++++++++++++++++ docs/hardware-rfroute-guide.md | 62 ++++++++++++++++++++ docs/hardware-station-shell-guide.md | 46 +++++++++++++++ docs/hardware-tx-control-guide.md | 62 ++++++++++++++++++++ docs/hardware-vswr-nanovna-guide.md | 70 +++++++++++++++++++++++ 6 files changed, 328 insertions(+), 1 deletion(-) create mode 100644 docs/hardware-microham-guide.md create mode 100644 docs/hardware-rfroute-guide.md create mode 100644 docs/hardware-station-shell-guide.md create mode 100644 docs/hardware-tx-control-guide.md create mode 100644 docs/hardware-vswr-nanovna-guide.md diff --git a/README.md b/README.md index 3cc60f6..2fc59fd 100644 --- a/README.md +++ b/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 diff --git a/docs/hardware-microham-guide.md b/docs/hardware-microham-guide.md new file mode 100644 index 0000000..b480f39 --- /dev/null +++ b/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 " 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. diff --git a/docs/hardware-rfroute-guide.md b/docs/hardware-rfroute-guide.md new file mode 100644 index 0000000..2605387 --- /dev/null +++ b/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_ 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. diff --git a/docs/hardware-station-shell-guide.md b/docs/hardware-station-shell-guide.md new file mode 100644 index 0000000..65c5d75 --- /dev/null +++ b/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. diff --git a/docs/hardware-tx-control-guide.md b/docs/hardware-tx-control-guide.md new file mode 100644 index 0000000..e3ccfb7 --- /dev/null +++ b/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 " -X POST http://127.0.0.1:8080/v1/openwebrx/tx/enable +curl -sS -H "Authorization: Bearer " http://127.0.0.1:8080/v1/openwebrx/tx/status +curl -sS -H "Authorization: Bearer " -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. diff --git a/docs/hardware-vswr-nanovna-guide.md b/docs/hardware-vswr-nanovna-guide.md new file mode 100644 index 0000000..2b8fec2 --- /dev/null +++ b/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 " -X POST http://127.0.0.1:8080/v1/swr/run-check +curl -sS -H "Authorization: Bearer " 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.