# ROT1Prog Rotorsteuerung (vollstaendige Praxisanleitung fuer RMS)

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 RMS wird der Rotor ueber Hamlib/`rotctl` gesteuert (typisch Modell-ID `902`).

## Schnellablauf (wenn du schon Erfahrung hast)

```bash
sudo apt update && sudo apt install -y hamlib-utils
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}" -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 die Azimuth-Werte plausibel mitlaufen und ein Set auf Zielwinkel sauber endet, ist die Basis ok.

## 1) Sicherheits- und Vorbereitungscheck

Vor jedem Testlauf:

- 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
ls -l /dev/rms-*
id -nG remotestation
```

Erwartung:

- `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-rotor
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:

```bash
sudo systemctl restart remotestation-arcg
```

## 8) API-Bedienung in RMS/OpenWebRX

- Status: `GET /v1/openwebrx/rotor/status`
- Setzen: `POST /v1/openwebrx/rotor/set`

Beispiel-Set:

```json
{
  "trigger": "user",
  "target": 180
}
```

Guards:

- Nur aktiver Stationsnutzer darf setzen.
- `trigger` muss `"user"` sein.
- Zielbereich ist `0..360`.

## 9) Kalibrierung (sauberer Ablauf)

Ziel: Controllerwert und reale Antennenrichtung muessen deckungsgleich sein.

Schrittfolge:

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.

Akzeptanzkriterium:

- Reproduzierbare Rueckkehr auf Referenzpunkt.
- Keine systematische Fehlanzeige in eine Richtung.

## 10) Lange Kabelwege / Stoerungen

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`