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