ARCG/ARCG-Remote-Station-Software
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

expand ROT1Prog setup and calibration runbook

Browse Source
This commit is contained in:
OE6DXD
2026-03-18 22:42:08 +01:00
parent f779ef9ef6
commit e201e5c460
2 changed files with 173 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
WORKING_CONTEXT.md
View File

@@ -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.

245
docs/rotor-rot1prog-guide.md
View File

@@ -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 <token>" 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`