add rot1prog rotor operating guide with quick-start steps

README.md

@@ -65,6 +65,7 @@ TX/PTT/Audio
 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`
 
 VSWR
 - `rms.vswr.native`: native VSWR command provider

docs/rotor-rot1prog-guide.md

@@ -0,0 +1,133 @@
+# ROT1Prog Rotorsteuerung (Bedienen, Einstellen, Kalibrieren)
+
+Diese Anleitung fasst den aktuellen Stand aus der RMS-Software zusammen, um einen Rotor mit ROT1Prog/Hamlib in Betrieb zu nehmen und zu warten.
+
+Hinweis: In der RMS-Software wird der Rotor nativ ueber `rotctl` gesteuert (Model-ID standardmaessig `902`).
+
+## Quick Start (10 Zeilen)
+
+```bash
+sudo apt update && sudo apt install -y hamlib-utils
+export ROTOR_DEV=/dev/rms-ftdi-uart
+rotctl -m 902 -r "${ROTOR_DEV}" p p
+rotctl -m 902 -r "${ROTOR_DEV}" -Z --set-conf=post_write_delay=0 p p P 90 0 p p
+rotctl -m 902 -r "${ROTOR_DEV}" p p
+grep -E '^(RMS_ROTOR_DEV|ROTOR_ROTCTL_MODEL|ROTOR_SET_ENABLED)=' /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/rotor/status
+```
+
+Wenn Zeile 3 und 5 plausible Azimuth-Werte liefern, ist die Basisverbindung ok.
+
+## 1) Voraussetzungen
+
+- Linux-Host mit installiertem `rotctl` (Paket `hamlib-utils`)
+- Serielles Device fuer den Rotor (z. B. `/dev/rms-ftdi-uart` oder dediziert `/dev/rms-rotor`)
+- Dienstuser `remotestation` mit Zugriff auf serielle Devices (typisch Gruppe `dialout`)
+
+Pruefen:
+
+```bash
+command -v rotctl
+ls -l /dev/rms-*
+id -nG remotestation
+```
+
+## 2) Relevante RMS-Konfiguration
+
+In `.env` (oder produktiv in `/etc/remotestation-arcg/remotestation-arcg.env`):
+
+```env
+RMS_ROTOR_DEV=/dev/rms-ftdi-uart
+ROTOR_ROTCTL_MODEL=902
+ROTOR_SET_ENABLED=true
+
+ROTOR_SET_TIMEOUT_MS=20000
+ROTOR_GET_TIMEOUT_MS=10000
+ROTOR_STATUS_RETRY_COUNT=6
+ROTOR_STATUS_RETRY_DELAY_MS=400
+ROTOR_POST_SET_STATUS_TIMEOUT_MS=5000
+```
+
+Danach Dienst neu starten:
+
+```bash
+sudo systemctl restart remotestation-arcg
+```
+
+## 3) Funktionstest auf Shell-Ebene
+
+Status lesen:
+
+```bash
+rotctl -m 902 -r /dev/rms-ftdi-uart p p
+```
+
+Sollzustand: Ausgabe enthaelt verwertbare Azimuth-Information (bei `p p` typischerweise erste numerische Zeile = Azimuth, zweite = Elevation).
+
+Setzen auf Zielwinkel:
+
+```bash
+rotctl -m 902 -r /dev/rms-ftdi-uart -Z --set-conf=post_write_delay=0 p p P 90 0 p p
+```
+
+Die RMS-Software nutzt intern dieses Muster (`p p` vor/nach `P ...`) fuer robustes Monitoring.
+
+## 4) Bedienung in RMS/OpenWebRX
+
+- Rotorstatus: `GET /v1/openwebrx/rotor/status`
+- Rotor setzen: `POST /v1/openwebrx/rotor/set`
+
+Wichtig fuer `set`:
+
+- Nur aktiver Stationsnutzer darf setzen (Owner-Policy).
+- `trigger` muss `"user"` sein (Guard gegen unbeabsichtigte Set-Aktionen).
+- `target` muss zwischen `0..360` liegen.
+- Set-Auftraege werden gequeued; ein neuer Zielwert kann einen pending Zielwert ersetzen.
+
+Beispiel:
+
+```json
+{
+  "trigger": "user",
+  "target": 180
+}
+```
+
+## 5) Kalibrierung (praxisnah)
+
+Die RMS-Software hat aktuell keinen eigenen Azimuth-Offset-Parameter. Kalibrierung passiert daher am Rotor/Controller selbst (ROT1Prog-Seite), RMS liest/steuert dann den kalibrierten Wert.
+
+Empfohlenes Vorgehen:
+
+1. Rotor auf bekannten mechanischen Referenzpunkt fahren (z. B. Nordmarke).
+2. Mit `rotctl ... p p` Ist-Azimuth lesen.
+3. Falls Istwert nicht zur realen Richtung passt, Offset/Nullpunkt am ROT1Prog/Controller korrigieren.
+4. Erneut `p p` pruefen.
+5. Testfahrten auf mehrere Punkte (z. B. 90/180/270) und Rueckkehr auf Referenzpunkt.
+6. Erst danach in RMS produktiv nutzen.
+
+## 6) Monitoring- und Laufzeitverhalten in RMS
+
+- Nach Set-Befehl wird Bewegung aktiv ueber Polling ueberwacht.
+- Ziel gilt als erreicht bei <= 5 Grad Abstand.
+- Fehlerfaelle:
+  - Rotor startet nicht (`did not start moving`)
+  - Rotor bleibt stehen (`movement stalled`)
+  - Ziel nicht innerhalb Timeout (`did not reach target within timeout`)
+- Bei Statuslesefehlern wird letzter bekannter Wert als `stale` geliefert.
+
+## 7) Typische Fehlerbilder + Fix
+
+- `permission denied`/`cannot open`: Device-Rechte/Gruppe `dialout` pruefen.
+- `device not found`: falscher Device-Pfad oder udev-Alias fehlt.
+- `rotor.set_disabled`: `ROTOR_SET_ENABLED=false`.
+- `rotor.set_guard`: API-Aufruf ohne `trigger:"user"`.
+- `openwebrx.not_owner`: nur aktiver Stationsnutzer darf Rotor steuern.
+- Statische `0°`-Anzeigen: Ausgabeformat von `rotctl p p` pruefen; RMS verwirft einzelne unlabeled Zahlenzeilen bewusst.
+
+## 8) Betriebs-Tipps
+
+- Fuer stabile Geraetezuordnung dedizierten Alias verwenden (`/dev/rms-rotor`).
+- Bei USB-Umstecken immer erst Shell-Test (`rotctl ... p p`), dann RMS testen.
+- Timeouts nur vorsichtig erhoehen; zu hoch kaschiert echte Kommunikationsprobleme.