# API-Referenz

Der Driver stellt zwei Schnittstellen bereit:

| Schnittstelle | Zweck | Port (Container) | Port (Host, docker-compose) |
|---------------|-------|------------------|------------------------------|
| **Input WebSocket** | Steuerbefehle empfangen, Status-Antworten senden | `2095` (`PORT`) | `2096` |
| **Info-/Status-Server (HTTPS)** | Statusübersicht + statische Web-UI | `2098` | `2098` |

---

## 1. Input WebSocket (`wss://…:2095`)

Implementiert in `server/InputWS.js`. Eingehende Nachrichten sind **Plain-Text-Strings**.
Die Antwortlogik unterscheidet bewusst zwischen **gezielten Antworten** (nur an den
Anfrager) und **Broadcasts** (an alle verbundenen Clients).

### Antwort-Routing

| Eingabe | Verarbeitung | Antwort | Empfänger |
|---------|--------------|---------|-----------|
| `Ping` | Heartbeat, wird geloggt | `Ping` | **nur Anfrager** (gezielt) |
| `M114` | Statusabfrage | Positions-JSON (siehe unten) | **nur Anfrager** (gezielt) |
| G-Code (`G1`, `G90`, `G91`, `G28`, `M1`, `M92`, …) | Bewegung/Zustandsänderung | aktuelles Positions-JSON | **alle Clients** (Broadcast) |
| FCodes (`FShow`, `FList`, `FPoint`, `FPlus`, `FMinus`, `FFirst`, `FLast`, `FGoto`, `FLoad`, `FSave`, `FClear`, `FPlay`, `FStop`) | Weiterleitung → `appRobotFileservice` via `robot/FCodeClient.js`; Stepping-Ergebnis (Radian-Zeile) wird lokal ausgeführt | Daten-JSON oder Positions-JSON | **alle Clients** (Broadcast) |
| alles andere | – | Fehler-Envelope | **nur Anfrager** (gezielt) |

**Begründung der Trennung:** Eine Bewegung ändert die Roboterposition — das ist ein
Status-Update, das jeder Client (z. B. die Simulation) sehen soll → Broadcast. Eine
reine Abfrage (`Ping`, `M114`) ist eine direkte Antwort an den Anfrager → gezielt.
FCodes (Datei-Befehle) werden durch den Driver als Gateway weitergereicht —
Steuerungen brauchen keine direkte Verbindung zur `appRobotFileservice`.

### Positions-JSON (`M114` / Broadcast nach Bewegung)

```json
{
  "position":   { "x": 0, "y": 30, "z": 0, "a": 0, "b": 0, "c": 0 },
  "motorCounts":{ "x": 0, "y": 0,  "z": 0, "a": 0, "b": 0, "c": 0, "e": 0 }
}
```

- `position` — kartesische Pose + Orientierung (`a`/`b`/`c` = ϕ/ϴ/Ψ in rad).
- `motorCounts` — aktuelle Motor-/Achswerte.

### Fehler-Envelope (maschinenlesbar)

Bei unbekannter Eingabe oder Verarbeitungsfehler erhält **nur der Anfrager**:

```json
{ "type": "error", "code": "UNKNOWN_COMMAND", "message": "Unrecognized input", "input": "<original>" }
```

| `code` | Bedeutung |
|--------|-----------|
| `UNKNOWN_COMMAND` | Eingabe passt auf keinen bekannten Befehl |
| `GCODE_ERROR` | Fehler beim Parsen/Ausführen eines G-Code-Befehls |
| `FILE_ERROR` | Fehler bei einem FCode-Befehl (von `appRobotFileservice` weitergereicht) |

Erfolgs-Antworten (`Ping`, Positions-JSON) bleiben aus Kompatibilitätsgründen im
bisherigen Rohformat; das Envelope gilt nur für Fehler.

---

## 2. Info-/Status-Server (`https://…:2098`)

Implementiert in `server/InfoServer.js`. Selbstsigniertes Zertifikat.

### Statische Web-UI
`GET /` · `GET /app.js` · `GET /style.css` · `GET /allApps.css`

### `GET /api/status`

Liefert Verbindungs- und Health-Informationen als JSON:

```json
{
  "generatedAt": "2026-06-08T12:00:00.000Z",
  "health": { "ok": false, "connectedSenders": 1, "totalSenders": 3 },
  "clients": ["127.0.0.1"],
  "senders": [
    {
      "name": "Base",
      "state": "connected",
      "url": "fluidNcBase.local",
      "isTestMode": false,
      "error": null,
      "reconnectAttempt": 0,
      "reconnectTimer": false,
      "health": "ok",
      "reason": null
    }
  ],
  "lastCommands": ["2026-06-08T…: G1 X10 Y10"],
  "lastPings": ["2026-06-08T… 127.0.0.1 : Ping"]
}
```

- `health.ok` — `true`, wenn **alle** Sender verbunden sind.
- pro Sender: `state` ∈ `connected | connecting | reconnecting | disconnected`;
  `health` ∈ `ok | warning | disconnected`.

### `GET /api/position`

Liefert die aktuelle Roboterposition (gleiches Positions-JSON wie oben),
**unabhängig** von laufenden Senderverbindungen.

### Sonstige Pfade
`404 Not found`.