Claude API

2026-06-08 19:04:31 +02:00
parent 10d306b7d4
commit c777f871cd
12 changed files with 529 additions and 28 deletions
--- a/doc/API.md
+++ b/doc/API.md
@@ -0,0 +1,111 @@
+# 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) |
+| Datei-Befehle (`FShow`, `FList`, `FPoint`, `FPlus`, `FMinus`, `FLoad`, `FSave`, `FClear`, `M20/23/28/29`) | Datei-/Log-Verwaltung | Befehlsergebnis | **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.
+
+> **Hinweis:** Feinere Zielsteuerung der Datei-Befehle (z. B. `FShow` als
+> Anfrager-only-Antwort) sowie `FFirst`/`FLast` gehören zur Datei-Verwaltung in
+> **ToDo 4** und bleiben hier bewusst unverändert.
+
+### 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 Datei-Befehl |
+
+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`.