diff --git a/WORKING_CONTEXT.md b/WORKING_CONTEXT.md index ec1cede..aa45e7e 100644 --- a/WORKING_CONTEXT.md +++ b/WORKING_CONTEXT.md @@ -59,3 +59,4 @@ Expected priority order: - Added external-reference notes for AlfaSpid RAK/ROT1Prog manual: - `docs/rotor-alfaspid-rak-rot1prog-manual-notes.md` - Linked the new notes page from `README.md` under RF/Hardware guides. +- Expanded `docs/rotor-rot1prog-guide.md` into a full end-to-end setup/calibration/runbook guide. diff --git a/docs/rotor-rot1prog-guide.md b/docs/rotor-rot1prog-guide.md index 7e87834..1ca4fbb 100644 --- a/docs/rotor-rot1prog-guide.md +++ b/docs/rotor-rot1prog-guide.md @@ -1,31 +1,50 @@ -# ROT1Prog Rotorsteuerung (Bedienen, Einstellen, Kalibrieren) +# ROT1Prog Rotorsteuerung (vollstaendige Praxisanleitung fuer RMS) -Diese Anleitung fasst den aktuellen Stand aus der RMS-Software zusammen, um einen Rotor mit ROT1Prog/Hamlib in Betrieb zu nehmen und zu warten. +Diese Seite ist die komplette Betriebsanleitung fuer die Einrichtung eines ROT1Prog/AlfaSpid-Controllers in RMS: von der Hardware-Inbetriebnahme ueber Kalibrierung bis zum Produktivbetrieb mit OpenWebRX. -Hinweis: In der RMS-Software wird der Rotor nativ ueber `rotctl` gesteuert (Model-ID standardmaessig `902`). +Hinweis: In RMS wird der Rotor ueber Hamlib/`rotctl` gesteuert (typisch Modell-ID `902`). -## Quick Start (10 Zeilen) +## Schnellablauf (wenn du schon Erfahrung hast) ```bash sudo apt update && sudo apt install -y hamlib-utils -export ROTOR_DEV=/dev/rms-ftdi-uart +export ROTOR_DEV=/dev/rms-rotor 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 +rotctl -m 902 -r "${ROTOR_DEV}" -Z --set-conf=post_write_delay=0 p p P 180 0 p p +rotctl -m 902 -r "${ROTOR_DEV}" -Z --set-conf=post_write_delay=0 p p P 270 0 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 " http://127.0.0.1:8080/v1/openwebrx/rotor/status ``` -Wenn Zeile 3 und 5 plausible Azimuth-Werte liefern, ist die Basisverbindung ok. +Wenn die Azimuth-Werte plausibel mitlaufen und ein Set auf Zielwinkel sauber endet, ist die Basis ok. -## 1) Voraussetzungen +## 1) Sicherheits- und Vorbereitungscheck -- 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`) +Vor jedem Testlauf: -Pruefen: +- Antennenumfeld freihalten (keine Personen im Drehbereich). +- Mechanische Endanschlaege kennen und als Limits im Controller setzen. +- Not-Aus/Abschaltmoeglichkeit griffbereit halten. +- Bei erstmaliger Inbetriebnahme mit reduzierter Geschwindigkeit bzw. beobachteter Testfahrt starten. + +## 2) Hardwareaufbau und Verdrahtung + +Die genaue Klemmenbelegung kommt aus dem Controllerblatt. Fuer RMS ist entscheidend: + +- Motorleitungen korrekt angeschlossen. +- Rueckmeldeleitung (Positionssensor/Poti) stabil und nicht vertauscht. +- Gemeinsame Masse sauber gefuehrt. +- Versorgungsspannung innerhalb Spezifikation. +- Bei langen Leitungen: vernuenftiger Querschnitt, sauberer Schirm/EMV-Aufbau. + +Praxisregel: + +- Erst lokalen Controllerbetrieb stabil bekommen. +- Danach erst PC/Hamlib/RMS anbinden. + +## 3) Linux/Host Voraussetzungen ```bash command -v rotctl @@ -33,12 +52,58 @@ ls -l /dev/rms-* id -nG remotestation ``` -## 2) Relevante RMS-Konfiguration +Erwartung: -In `.env` (oder produktiv in `/etc/remotestation-arcg/remotestation-arcg.env`): +- `rotctl` vorhanden. +- Serielles Device sichtbar (z. B. `/dev/rms-rotor`, `/dev/rms-ftdi-uart`). +- Service-User hat Zugriff (typisch Gruppe `dialout`). + +## 4) Stabile Device-Zuordnung (empfohlen) + +Nutze einen festen Alias (`/dev/rms-rotor`) statt wechselnder `ttyUSBx`-Namen. + +- Vorteil: USB-Reconnect oder Reboot bricht nicht die RMS-Konfiguration. +- Umsetzung je nach Deploy-Repo per udev-Regel. + +## 5) Controller-Grundkonfiguration (vor RMS) + +Auf Controllerseite müssen folgende Punkte sauber gesetzt sein: + +- Arbeitsbereich (Azimuth-Limits) passend zur realen Mechanik. +- Null-/Referenzrichtung (typisch geographisch Nord) konsistent zur Stationsdoku. +- Drehrichtung korrekt (CW/CCW nicht invertiert). +- Presets optional, aber nicht zwingend fuer RMS. + +Wichtig: RMS hat keinen eigenen Offset-Parameter fuer Azimuth. Die Wahrheit muss im Controller stimmen. + +## 6) Bench-Test mit Hamlib + +Status lesen: + +```bash +rotctl -m 902 -r /dev/rms-rotor p p +``` + +Setzen + Status davor/danach: + +```bash +rotctl -m 902 -r /dev/rms-rotor -Z --set-conf=post_write_delay=0 p p P 90 0 p p +rotctl -m 902 -r /dev/rms-rotor -Z --set-conf=post_write_delay=0 p p P 180 0 p p +rotctl -m 902 -r /dev/rms-rotor -Z --set-conf=post_write_delay=0 p p P 270 0 p p +``` + +Sollverhalten: + +- `p p` liefert konsistente numerische Rueckmeldung. +- Der Rotor faehrt reproduzierbar auf Zielwinkel. +- Keine Aussetzer/Time-outs. + +## 7) RMS-Konfiguration + +In `/etc/remotestation-arcg/remotestation-arcg.env` (oder entsprechender Runtime-ENV): ```env -RMS_ROTOR_DEV=/dev/rms-ftdi-uart +RMS_ROTOR_DEV=/dev/rms-rotor ROTOR_ROTCTL_MODEL=902 ROTOR_SET_ENABLED=true @@ -49,43 +114,18 @@ ROTOR_STATUS_RETRY_DELAY_MS=400 ROTOR_POST_SET_STATUS_TIMEOUT_MS=5000 ``` -Danach Dienst neu starten: +Danach: ```bash sudo systemctl restart remotestation-arcg ``` -## 3) Funktionstest auf Shell-Ebene +## 8) API-Bedienung in RMS/OpenWebRX -Status lesen: +- Status: `GET /v1/openwebrx/rotor/status` +- Setzen: `POST /v1/openwebrx/rotor/set` -```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: +Beispiel-Set: ```json { @@ -94,40 +134,99 @@ Beispiel: } ``` -## 5) Kalibrierung (praxisnah) +Guards: -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. +- Nur aktiver Stationsnutzer darf setzen. +- `trigger` muss `"user"` sein. +- Zielbereich ist `0..360`. -Empfohlenes Vorgehen: +## 9) Kalibrierung (sauberer Ablauf) -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. +Ziel: Controllerwert und reale Antennenrichtung muessen deckungsgleich sein. -## 6) Monitoring- und Laufzeitverhalten in RMS +Schrittfolge: -- 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. +1. Mechanische Referenz anfahren (z. B. Nordmarke). +2. `rotctl ... p p` lesen und dokumentieren. +3. Abweichung am Controller korrigieren (Nullpunkt/Offset laut Controller-Setup). +4. Erneut Referenz pruefen. +5. Vierpunkt-Test fahren (`0/90/180/270`). +6. Zur Referenz zurueckfahren und Drift pruefen. +7. Erst danach RMS produktiv freigeben. -## 7) Typische Fehlerbilder + Fix +Akzeptanzkriterium: -- `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. +- Reproduzierbare Rueckkehr auf Referenzpunkt. +- Keine systematische Fehlanzeige in eine Richtung. -## 8) Betriebs-Tipps +## 10) Lange Kabelwege / Stoerungen -- 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. +Typische Effekte: + +- Unruhige Positionswerte. +- Sporadische Lesefehler. +- Verzoegerter Start/Stopp. + +Massnahmen: + +- Leitungsfuehrung und Massekonzept verbessern. +- Schirmung pruefen. +- Steckverbinder nachziehen/reinigen. +- Erst danach Software-Timeouts anheben. + +## 11) Monitoringverhalten in RMS + +- Nach `set` pollt RMS den Fortschritt. +- Ziel gilt als erreicht bei kleinem Restabstand (typisch <= 5 Grad). +- Status kann bei Lesefehlern als `stale` geliefert werden. + +Fehlermuster: + +- `did not start moving` +- `movement stalled` +- `did not reach target within timeout` + +## 12) Troubleshooting-Runbook + +### A) `permission denied` / `cannot open` + +- Device-Rechte pruefen. +- `remotestation` in `dialout`. +- Service neu starten. + +### B) `device not found` + +- Alias fehlt oder falscher Device-Pfad. +- Udev-Regel pruefen. + +### C) Set wird vom API-Guard abgelehnt + +- `ROTOR_SET_ENABLED=true`. +- `trigger: "user"` senden. +- Owner-Status der Session pruefen. + +### D) Anzeige bleibt statisch / 0 Grad + +- `rotctl p p` Rohformat pruefen. +- Controller-Rueckmeldung auf Sensorseite verifizieren. + +## 13) Produktiv-Freigabecheck + +Vor Go-Live einmal komplett: + +1. 15-30 Minuten zyklische Testfahrten. +2. Mehrfaches Setzen auf gleiche Ziele (Wiederholgenauigkeit). +3. Rueckkehrtest auf Referenzpunkt. +4. RMS/API/OpenWebRX konsistent? +5. Fehlerfrei ueber Service-Restart? + +## 14) Wartung + +- Quartalsweise Steckverbinder und Zugentlastung pruefen. +- Nach mechanischen Eingriffen immer neu kalibrieren. +- Nach USB/Kernel/Hostwechsel immer zuerst Shell-Test (`rotctl`), dann RMS. + +## 15) Verwandte Dokumente + +- Hamlib Plugin: `docs/plugins/rms-rotor-hamlib.md` +- Hersteller-Referenzhinweis: `docs/rotor-alfaspid-rak-rot1prog-manual-notes.md`