Interfaces¶
Everything a developer needs in order to program against uGo without asking anyone: the chassis below us, our own server, and the cloud above us. Three interfaces, one source, and every statement marked with where it comes from.
Language note
The pages under Interfaces are kept in German, unlike the rest of this portal. They are contract documents whose worth is the precision of measured facts, and a translation risks changing what was measured. They come from one source file — if the house decides this portal is English only, they are translated in a single pass.
The three layers¶
-
Quickstart
Zehn Minuten von „nichts" zu „der Roboter fährt" — anmelden, Zustand lesen, ein Ziel anfahren, und die vier Fallen, die uns Tage gekostet haben.
-
Fahrgestell
Karten, Kartenfahrten, Lage, Fahrt, Zonen, die Ladestation als Paar — und der WebSocket, der als einziger den Zustand liefert.
-
uGo server
Unsere eigene Schnittstelle unter
/api/**: Anmeldemodell, alle Routen, die beiden Durchleitungen und ihre Riegel. -
URG cloud (uSuite)
MQTT, Themenbaum je Gerät, das Job-Dokument Feld für Feld, Ausrollen in vier Stufen, Rückrollen, Anmeldestrecke.
-
Alle Dienste im Überblick
Welche Schnittstellen wir bereitstellen, wer mit wem spricht, wo der Vertrag liegt — und die eine Architekturregel, gegen die niemand neu anbinden sollte.
Drei Schnittstellen in einem Blatt: das Fahrgestell, unser eigener uGo-Server unter /api/** und die URG-Cloud über MQTT. Stand 20.08.2026 · für Entwickler, insbesondere für die Arbeit unterhalb der Naht.
Note
Wozu dieses Blatt. Es soll ausreichen, um ohne Rückfrage dagegen zu programmieren. Deshalb steht bei jeder Aussage, woher sie kommt: was am Gerät gemessen wurde, was aus einer Herstellerbeschreibung übernommen ist und was schlicht offen ist. Wo etwas offen ist, steht „offen" und der Grund — nicht eine plausible Zahl. Eine geratene Zahl sieht auf dem Bildschirm genauso aus wie eine gemessene, und man merkt den Unterschied erst am fahrenden Roboter.
Prüfstand aller Messungen: Gerät 8982504805371oD (uLog Deliver 80, Fahrgestellsoftware 2.12.28-pi64), 17.–20.08.2026. Wo eine Messung genannt ist, ist sie an diesem einen Gerät entstanden. Ob ein Wert eine Konstante der Baureihe ist, weiss niemand — dazu bräuchte es ein zweites Gerät.
Belegstufen¶
| Marke | Bedeutung | Wie damit umzugehen ist |
|---|---|---|
| BELEGT | Am Prüfgerät beobachtet, mit Datum. | Belastbar. Trotzdem: ein Gerät, eine Fassung. |
| HINWEIS | Aus dem Herstellerportal oder dessen Schnittstellenbeschreibung, nicht nachgemessen. | Vor dem Verlassen darauf am Gerät gegenprüfen. |
| VORSICHT | Plausibel, aber ohne Beleg. Im Quelltext als confidence: 'assumed'. |
Nicht in eine Entscheidung einbauen, die Bewegung auslöst. |
| OFFEN | Unbekannt. Wird bewusst nicht geraten. | Zahl durchreichen, Bedeutung nicht behaupten. |
Danger
DIE WICHTIGSTE WARNUNG DIESES BLATTES: das Fahrgestell rechnet Winkel uneinheitlich.
Dieselbe Grösse kommt je nach Weg in Grad oder im Bogenmass. Wer das verwechselt, bekommt keinen Fehler, sondern eine falsche Fahrt.
| Wo | Einheit | Beleg |
|---|---|---|
Thema /tracked_pose, Feld ori (WebSocket) |
Grad | BELEGT |
POST /chassis/pose, Feld ori |
Bogenmass | BELEGT — gesendet wurde 1.5708, danach meldete das Gerät 90° |
POST /chassis/moves, Feld target_ori |
Bogenmass | BELEGT — mit Grad kommt fail_reason 103 invalid_charge_dock und eine Ausrichtung wie 4927 (= 86 × 57,3) |
Zeichnungen (overlays), Feld yaw / iconYaw |
Grad | BELEGT, meist als Zeichenkette |
Im uGo-Code liegt die Umrechnung an genau zwei Stellen: degreesToRadians beim Schreiben, radiansToDegrees beim Lesen von target_ori (src/lib/adapter/chassis-adapter.ts). Das Modell führt intern Grad (yawDeg). Wer eine dritte Umrechnungsstelle einführt, baut die nächste Fehlerquelle.
Was ausdrücklich offen bleibt¶
| Frage | Warum offen | Wie sie zu schliessen ist |
|---|---|---|
regionType der Sperrzone |
keine Messung. Wird nicht geraten, weil eine falsch nummerierte Sperrzone richtig aussieht und der Roboter trotzdem hineinfährt | Am Gerät eine Sperrzone im Portal anlegen und die Zahl aus overlays ablesen |
| Die übrigen 23 Zonenarten | Namen bekannt, Zahlen nicht | dito, je Art einmal |
| Punktarten ohne Zahl (Empfang, Aufzug, Elektrische Tür, …) | Der Nummernraum hängt vom eingestellten Geschäftsszenario ab | Je Art einen Punkt im Portal anlegen und die Zahl ablesen |
| Typ 11 = „Delivery Point" | VORSICHT; beobachtet als Stationen A/B/C | Im Portal einen Punkt als „Delivery Point" anlegen und die Zahl vergleichen |
direction einer Fahrspur (beobachtet: 3) |
Einbahn vorwärts, rückwärts oder beidseitig — nicht belegt | Zwei Spuren mit verschiedenen Richtungen anlegen und vergleichen |
Feldname der Zonengeschwindigkeit im overlays |
Grenzen aus dem Portal belegt, Feldname nicht | Eine „Sloping Area" mit einem ungewöhnlichen Wert anlegen und im overlays danach suchen |
startType / endType eines Punktes |
Bedeutung unbekannt | offen |
iconYaw-Versatz von −82 |
reproduzierbar, aber unerklärt | Beim Hersteller nachfragen; wirkt offenbar nur auf die Darstellung |
| Ist 0,899 m eine Konstante der Baureihe? | Ein Paar, viermal dieselbe Messung | Eine zweite, andere Ladestation vermessen. Ergibt sie etwas anderes, wird daraus ein Feld je Standort |
PATCH /maps/<id> mit overlays |
nie an einem echten Gerät gemessen — weder für Punkte noch für Zonen | Am Prüfgerät durchspielen und dabei overlays_version und Inhalt vorher/nachher festhalten |
| Vergibt das Gerät eigene Kennungen für geschriebene Zeichnungen? | nicht geprüft | dito; solange über Kennung und Namen nachlesen |
| Pausieren eines Fahrauftrags | Ob {"state":"paused"} oder ein Dienst das kann, ist nicht belegt |
Am Gerät ausprobieren |
| Uhr und Zeitzone des Fahrgestells | Sechs naheliegende Pfade abgefragt, keiner passt | Beim Hersteller nachfragen, sonst über die Konsole des Fahrgestells stellen |
Ursache des Kartenverlusts bei restart_service |
Wirkung zweimal gemessen, Ursache nicht belegt | Gehört in den Vertrag mit dem Hersteller — sie betrifft die Cloud-Ablösung unmittelbar |
documentParameters bei eigenen Job-Vorlagen |
Die AWS-Beschreibung schränkt sie auf verwaltete Vorlagen ein; ohne Konto nicht prüfbar | Einen Job aus einer eigenen Vorlage anlegen und nachsehen, ob die Felder ersetzt sind. Bis dahin trägt der Zeiger den Fall |
| Schnittstelle des u-IoT-Moduls | Beschreibung steht aus | Sobald sie vorliegt, wird aus dem Rohtext-Gerüst eine gedeutete Fläche — vorher nicht |
Note
Zwei Regeln, die dieses Blatt am Leben halten.
Erstens: keine Aussage ohne Beleg. Wer hier etwas ergänzt, schreibt dazu, ob es gemessen, übernommen, vermutet oder offen ist — und bei einer Messung Datum und Gerät. Eine Zeile ohne Belegstufe ist in einem halben Jahr nicht mehr von einer Vermutung zu unterscheiden.
Zweitens: was hier steht, steht auch im Quelltext, und umgekehrt. Die Fundstellen sind in den Abschnitten genannt (src/lib/chassis/point-types.ts, src/lib/chassis/zone-types.ts, src/lib/server/zonen-zeichnungen.ts, src/lib/adapter/chassis-adapter.ts, terraform/iot-identitaet.tf, terraform/update-vorlagen/job-dokument.json.tftpl, dienste/anmeldung/index.mjs, geraet/lib/server/wolke.ts). Läuft eines von beiden weg, gilt das Gerät.
Every contract URG publishes¶
The table this page carried since stage 1. Three of its rows are now described in full on the pages above; the rest still wait for a generator that writes its specification to a file instead of only serving it at runtime.
| Contract | Kind | Source | Described |
|---|---|---|---|
| Chassis REST | REST | described today only through our own simulator | Fahrgestell — measured on device 8982504805371oD |
| uGo server | REST | tablet-ui/src/routes/api |
uGo-Server — all routes |
| URG cloud (uSuite) | MQTT / JSON | urg-cloud/terraform |
Cloud — topics, job document, rollout |
| uGo+ operator UI | OpenAPI 3 | ugo-plus/ugo.ui/ui |
not yet |
| Guest row | OpenAPI 3 | ugo-plus/ugo.ui/guestrow |
not yet |
| Lift control | OpenAPI 3 | site/elevator-control |
in outline, Dienste |
| Door control | OpenAPI 3 | accessibility/door-control |
in outline, Dienste |
| Multi-level movement | OpenAPI 3 | accessibility/multilevel-accessibility |
in outline, Dienste |
| Map sync between robots | REST | accessibility/door-control |
in outline, Dienste |
| Movement authority | REST | draft | in outline, Dienste |
| Voice assistant | OpenAPI 3 | site service | Voice |
| uGo+ device communication | gRPC / Protobuf | uGo.proto — six diverging copies, no common source |
not yet |
| u-IoT | REST | site/iot-integration |
partly, in uGo-Server |
| uMe gateway | WebSocket / JSON | w.Saeidi/ume-sdk |
not yet |