4 · Welche Schnittstellen wir bereitstellen

Ein Blatt für die Frage, die am Anfang jeder Anbindung steht: welche Dienste gibt es, wer spricht mit wem, und wo steht der Vertrag dazu. Die drei ausführlichen Blätter — Fahrgestell, uGo-Server, Cloud — beschreiben je eine Schnittstelle im Einzelnen. Dieses hier ordnet sie ein und nennt die übrigen.

4.1 Die Landkarte in einem Satz je Ebene

Ebene	Wer spricht	Wohin	Träger
Unten	uGo-Server, Zugangsdienste	Fahrgestell	HTTP und WebSocket, ohne Anmeldung — deshalb liegt das Fahrgestell in einem eigenen Netzabschnitt
In der Mitte	Tablett, Kiosk, Zweitanzeige	uGo-Server, /api/**	HTTP, Sitzungskeks, zwei Rollen
Seitwärts	Roboter untereinander	Roboter	UDP-Rundsendung, alle zwei Sekunden, je Standort signiert
Zum Haus	uGo-Server, Zugangsdienste	Tür, Aufzug, u-IoT	HTTP, je Standort eine Adresse
Nach oben	Gateway	AWS IoT Core	MQTT über TLS, Zertifikat je Gerät, nur ausgehend

4.2 Die Dienste im Einzelnen

Dienst	Grundpfad	Wofür	Anmeldung	Vertrag
uGo-Server	/api/**	Bedienoberfläche, Touren, Regeln, Karten, Zonen, Fahrtenbuch, Flotte, Cloud-Anbindung	Sitzungskeks, Rollen Bediener und Techniker; einige Routen bewusst ohne	uGo-Server, alle Routen
uGo-Server, Zweitsockel	dieselben Pfade, nur lesend	Fernwartung. Bindet an 127.0.0.1, GET/HEAD, Erlaubnisliste	keine — und ohne Sitzung antworten die geschützten Routen mit 401	Fernwartung
Durchleitung Fahrgestell	/api/chassis/**	Der Weg zum Fahrgestell, Pfad und Rumpf unverändert	teils	Fahrgestell
Durchleitung u-IoT	/api/uiot/**	Nur lesend, gesperrte Pfade, nur mit Anmeldung	ja	uGo-Server, 2.4
Durchleitung Sprachdienst	/api/chatbot/**	Kontext, Befehle, Zieladresse. Die Sprachstrecke selbst ist gesperrt	Techniker	Sprache
Türsteuerung	eigener Dienst	Erkennt Türen aus den Zeichnungen der Karte und entscheidet aus der Geometrie, wann eine öffnet	OFFEN	OpenAPI zur Laufzeit unter /api-docs
Aufzug und Ebenenwechsel	eigener Dienst	Warteposition, Fahrtanforderung, Kartenwechsel, Neulokalisierung, Fortsetzen — als eine Kette	OFFEN	OpenAPI zur Laufzeit
Kartenabgleich	POST /mapSync/sync-now	Eine Karte von einem Roboter auf einen anderen bringen und dort neu lokalisieren, in einem Aufruf	OFFEN	OpenAPI zur Laufzeit
Bewegungshoheit	POST /…/desired-moves, …/ownership, …/moves/:id/pause, …/resume	Absichten statt Fahrbefehle. Siehe unten	OFFEN	Entwurf
Sprachdienst	/api/chatbot/*, /api/intercommunicator/*, /api/wake-word/*	Wachwort, Kontext, Phrasenbefehle, Sprachstrecke	OFFEN	/docs-json zur Laufzeit
u-IoT-Modul	REST	Digitale Ein- und Ausgänge, Ruftaster, Aktionsregeln	ohne — deshalb nur im geschützten Netz	Beschreibung steht aus
Anmeldedienst der Cloud	POST /anmeldung	Genau ein Pfad: aus einer Zertifikatsanfrage wird ein Gerätezertifikat	Beitrittscode, einmalig	Cloud, 3.8
Cloud, Themenbaum	urg/<umgebung>/geraet/<seriennummer>/…	Zustand, Kennzahlen, Störung, Karte, Update, Wartungssitzung	Zertifikat je Gerät	Cloud, 3.2

Warum bei fünf Zeilen „offen" steht, wo eine Anmeldung stehen müsste. Diese Dienste laufen heute im geschützten Netzabschnitt und prüfen keine Kennung. Das ist tragbar, solange der Abschnitt trägt, und es ist der Punkt, an dem die Bewegungshoheit zuerst einen Schlüssel braucht: sie wird das eine lohnende Ziel, sobald alle Fahrbefehle durch sie laufen.

4.3 Die Regel, die über allen steht: ein Schreiber

Ein Fahrgestell dieser Klasse nimmt einen neuen Fahrbefehl an, indem es den laufenden ersetzt — still, ohne Warteschlange und ohne Begriff von Eigentum. Zwei Bauteile, die beide das Richtige wollen, unterbrechen sich deshalb gegenseitig.

Die Antwort darauf ist eine Architekturregel und kein Feld in einer Konfiguration:

Genau ein Bauteil je Roboter setzt Fahrbefehle ab. Alle anderen reichen eine Absicht ein und lassen sich sagen, wann sie fahren dürfen. Lesende Verbindungen bleiben unmittelbar.

Für einen Partner, der gegen diese Plattform baut, hat das eine unmittelbare Folge: eine Anbindung, die selbst POST auf das Fahrgestell schickt, ist heute möglich und wird morgen im Weg stehen. Wer neu anbindet, reicht Absichten ein.

Zwei Verben, die dazugehören und die es ohne diese Regel nicht geben kann:

Verb	Was es tut
pause	Hält einen Auftrag, ohne ihn abzubrechen. Jeder Anhaltende gibt seinen eigenen Halt wieder frei; mehrere Halte schliessen sich nicht aus. Der Auftrag behält seinen Eigentümer und muss danach nicht neu vergeben werden
resume	Gibt den eigenen Halt frei. Dass danach noch jemand hält, ist kein Fehler, sondern die Auskunft, dass die Fahrt noch aus einem anderen Grund steht

Der Unterschied zum bisherigen Weg ist der ganze Punkt: ein Abbruch mit anschliessender Neuvergabe sieht für den Auftraggeber aus wie ein Fehlschlag. Ein Halt sieht aus wie eine Wartezeit — und genau das ist eine geschlossene Tür.

4.4 Karten und ihre Identität

Zwei Roboter, die über dieselbe Karte reden, brauchen einen gemeinsamen Namen dafür. Der örtliche Zähler taugt nicht: dieselbe Karte, auf zwei Geräte kopiert, bekommt dort verschiedene Nummern, und auch die vom Gerät vergebene Kennung wird beim Kopieren neu vergeben. Nur der Name überlebt eine Übertragung, und ein Name ist kein Schlüssel.

Woran ein Dienst deshalb erkennt, dass sich die Karte geändert hat:

Weg	Wie	Bewertung
Regelmässig GET /chassis/current-map fragen	einfach	Kostet einen Abruf im Takt und merkt eine Änderung erst beim nächsten
Das Thema /map/info auf dem WebSocket bestellen	Das Thema ist gehalten: der aktuelle Stand kommt sofort beim Verbinden und danach bei jeder Änderung	Der bessere Weg. Kein Abfragetakt, keine Verzögerung

Erkannt wird eine Änderung am Paar (Kennung, Zeichnungsfassung) — eine andere Karte oder dieselbe Karte mit neuen Zeichnungen. Und die Regel, die dazugehört: solange die Karte nicht bekannt ist, wird nichts ausgelöst. Auf der Geometrie eines anderen Stockwerks zu handeln ist schlimmer, als gar nicht zu handeln.

4.5 Was maschinenlesbar vorliegt und was nicht

Vertrag	Art	Zustand
uGo-Server	REST	Vollständig beschrieben, siehe uGo-Server. Eine erzeugte Datei gibt es nicht
Fahrgestell	REST	Beschrieben aus Messung. Der Hersteller liefert keine Datei, die wir weitergeben dürften
Cloud	MQTT/JSON	Beschrieben, siehe Cloud
Tür, Aufzug, Ebenenwechsel, Kartenabgleich	OpenAPI 3	Wird zur Laufzeit ausgeliefert, aber nicht in eine Datei geschrieben — deshalb steht sie hier nicht
Sprachdienst	OpenAPI 3	dito, unter /docs-json
u-IoT	REST	OFFEN — Beschreibung steht aus

Der eine Schritt, der diese Tabelle grün macht: jeder Dienst, der seine Beschreibung schon zur Laufzeit erzeugt, schreibt sie zusätzlich beim Bauen in eine Datei und legt sie neben das Ergebnis. Dann kann dieses Portal sie einbinden, statt sie zu beschreiben.