# 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`
- Vollstaendiges Hersteller-PDF im Repo: `docs/RAK_Rot1Prog.pdf`

## 16) Herstellerdetails aus ROT1Prog-Manual (15 SEP 2022)

Die folgenden Punkte sind explizit aus der Controller-Anleitung uebernommen und fuer RMS-Betrieb relevant.

### 16.1 Controller-Funktionen und Eckdaten

- Digitale Anzeige mit 1-Grad-Aufloesung.
- Versorgung: `13.8..18 V` bei ca. `3..8 A`.
- Elektronische Overtravel-Range: insgesamt `720 Grad` (normal 360 + je 180 Overtravel links/rechts).
- Programmierbare Limits (u. a. fuer Side-Mount).
- USB-Schnittstelle fuer PC-Steuerung.
- Optionales Mouse-Panel mit L/R/Stop und 6 Preset-Tasten.

### 16.2 Front-/Back-Hinweise

- Front: L/R-Tasten, Setup-/Function-Tasten, 4-stellige Anzeige, Overlap-Indikator.
- Legacy-Serienversion (nicht mehr produziert):
  - 4-Pin Rotatoranschluss: Pin 1/2 Motor Drive, Pin 3/4 Impulse Sense.
  - Blue/Brown Motorleitungen sind laut Manual in der Polaritaet unkritisch.

### 16.3 Setup-Menuepunkte (ROT1Prog)

Der Setup-Dialog durchlaeuft u. a. diese Parameter:

- Ratio: `1.00` (Default) bzw. `0.80` bei Ring-Version.
- Programmierbares High Limit (clockwise).
- Programmierbares Low Limit (counter-clockwise).
- Programmierbarer Reset-Wert (`0` oder `180`).
- Presets `P1..P6`.
- Program Simulation (Emulation).
- Heading Adjust (blinkende Zahlen).

### 16.4 Program Simulation / Emulation

Im Manual aufgefuehrte Simulationsmodi:

- `Spid`
- `Orion`
- `Hygain`
- `Yaesu`

Manual-Hinweis: Alfa empfiehlt die Fremdprotokolle nicht aktiv zu supporten; ausserdem koennen manche Programme mit den seriellen Anforderungen nicht sauber arbeiten.

### 16.5 PC-Kommunikation

- Serielle Einstellungen: `1200-8-N-1`.
- USB-Version mit FTDI `FT232RL`.
- Linux-Portsuche laut Manual:
  - `ls /dev/ttyUSB*`
- macOS-Portsuche laut Manual:
  - `ls /dev/tty.*`

### 16.6 Betriebsmodi

Laut Manual sind folgende Modi vorgesehen:

- Normal Operations Mode
- Half Auto Mode
- Auto Mode
- Preset Mode (mit optionaler Mouse)

Kurzlogik:

- **Normal**: L/R fahren solange Taste gedrueckt ist.
- **Half Auto**: Zielrichtung vorwaehlen, nach kurzer Inaktivitaet beginnt automatische Fahrt.
- **Auto**: Befehle von PC-Software; manuelle Tasten als Override.
- **Preset**: Preset-Tasten fahren auf gespeicherte Headings.

### 16.7 Reset/Kalibrierung und Overtravel-Anzeige

Manual-Kernpunkte:

- Beim Reset wird nicht automatisch alles auf "True North" gezwungen; Kalibrierung erfolgt bewusst.
- Reset-Prozedur beeinflusst nicht automatisch Presets/Limits.
- Overtravel-Indikator:
  - steady dot fuer eine Seite,
  - blinking dot fuer die andere Overtravel-Seite.

Fuer RMS bedeutet das: Controller-Referenz immer dokumentieren und nach Servicearbeiten reproduzierbar neu anfahren.

### 16.8 208-Condition (Manual-Fehlerbild)

Die Anleitung beschreibt einen Sonderfall, bei dem der Controller scheinbar ohne Nutzerkommando auf `208` Grad fahren kann (Command-Flood/Overload-Szenario).

Praxisregel fuer RMS:

- Kommandos nicht unnoetig dicht hintereinander feuern.
- Bei Automationspfaden kleine Guard-Delays einplanen.
- Bei reproduzierbarem Verhalten zuerst lokale Controllerbedienung und Sense-Leitung pruefen.

### 16.9 Motor-Sense/Schutzhinweis

Laut Manual wird bei fehlender Sense-Rueckmeldung der Motor durch Schutzlogik abgeschaltet.

- Symptom: Motor startet kurz und stoppt wieder.
- Pruefen: Sense-/Reed-Wiring und mechanische Blockade.

### 16.10 Warranty/Service-Hinweis

Die Anleitung enthaelt 12-Monats-Gewaehrleistung mit einschraenkenden Bedingungen (u. a. kein Schutz bei Fremdgeraetekombination, Blitz, Fehlbedienung etc.).

Fuer RMS-Dokumentation bleibt entscheidend:

- Bei Hardwareauffaelligkeiten zuerst Bench-Test auf Controllerseite,
- dann RMS-Integration getrennt validieren,
- und Servicefaelle inkl. Kaufnachweis dokumentieren.