3 · URG-Cloud¶
Für IT, Techniker und Integrationspartner
Technische Referenz für IT-Abteilungen, URG-Techniker und geschulte Partner. Keine Bedienungsanleitung für Endanwender.
Danger
Die Zusage, an der sich jede Zeile dieses Teils messen lassen muss: Kein Fahrbefehl aus der Cloud. Nie. Aus dieser Richtung nimmt das Gerät genau zwei Dinge an — eine fassungsfreigabe und eine sperre. Alles andere wird verworfen und protokolliert, auch aus einer gültigen Verbindung mit gültigem Zertifikat.
Die Sperre ist die einzige erlaubte Richtung nach unten, weil sie nur wegnimmt: sie hält an, sie fährt nicht. Diese Eigenschaft hat nur, wer sie nirgends aufweicht — nicht „nur für die Fernwartung", nicht „nur im Prüfstand". Wer im Empfang einen dritten Fall hinzufügt, hebt die Zusage auf, mit der dieses Gerät verkauft wird.
Zweiter Grundsatz: die Cloud ist ein Zusatz, nie eine Voraussetzung. Ein Roboter ohne Internet fährt in vollem Funktionsumfang weiter, puffert seine Meldungen und reicht sie nach.
3.1 Verbindung¶
| Punkt | Wert |
|---|---|
| Träger | AWS IoT Core über MQTT, TLS beidseitig, X.509 je Gerät |
clientId |
= Thing-Name = Seriennummer des Fahrgestells |
| Anschluss | 8883; bei einer Firewall, die das sperrt, 443 mit der von AWS verlangten ALPN-Kennung x-amzn-mqtt-ca |
| QoS | 1 in beide Richtungen |
| Wurzelzertifikat | ohne eigene Datei die Wurzeln von Node (Amazon Root CA 1 ist darin). rejectUnauthorized bleibt in jedem Fall an |
| Wiederverbinden | selbst gesteuert: 1 s, 5 s, 15 s, 60 s, 300 s, jeweils mit ±20 % Streuung — mehrere Roboter am selben WLAN dürfen nach einer Störung nicht in derselben Sekunde anklopfen |
| Puffer | Meldungen, die nicht hinausgehen, landen in daten/wolke-puffer.jsonl und werden beim nächsten Verbinden in der ursprünglichen Reihenfolge nachgereicht. Bei Überlauf (5000) fliegt die älteste Kennzahl, nie die älteste Störung |
3.2 Themenbaum je Gerät¶
Alles, was ein Roboter sagen oder hören darf, liegt unterhalb eines einzigen Pfades:
urg/<umgebung>/geraet/<seriennummer>/<art>
<umgebung> ist pruef oder betrieb. <seriennummer> ist der Thing-Name, und den setzt AWS über die Richtlinienvariable ${iot:Connection.Thing.ThingName} durch. Was im Pfad steht, hat AWS erzwungen; was im Rumpf steht, hat der Absender selbst geschrieben und ist eine Behauptung. Alle Regeln in der Cloud holen die Seriennummer deshalb mit topic(4) aus dem Pfad und niemals aus dem Rumpf.
| Richtung | Thema | Inhalt | Was in der Cloud damit geschieht |
|---|---|---|---|
| Gerät → Cloud | …/zustand |
Zustand, Fassungen | Lambda schreibt die Zeile des Gerätes fort (nur UpdateItem, kein Anlegen) |
| Gerät → Cloud | …/kennzahlen |
viel, gleichförmig | Firehose, spätere Auswertung |
| Gerät → Cloud | …/stoerung |
Störung | SNS — ein Mensch soll es merken |
| Gerät → Cloud | …/karte |
{vorgang:"gesichert", archivId, name, bytes, pruefsumme} |
Vermerk |
| Gerät → Cloud | …/karte/anfrage |
Steckbrief einer Kartensicherung, siehe 3.7 | Lambda antwortet mit vorsignierten Ablageadressen |
| Gerät → Cloud | …/update/rueckroll |
Rückrollmeldung, siehe 3.6 | Lambda zählt Geräte und sperrt notfalls die Fassung |
| Cloud → Gerät | …/befehl |
nur fassungsfreigabe und sperre |
alles andere verwirft das Gerät |
| Cloud → Gerät | …/+/antwort |
Antwort auf eine eigene Frage, zugeordnet über anfrageId |
Antwort ohne offene Frage wird verworfen |
| beidseitig | $aws/things/<name>/jobs/… |
IoT Jobs; bestellt wird notify-next |
siehe 3.5 |
| beidseitig | $aws/things/<name>/shadow/… |
Geräteschatten | trägt u. a. die laufende Fassung — sie passt nicht in die drei durchsuchbaren Merkmale des Thing-Typs |
Umschlag jeder Meldung nach oben: {art, zeit, inhalt}. zeit ist die Uhr des Roboters; die Cloud übernimmt sie bewusst nicht als Empfangszeit — ein Gerät puffert bei Netzausfall und reicht nach, und seine Uhr kann danebenliegen. Wann etwas gehört wurde, weiss nur die Cloud; wann es gemessen wurde, steht im Inhalt.
3.3 Was das Gerät darf — aus der IoT-Richtlinie¶
| Recht | Worauf | Warum genau so |
|---|---|---|
iot:Connect |
client/${iot:Connection.Thing.ThingName} |
Die wichtigste Zeile der ganzen Richtlinie. Ohne sie dürfte jedes gültige Gerätezertifikat unter jeder clientId verbinden — alle Roboter teilen sich dieselbe Richtlinie. Ein einziges übernommenes Gerät (und ein Roboter steht in einem Krankenhausflur, nicht in einem Rechenzentrum) könnte sich dann als jeder andere ausgeben: fremde Zustandsmeldungen fälschen, fremde Update-Aufträge abholen, eine fremde Verbindung abwerfen (MQTT trennt bei gleicher clientId den älteren Teilnehmer). Die gesamte Rechtetrennung fällt auf diese eine Bindung zurück, weil dieselbe Variable auch in allen Themenpfaden steckt. Nebenwirkung, die gewollt ist: die Variable ist nur belegt, wenn das Zertifikat an einem Ding hängt — ein Zertifikat ohne Registrierung kann sich gar nicht verbinden |
iot:Publish |
urg/<umgebung>/geraet/<name>/*, $aws/things/<name>/jobs/*, $aws/things/<name>/shadow/* |
Kein Platzhalter weiter oben im Baum, also kein Weg in den Zweig eines anderen Roboters oder in einen Verwaltungspfad. Die feste Umgebung schliesst zusätzlich aus, dass ein Prüfgerät in die Betriebsumgebung hineinredet |
iot:Subscribe |
dieselben Pfade als topicfilter/… |
Das Gerät bestellt örtlich mit #; in der Richtlinie steht *, weil ein ARN keine MQTT-Platzhalter kennt. Wichtig ist, was davor steht: der Pfad ist bis zum Gerätenamen fest |
iot:Receive |
dieselben Pfade | AWS prüft dieses Recht beim Zustellen jeder einzelnen Nachricht, nicht nur beim Bestellen — die Erlaubnis zum Bestellen reicht nicht |
iot:DescribeJobExecution, GetPendingJobExecutions, StartNextPendingJobExecution, UpdateJobExecution |
thing/<name> und job/* |
Für den HTTP-Weg der Job-Schnittstelle, wenn das Gerät Fortschritt meldet. job/* ist nötig, weil die Auftragskennung erst zur Laufzeit entsteht; die Bindung hält über thing/ |
Nicht in der Richtlinie und mit Absicht: Zertifikate. Ein Zertifikat gehört genau einem Gerät und entsteht bei dessen Erstanmeldung, nicht beim Einrichten der Cloud. Ebenso hängt der Anmeldedienst das Zertifikat an Richtlinie und Ding — sonst müsste für jeden neuen Roboter die Cloud-Einrichtung geändert werden, und ein Techniker vor Ort könnte kein Gerät in Betrieb nehmen.
3.4 Das Job-Dokument, Feld für Feld¶
Der Vertrag zwischen Cloud und Gateway. Er entsteht aus einer festen Job-Vorlage der Cloud und wird vom Aktualisierungsdienst des Gateways gelesen. Feste Werte stehen in der Vorlage, ${aws:iot:parameter:…} setzt derjenige, der aus der Vorlage einen Job erzeugt.
| Feld | Beispiel | Bedeutung / Regel |
|---|---|---|
dokument_fassung |
1 |
ändert sich nur, wenn Felder wegfallen |
vorhaben |
"ugo-update" |
Erkennungsmarke; alles andere ignoriert das Gateway |
stufe |
"pruefgeraete" |
pruefgeraete | vorhut | zehntel | flotte, kommt aus der Vorlage |
schicht |
"server" |
Nur server oder kiosk. Alles andere lehnt das Gateway ab — das ist die Stelle, an der ein Tippfehler in einem Ausrollbefehl aufhört, gefährlich zu sein. Das Fahrgestell wird von diesem Weg nie angefasst. |
fassung |
"2026.08.19-3" |
was gespielt wird; Schlüssel der Tabelle fassungen |
fassung_vorher_erwartet |
"2026.08.12-1" |
leer = beliebig. Sonst: passt der Stand nicht, wird nicht gespielt |
paket.adresse |
vorsigniert, kurzlebig | aus dem Platzhalter ${aws:iot:s3-presigned-url:…} der Job-Vorlage, beim Anlegen des Jobs ersetzt; die Gültigkeit ist eine feste Einstellung der Cloud |
paket.sha256 |
Prüfsumme des tar.zst |
wird vor dem Entpacken geprüft |
paket.signatur_b64 |
ECDSA-P256-Signatur | über die 32 Byte des SHA-256, nicht über das Paket. KMS liefert sie DER-kodiert — genau die Form, die openssl erwartet, also kein Umformschritt dazwischen |
paket.signatur_verfahren |
"ECDSA_SHA_256" |
— |
paket.signatur_schluessel |
alias/urg-<umgebung>-update-signatur |
Der öffentliche Teil liegt auf dem Gerät unter /etc/ugo/paket-signatur.pub (rund 100 Byte) und braucht danach nichts mehr — keine Kette, keine Uhr, kein Netz. Der Preis dieser Wahl: kein Widerruf, bewusst genommen |
paket.groesse_bytes |
Zahl als Zeichenkette | Vorabprüfung gegen freien Plattenplatz |
zeiger.dokument zeiger.paket |
vorsigniert, feste Schlüssel pakete/zeiger/<stufe>.json bzw. .tar.zst |
Zweiter Weg, siehe unten |
sperren.nicht_waehrend_fahrt |
true |
Ein Roboter, der gerade einen Auftrag fährt, wird nicht neu gestartet. Auch nicht „kurz" |
sperren.mindest_akku_prozent |
40 |
Das Gateway rechnet mit max(Dokument, Gerätevorgabe) — das Dokument darf strenger sein, nie lockerer |
sperren.nur_im_wartungsfenster |
true |
Fenster je Kunde in /etc/ugo/wartungsfenster.conf. Steht dort keins, wird gar nicht aktualisiert — kein Vorgabewert, keine Kulanz. Ein Fenster ist eine Zusage, die ein Mensch dem Kunden gegeben hat |
gesundheit.frist_sekunden |
60 |
danach rollt das Gerät von allein zurück |
gesundheit.pfad / .port |
"/" / 5173 |
Gesundheitsprüfung nach dem Umschalten |
rueckrollen.erlaubt |
true |
— |
rueckrollen.melde_thema |
urg/<umgebung>/geraet/{seriennummer}/update/rueckroll |
siehe 3.6 |
Die drei Sperren stehen im Dokument, sind aber keine Bitte. Das Gerät prüft sie selbst und meldet REJECTED mit Grund, wenn eine greift.
Warning
Warum dieselben Angaben zweimal im Dokument stehen. Fassung, Prüfsumme und Signatur ändern sich mit jeder Freigabe; eine Job-Vorlage ist dagegen fest. AWS füllt ${aws:iot:parameter:…} beim Anlegen eines Jobs über --document-parameters. Ungeprüft ist, ob AWS das auch für eigene (nicht AWS-verwaltete) Vorlagen zulässt — die Beschreibung von CreateJob schränkt documentParameters auf verwaltete Vorlagen ein, und ohne Konto lässt sich das nicht ausprobieren. Deshalb trägt das Dokument beides, und das Gerät nimmt, was da ist:
- Parameter — der kurze Weg, wenn AWS ihn zulässt.
- Zeiger — sind die Felder unersetzt geblieben, lädt das Gerät
zeiger.dokumentund nimmt die Angaben von dort.
Der Zeiger ist kein Vertrauensproblem: das Gerät glaubt ihm nur, was die Signatur trägt. Wer den Zeiger austauscht, ohne den Signaturschlüssel zu haben, erreicht genau eine Zeile im Protokoll (signatur-ungueltig).
3.5 Ausrollen in vier Stufen¶
| Stufe | Vorlage | Ziel | Wartezeit davor |
|---|---|---|---|
| 1 Prüffeld | update_stufe1_pruefgeraete |
Dinggruppe urg-<umgebung>-pruefgeraete — hier stehen die Prüfgeräte der URG |
— |
| 2 Vorhut | update_stufe2_vorhut |
ein einzelnes abgesprochenes Kundengerät | 48 h |
| 3 Zehntel | update_stufe3_zehntel |
von Hand zusammengestellte Liste über mehrere Kunden — bewusst keine feste Gruppe | 72 h |
| 4 Flotte | update_stufe4_flotte |
Dinggruppe urg-<umgebung> |
eine Woche |
Beim Einrichten der Cloud entstehen nur die Vorlagen. Den Job selbst — und damit das Ziel — legt ein Mensch einzeln an. Das ist Absicht: „auf welche Geräte" soll nie ein Nebeneffekt sein. Die Wartezeiten erzwingt keine Automatik; sie entstehen dadurch, dass ein Mensch den nächsten Job anlegt.
Die Job-Kennung muss mit urg-<umgebung>-update- beginnen: die Notbrems-Lambda bricht nur Jobs mit diesem Präfix ab, und ihre Rolle darf auch nur diese anfassen.
Warum IoT Jobs und nicht ein eigener Weg: der Roboter holt, niemand drückt. Kein offener Port beim Kunden. Ein Gerät, das eine Woche aus war, bekommt seinen Job beim nächsten Verbinden — ohne dass irgendwo von Hand eine Liste „noch offen" geführt wird.
3.6 Rückrollen¶
Kommt der Roboter nach dem Umschalten nicht binnen der Frist gesund hoch, hängt er den Verweis zurück, startet neu und meldet auf urg/<umgebung>/geraet/<seriennummer>/update/rueckroll:
{ "fassung": "2026.08.19-3", "schicht": "server", "grund": "gesundheit", "job_id": "urg-pruef-update-stufe1-…", "zeitpunkt": "…" }
Die Lambda trägt die Seriennummer in eine Menge ein. Ab drei verschiedenen Geräten wird gesperrt = true auf dem Posten (fassung + schicht) gesetzt und die laufenden Jobs dieser Fassung werden abgebrochen. Verschiedene Geräte, nicht drei Meldungen — ein Gerät in einer Schleife ist ein Gerätefehler, kein Fassungsfehler.
3.7 Kartensicherung — der Umweg über eine vorsignierte Adresse¶
Warum ein Umweg: MQTT trägt höchstens 128 KB je Nachricht; eine Carto-Karte eines Krankenhausflurs liegt darüber. Stückeln hiesse, eine eigene Wiederzusammensetzung samt Lücken- und Reihenfolgeproblem zu bauen — für eine Verbindung, die in einem Krankenhaus regelmässig abreisst.
- Gerät →
…/karte/anfrage: nur der Steckbrief —{vorgang:"ablageadressen", archivId, name, pruefsumme, dateien:[{name, bytes}], anfrageId}. Das ist klein und passt immer. - Lambda legt eine vorläufige Zeile an („erwartet") und antwortet auf
…/karte/antwortmit je einer vorsignierten PUT-Adresse, 15 Minuten gültig. Erlaubt sind genau drei Dateinamen:karte.pbstream,raster.png,beschreibung.json. Eine vorsignierte Adresse ist ein Schreibrecht — wer den Dateinamen bestimmen dürfte, bestimmte den Ort im Eimer. - Gerät lädt per HTTPS unmittelbar nach S3,
beschreibung.jsonzuletzt. Reisst die Verbindung ab, wird wiederholt; die Schlüssel bleiben dieselben. - S3 meldet die eingetroffene
beschreibung.jsonzurück; erst dieser Schritt setzt die Zeile auf „gesichert".
Warum die Beschreibung der Auslöser ist und nicht die Carto-Karte: sie ist die Marke für einen vollständigen Satz. Bricht es vorher ab, liegt oben Bruchstückhaftes ohne Beschreibung — sichtbar unvollständig statt scheinbar heil.
Unverändert Gesichertes wird übersprungen (Vergleich über die Prüfsumme). Das ist kein Geiz: manche Häuser hängen den Roboter an einen Mobilfunkstick.
3.7.1 Karten verteilen — Auftrag an ein anderes Gerät¶
Stand 08.11.2026. Bedienung in der Konsole: Karten an andere Roboter verteilen.
Eine gesicherte Karte (3.7) lässt sich als Auftrag an andere Geräte desselben Knotens geben. Die Cloud schickt dabei nichts nach unten und legt keinen IoT-Job an: das Zielgerät holt den Auftrag an seiner Ladepause selbst ab, über denselben Kanal wie 3.7 (Frage auf …/karte/anfrage, Antwort auf …/karte/antwort, zugeordnet über anfrageId; die Seriennummer kommt nur aus dem Themenpfad). Der Auftrag ist ein Import in das Kartenarchiv des Geräts — aktivieren ist immer false. Ab uGo-Dienst 1.0.37 aktiviert das Gerät eine so importierte Karte beim nächsten Laden selbst (an der Ladestation, ohne Auftrag, mit Fahrsperre während des Wechsels, außer im Mehretagenbetrieb); aktivieren: false verhindert das nicht. Die Cloud setzt nie aktiv.
Route der Verwaltung: POST /geraet/{seriennummer}/karte/verteilen — {seriennummer} ist die Quelle. Verteilen dürfen Service und der Verwalter des Kunden; eine Rolle, die nur ansieht, erhält 403 (kv.rolle). Seit 12.11.2026 gilt das auch für den Vertrieb: 403 kv.rolle („Diese Rolle darf keine Kartensicherung verteilen.“) auf allen Verteilwegen — ein Ziel, mehrere Ziele, andere Baureihe, Zurückspielen auf das eigene Gerät —, als erste Prüfung, bevor eine Adresse, ein Auftrag, ein Protokolleintrag oder ein IoT-Job entsteht. Siehe Rechte.
| Feld | Bedeutung |
|---|---|
ziel |
eine Seriennummer (ein Ziel) |
ziele |
alternativ eine Liste mit 1 bis 20 Seriennummern; doppelte Einträge zählen einmal, mehr als 20 ergibt 400 (kv.zuVieleZiele) |
kartenname |
der gesicherte Stand der Quelle |
anfrage |
bei ziele: Kennung der Anfrage (8 bis 64 Zeichen A-Za-z0-9_-); dieselbe Kennung ein zweites Mal ergibt 409 (kv.verteilungDoppelt) |
andereBaureiheBestaetigt |
seit 08.11.2026, siehe 3.7.2 |
Je angenommenem Ziel entsteht ein eigener Auftrag mit eigener Protokollzeile. Bei ziele verwirft ein abgelehntes Ziel die anderen nicht; die Antwort nennt das Ergebnis je Ziel in ergebnisse.
GET /geraet/{seriennummer}/karten liefert die wählbaren Ziele (ziele), die Geräte desselben Knotens, die nicht Ziel sein können, mit Grund (ausgeschlossen) und für Service und Verwalter die letzten Verteilungen mit ihrem Stand je Ziel (vorbereitet, abgeholt, importiert, abgelehnt, aktiviert-am-geraet). „aktiviert am Gerät“ steht dort nur, wenn das Gerät es selbst gemeldet hat. Name und Kennzeichen der Stände vom Gerät: 3.7.3.
3.7.2 Karten über Baureihen hinweg verteilen¶
Stand 09.11.2026. Verfügbar seit 08.11.2026.
Ziel einer Verteilung kann jedes Gerät desselben Knotens sein, das in Betrieb ist und zur fahrenden Familie mit gleichem Kartenformat gehört: typ uGo, uServe oder uLog. Innerhalb derselben Baureihe gilt wie bisher keine weitere Bedingung. Gesperrt bleiben Humanoid, Anlage, vorerfasste Geräte, Geräte außer Betrieb, ein anderer Knoten, ein leerer typ und Baureihen außerhalb der Familie (409, kv.andereBaureihe). Zielliste und Prüfung beim Absenden folgen derselben Regel: ein angebotenes Ziel wird mit Bestätigung angenommen.
| Feld / Antwort | Bedeutung |
|---|---|
ziele[].andereBaureihe (GET …/karten) |
true, wenn das Ziel eine andere Baureihe als die Quelle ist; die Konsole kennzeichnet es („andere Baureihe: uServe“) |
andereBaureiheBestaetigt (POST …/karte/verteilen) |
genau true (kein "ja", keine 1) ist Pflicht, sobald ein Ziel eine andere Baureihe ist; bei ziele gilt es für die ganze Verteilung |
409 kv.andereBaureiheUnbestaetigt |
Ziel anderer Baureihe ohne Bestätigung; bei ziele je Ziel in ergebnisse, die übrigen Ziele bleiben |
| Auftragszeile | bei anderer Baureihe zusätzlich andereBaureihe, quellTyp, andereBaureiheBestaetigtVon, andereBaureiheBestaetigtAm; die Protokollzeile nennt beides |
In der Konsole erscheint die Bestätigung als Pflichthäkchen „Wege, Engstellen und Zonen sind für diese Baureihe vor Ort geprüft.“; bis dahin bleibt der Knopf gesperrt. Grund: Abmessungen, Fahrwege, Zonen und Ladestation unterscheiden sich je Baureihe.
Das Gerät prüft beim Import keine Baureihe
Die Prüfung in der Cloud ist die einzige technische Sperre; maßgeblich ist die Bestätigung vor Ort durch den Techniker. Ein Aufruf mit andereBaureiheBestaetigt: true gilt als diese Bestätigung und wird mit Zugang und Zeit vermerkt. Aktiviert wird weiterhin nur am Gerät.
3.7.3 Name statt Kennung, Sperre der Testkarte¶
Stand 09.11.2026. Gebaut, noch nicht ausgerollt; wirksam mit dem nächsten Update der uSuite (Verwaltung und Konsole). Bedienung: Kartennamen und Testkarten.
Ein Stand „vom Gerät“ trägt in der Ablage nur seine Archivkennung (UUID). Die Testkarte einer
Messung am Gerät (Kartenname USU36-Test) kann über „Alle Karten sichern“, Einzelsichern oder die
Wiederherstellung eines Speicherpunkts dorthin gelangen. Ein Zielgerät legt einen gelieferten Stand
ab und aktiviert ihn beim nächsten Laden; aktivieren: false im Auftrag verhindert das nicht.
Deshalb sperrt die Cloud diesen Stand.
| Feld / Antwort | Bedeutung |
|---|---|
sicherungen[].anzeigename (GET …/karten) |
jetzt auch für herkunft: geraet: der Name, den das Gerät beim Sichern gemeldet hat. Gelesen wird er für die neuesten Stände, höchstens 20 je Abruf; dahinter und ohne gemeldeten Namen fehlt das Feld, die Konsole zeigt dann die Kennung wie bisher. Die Konsole zeigt den Namen, die Kennung klein darunter. |
sicherungen[].testkarte (GET …/karten) |
true für die Testkarte; die Konsole zeigt „Testkarte – nicht verteilbar“ und bietet für diesen Stand weder Auswahl noch Zurückspielen an. |
409 kv.testkarte (POST …/karte/verteilen) |
Der gewählte Stand ist die Testkarte — bei ziel, bei ziele (ganze Verteilung, kein Auftrag) und beim Zurückspielen (ziel = Quelle). Der Körper trägt wie jede Absage fehler und hinweis: „Dieser Stand ist eine Testkarte und wird nicht verteilt oder zurückgespielt.“ / „Testkarten gehören zu einer Messung am Gerät und nie in das Kartenarchiv eines Roboters. Ein Gerät würde sie beim nächsten Laden aktivieren. Bitte einen anderen Stand wählen.“ |
Erkannt wird am Namen mit demselben Vergleich wie am Gerät: Leerzeichen am Rand und Groß- und
Kleinschreibung zählen nicht (USU36-Test, usu36-test und USU36-Test mit Leerzeichen am Ende
sind gesperrt, USU36-Test-2 nicht). Vorbereitet ist zusätzlich ein künftiges Feld
testkarte: true in der Beschreibung des Stands; heute setzt es niemand. Fehlt der Name (älterer
Stand ohne gemeldeten Namen), wird nicht gesperrt. Beim Verteilen wird genau der gewählte Stand
gelesen; die Sperre greift also unabhängig von seiner Stelle in der Liste.
3.7.4 Punkte und Zonen bearbeiten — neuer Stand aus einer Kopie¶
Stand 10.11.2026 (USU-114, USU-111 Stufe B). Ab Freischaltung in Produktion und Testumgebung verfügbar; ohne Freischaltung gibt es Route und Angebot nicht. Bedienung: Punkte und Zonen bearbeiten.
Der Editor ändert Punkte und Zonen eines gesicherten Stands (3.7) auf einer Kopie und legt daraus einen neuen Stand an. Der Ausgangsstand bleibt unverändert. Die Cloud schickt dabei nichts an ein Gerät, legt keinen Auftrag und keinen IoT-Job an und setzt nie aktiv eine Karte; verteilt wird über den vorhandenen Weg (3.7.1), aktiviert nur am Gerät.
Route der Verwaltung: POST /geraet/{seriennummer}/karte/bearbeiten — {seriennummer} ist
das Gerät, dessen Stand bearbeitet wird. Erlaubt für Zugänge mit dem Hochladerecht (Service und
Verwalter des Kunden); kein neues Recht. Ein Zugang, der nur ansieht, erhält 403. Seit
12.11.2026 sind Lesen und Schreiben getrennt: der Vertrieb darf lesen (lesen: true), aber nicht
speichern — siehe Rechte: Lesen und Schreiben.
| Feld / Antwort | Bedeutung |
|---|---|
kartenname |
der gesicherte Ausgangsstand |
lesen: true |
liest nur: 200 mit merkmale (Punkte, Ladestationen, Zonen des Stands) für die Tabelle der Konsole; nichts wird angelegt. Seit USU-115 zusätzlich Zeichnungstext, Rahmen und Bildadresse (3.7.5) |
aenderungen |
Liste mit höchstens 200 Einträgen: punkt-verschieben (id, x, y, grad), punkt-anlegen (name, punktart 11 Station, 7 Tür, 10 Wartepunkt, x, y, grad; Ladestation 9 seit USU-115 abgewiesen), zone-verschieben (id, ecken), zone-anlegen (name, ecken, Langsamzone; weitere Arten und Änderungsarten in 3.7.5) |
201 ke.angelegt |
neuer Stand angelegt: archivId (beginnt mit upload-bearbeitet-), kartenname, quelle, neueKennungen, neueLadestation, aenderungen; Protokollzeile karte-bearbeitet |
403 ke.nurAnsehen |
Speichern (aenderungen) mit einer Rolle, die Kartenstände nur ansehen darf (Vertrieb); geprüft, bevor etwas gelesen oder geschrieben wird |
404 ke.aus |
der Editor ist in dieser Umgebung nicht freigeschaltet |
409 ke.geraet |
für dieses Gerät lässt sich kein Stand bearbeiten (z. B. außer Betrieb) |
409 ke.unlesbar / ke.zuGross, 502 ke.kopie |
Stand nicht lesbar, Ergebnis zu groß, Kopie nicht prüfbar — es wird nichts angelegt |
400 mit ke.* |
Eingabe abgelehnt, z. B. ke.ladestationGesperrt (Ladestation nicht verschiebbar bis zur Messung USU-36), ke.dreiEcken, ke.zuVieleEcken (höchstens 200 je Zone), ke.nameFehlt, ke.nameDoppelt |
GET /geraet/{seriennummer}/karten meldet nur bei freigeschaltetem Editor darfBearbeiten
(true nur für Zugänge mit Schreibrecht, siehe Rechte); die Konsole zeigt im Kartenblatt eines Stands nur dann die
Karte „Punkte und Zonen bearbeiten“ mit dem Knopf Bearbeiten. Ein bearbeiteter Stand trägt in
sicherungen[] die Herkunft bearbeitet.
Verteilen eines bearbeiteten Stands (3.7.1): nur an ein Ziel, das im Zustand die Fähigkeit
bearbeitet-empfang-v1 meldet; sonst 409 kv.zielOhneEmpfang („Dieses Gerät nimmt keine in der
uSuite bearbeiteten Kartenstände an. Es wird nicht beliefert.“), kein Auftrag. Ein Stand unter
upload-bearbeitet-… ohne oder mit unbekannter Herkunft wird ebenso behandelt.
Am Gerät wirkt der Schalter ab uGo-Dienst 1.0.37
Die Fähigkeit meldet der uGo-Dienst ab 1.0.37 (freigegeben am 12.11.2026), und nur mit
eingeschalteter Einstellung karteneditorEmpfang (ab Werk aus, je Gerät; setzt der URG-Service
mit Technikerrecht). Ein solches Gerät nimmt einen bearbeiteten Stand an, merkt ihn zum
Aktivieren vor und aktiviert ihn beim nächsten Laden (an der Ladestation, ohne Auftrag, mit
Fahrsperre während des Wechsels); verschobene Punkte behalten ihre Kennung. Ohne diese Fassung
oder Einstellung bewirkt die Freischaltung in der Cloud am Gerät nichts.
Rückweg: Freischaltung zurücknehmen (Cloud-Schalter karteneditor aus). Route und Angebot
entfallen; angelegte Stände bleiben in der Kartenablage erhalten, nichts wird gelöscht.
3.7.5 Karten grafisch bearbeiten — Lesemodus mit Schwärzung, Vorgänge wie am Gerät¶
Stand 12.11.2026 (USU-115 Stufe 1). Gebaut, noch nicht ausgerollt; wirksam nach Einspielen
der Lambda verwaltung und der Konsole. Route, Rechte und Cloud-Schalter karteneditor wie in
3.7.4 — keine neue Route, kein neues Recht. Den Reiter „Karten bearbeiten“ zeigt die Konsole nur
der Rolle Service und dem Verwalter, nicht dem Vertrieb. Bedienung:
Karten grafisch bearbeiten.
Die Konsole zeigt die Karte mit dem Kartenbereich der Roboteroberfläche (Gerätefassung 1.0.37),
als festes Bündel mit Herkunftsangabe (konsole/kartenbearbeitung/HERKUNFT.json: Quellstand,
SHA-256). Arten, Parameter, Prüfregeln und Darstellung sind damit im Browser dieselben wie am
Gerät. Angewendet werden die Änderungen in der Verwaltung, nicht im Browser — Schwärzung,
Kennungserhalt und Grenzen liegen auf dem Server. Ein Gleichlauftest in der uSuite prüft die Regeln
der Verwaltung gegen die Gerätefunktionen; gewollte Abweichungen (Ladestation, IOT-Steuerbereich,
Selbstschnitt) sind dort mit Grund geführt. Die Cloud schickt weiterhin nichts an ein Gerät; es
bleibt bei Verteilen (3.7.1) und Aktivieren nur am Gerät.
Lesen¶
POST /geraet/{seriennummer}/karte/bearbeiten mit { "kartenname": "…", "lesen": true } → 200.
Die bisherigen Felder bleiben (kartenname, anzeigename, merkmale, schluessel: "ke.gelesen");
neu sind:
| Feld | Bedeutung |
|---|---|
zeichnungen |
vollständiger Zeichnungstext der Quelle als JSON-Text — alle Punkte, Zonen samt Parametern und alle LineString —, geschwärzt (siehe unten). Fehlt bei unlesbarem Text. |
rahmen |
{ "aufloesung": …, "ursprung": [x, y] }. Quelle wie im Kartenblatt: Zeichnungstext vor Tabellenzeile vor Beschreibung. Fehlt eine Angabe, fehlt das Feld. |
bild |
vorsignierte GET-Adresse auf das Kartenbild (raster.png) der Quelle. Fehlt, wenn das Signieren scheitert. |
bildGueltigSekunden |
Gültigkeit der Bildadresse, 300. |
hinweisSchluessel |
nur gesetzt als ke.geschwaerztZurueckgehalten: ein geschwärzter Wert kam nach dem Schwärzen noch an anderer Stelle vor. Dann fehlt das betroffene Feld (zeichnungen und/oder merkmale), nie wird der Rohtext ausgeliefert. Die Konsole bietet den Stand dann nicht zum Bearbeiten an. |
Schwärzung (Sperrliste, eine Stelle in der Verwaltung): die Eigenschaften deviceIds, mac,
deviceId, deviceMac — in jeder Tiefe, Schlüssel ohne Rücksicht auf Groß- und
Kleinschreibung — werden vor der Antwort entfernt. Danach sucht die Verwaltung jeden entfernten
Wert (ab vier Zeichen, ohne Groß/klein) im ausgelieferten Text; ein Treffer führt zu
hinweisSchluessel. Beim Speichern wirken die Änderungen auf die Quelle: geschwärzte Werte und
alle unberührten Merkmale kommen Byte für Byte aus ihr.
Speichern¶
{ "kartenname": "…", "aenderungen": [ … ] }, höchstens 200 Einträge. Antwort 201
ke.angelegt wie in 3.7.4 (archivId upload-bearbeitet-…, kartenname, quelle,
neueKennungen, aenderungen), neu mit imBildGeprueft (true/false, siehe Prüfung).
neueLadestation bleibt im Rumpf; seit USU-115 legt die Verwaltung keine Ladestation mehr an.
art |
Felder | Bemerkung |
|---|---|---|
punkt-verschieben |
id, x, y, grad (optional) |
auch Drehen. Ladestation (9) und Andockpunkt (36): ke.ladestationGesperrt bzw. ke.andockpunkt |
punkt-anlegen |
name, punktart, x, y, grad |
punktart 11 Station, 7 Tür, 10 Wartepunkt. 9 Ladestation → 400 ke.punktart (Entscheidung 12.11.2026). Feste Aufzugnamen → ke.festerName |
punkt-umbenennen |
id, name |
neu. Feste Aufzugnamen weder neu noch alt |
punkt-entfernen |
id |
neu. Ladestation und Andockpunkt gesperrt |
aufzugpunkt-ersetzen |
name (ELV1-WAIT oder ELV1-CABIN), x, y, grad |
neu. Ersetzt den vorhandenen Punkt dieses Namens wie der Vorgang „ersetzen“ am Gerät; andere Namen → ke.ersetzenNurFest |
zone-verschieben |
id, ecken |
der vollständige neue Ring: deckt Ecken ziehen, einfügen, entfernen und das Verschieben der ganzen Zone ab. IOT-Steuerbereich: mac/subtype bleiben aus der Quelle |
zone-anlegen |
name, ecken, regionType (optional), parameter (optional) |
erweitert: ohne regionType wie bisher Langsamzone 2. 5 (IOT-Steuerbereich) → ke.iotGesperrt |
zone-umbenennen |
id, name |
neu. Setzt name und desc |
zone-entfernen |
id |
neu. Jede Art |
Zonenarten: die 23 am Gerät belegten Nummern 1–10, 12–20, 22–25.
Parameter (unsere Schlüssel, geschrieben in die Feldnamen des Geräts; Komma als Dezimalzeichen
erlaubt, leere Werte zählen nicht):
regionType |
Parameter → Feld am Gerät | Grenze |
|---|---|---|
2 Langsamfahrbereich |
speedLimit → speed |
keine, wie am Gerät |
7 Steigungsbereich |
speedLimit → speed |
0 bis 1,2 m/s |
15 Tiefhindernisbereich |
obstacleType |
Konsole: „0 steht für ein niedriges Hindernis.“ |
20 Lautstärkebereich |
volume |
0 bis 100 |
Die Wirkung am Roboter ist nur für 2 gemessen; die Konsole zeigt für alle anderen Arten den
Hinweis „Wirkung nicht gemessen“.
Namen: Punktnamen höchstens 100 Zeichen, eindeutig ohne Rücksicht auf Groß/klein und mit
zusammengezogenem Leerraum, auch gegen Punkte, die im selben Auftrag angelegt werden. Feste
Aufzugnamen (ELV1-WAIT, ELV1-CABIN, ELV1-AREA, ELV1-DOOR, jede Schreibweise) entstehen nur
über aufzugpunkt-ersetzen und werden nicht umbenannt; Zonen erhalten keinen festen Aufzugnamen.
Zonennamen höchstens 64 Zeichen, eindeutig — beim Anlegen gegen name, beim Umbenennen auch gegen
desc. Die Konsole begrenzt zusätzlich Namen neuer Punkte auf 64 Zeichen.
Prüfung vor dem Speichern (auch in der Verwaltung): ke.selbstschnitt, wenn sich nicht
benachbarte Kanten einer neuen oder gesetzten Zone kreuzen oder berühren (zwei benachbarte Kanten,
die auf einer Linie zurücklaufen, zählen nicht). ke.ausserhalbBild, wenn ein neuer oder bewegter
Punkt oder eine neue oder gesetzte Ecke außerhalb des Kartenbildes liegt (Rand eingeschlossen).
Geprüft wird nur mit Rahmen und Bildgröße (aus dem Kopf von raster.png); fehlt eines, wird
nicht geprüft und die Antwort trägt imBildGeprueft: false. Bestand außerhalb des Bildes hält das
Speichern nicht auf.
Kennungserhalt: Der neue Stand darf genau die ausdrücklich entfernten oder ersetzten Kennungen
nicht mehr enthalten, sonst keine; dockingPointId ändert sich nie. Verstoß → 500
ke.kennungVerloren, es wird nichts gespeichert.
Fehlerschlüssel¶
Alle Absagen der Eingabe kommen als 400 mit schluessel, fehler (deutscher Klartext), index
(Stelle in aenderungen) und, wo sinnvoll, werte. Die Konsole übersetzt die Schlüssel in sechs
Sprachen.
| Schlüssel | Bedeutung | werte |
|---|---|---|
ke.zonenart |
regionType am Gerät nicht belegt |
{ regionType } |
ke.iotGesperrt |
IOT-Steuerbereich (5) wird in der uSuite nicht angelegt |
— |
ke.parameterObjekt |
parameter ist kein Objekt |
— |
ke.parameterUnbekannt |
Parameter gibt es für diese Art nicht | { regionType, parameter } |
ke.parameterZahl |
Parameter ist keine Zahl | { parameter } |
ke.parameterUnter / ke.parameterUeber |
Wert unter bzw. über der Grenze | { parameter, grenze }, z. B. "1.2 m/s" |
ke.punktart |
Punktart lässt sich hier nicht anlegen (auch Ladestation 9) |
— |
ke.festerName |
fester Aufzugname, wo er nicht erlaubt ist | — |
ke.ersetzenNurFest |
aufzugpunkt-ersetzen mit anderem Namen |
{ namen } |
ke.nameZuLang |
Name zu lang | { zeichen: 100 } bei Punkten |
ke.zoneNameDoppelt |
Zonenname schon vergeben | — |
ke.andockpunkt |
Andockpunkt wird nicht einzeln verschoben | — |
ke.selbstschnitt |
Zonenkanten kreuzen sich | — |
ke.ausserhalbBild |
Punkt oder Ecke außerhalb des Kartenbildes | — |
ke.keineAenderung |
leere Änderungsliste | — |
403 ke.nurAnsehen |
Rolle darf Kartenstände nur ansehen (Vertrieb), siehe Rechte | — |
| wie bisher | ke.nameFehlt, ke.nameDoppelt, ke.kennungUnbekannt, ke.ladestationGesperrt (jetzt auch beim Entfernen von 9 und 36), ke.zahl, ke.dreiEcken, ke.zuVieleEcken (höchstens 200 je Zone), ke.zuViele (mehr als 200 Änderungen), ke.art |
— |
500 ke.kennungVerloren |
Kennungserhalt verletzt, nichts gespeichert | — |
Rückweg: wie 3.7.4 (Schalter karteneditor aus: Route und Angebot entfallen, angelegte Stände
bleiben). Die Tabellenform aus 3.7.4 bleibt in der Konsole als zweiter Weg erhalten.
Rechte: Lesen und Schreiben von Kartenständen¶
Stand 12.11.2026 (Entscheidung vom 12.11.2026), gebaut, noch nicht ausgerollt; wirksam mit der
Lambda verwaltung. Ansehen und Schreiben von Kartenständen sind getrennte Rechte:
| Recht | Wer | Wofür |
|---|---|---|
darfKartenstand (Ansehen) |
Zugänge mit Kartenrecht wie bisher, darunter der Vertrieb | Kartenliste (GET /geraet/{seriennummer}/karten), Herunterladen, Lesemodus des Editors (POST …/karte/bearbeiten mit lesen: true) |
darfKartenstandSchreiben (Schreiben) |
wer Servicehandlungen darf oder als Verwalter des Kunden verwaltet — nicht der Vertrieb | Hochladen (POST /geraet/{seriennummer}/karte/hochladen), Speichern im Editor (POST …/karte/bearbeiten mit aenderungen) |
| Verteilen (dieselbe Regel) | wie Schreiben — nicht der Vertrieb | alle Verteilwege über POST /geraet/{seriennummer}/karte/verteilen (3.7.1–3.7.3); sonst 403 kv.rolle |
Eine Rolle ohne Schreibrecht erhält beim Hochladen und beim Speichern 403 mit
schluessel: "ke.nurAnsehen" und hinweis, bevor etwas gelesen oder geschrieben wird. Wortlaut der
Konsole: „Diese Rolle darf Kartenstände nur ansehen, nicht speichern oder hochladen.“ / Hinweis:
„Speichern und hochladen dürfen Service und der Verwalter des Kunden.“ Die Kartenliste meldet
darfHochladen, darfBearbeiten und darfVerteilen nur mit Schreib- bzw. Verteilrecht als true;
ohne Verteilrecht fehlen auch Ziele, Zurückspielen und Mehrfachangaben. Neu ist darfHerunterladen
(= Ansehen): daran hängt der Knopf „Herunterladen“, der vorher am Verteilrecht hing; ältere Antworten
ohne das Feld behandelt die Konsole wie bisher über darfVerteilen. Geprüft wird das Recht, nicht
der Rollenname. Der Vertrieb sieht und lädt herunter, speichert, lädt hoch und verteilt nicht
(Entscheidungen vom 12.11.2026).
Rückweg: Schreiben wieder an darfKartenstand binden, Verteilen wieder an Servicerecht oder
Verwalter (Commits zurücknehmen).
Keine gemessene Wirkung in der Anzeige: Die Kartenbearbeitung zeigt für die Langsamzone keine gemessenen Wirkungswerte an (Entscheidung 12.11.2026); der Bau sperrt den betreffenden Gerätetext. Für alle übrigen Zonenarten bleibt der Hinweis, dass die Wirkung nicht gemessen ist. Angezeigt werden nur eingestellte Parameter und die Grenzen des Formulars.
3.8 Anmeldestrecke¶
Der Kernpunkt, um den sich das ganze Verfahren dreht: der private Schlüssel verlässt das Gerät nie. Der Roboter erzeugt sein Schlüsselpaar selbst und schickt nur eine Zertifikatsanfrage (CSR). Die Cloud ruft CreateCertificateFromCsr auf; AWS IoT unterschreibt mit seiner eigenen CA. Ein Einbruch in unsere Cloud gibt einem Angreifer damit keine Möglichkeit, sich als ein Roboter auszugeben — der Schlüssel lag dort nie. Ein Plattentausch am Roboter kostet dafür ein neues Zertifikat; das ist der bewusst in Kauf genommene, günstigere Preis.
Es wird ausdrücklich keine eigene Zertifizierungsstelle betrieben. Eine eigene CA hiesse einen CA-Schlüssel besitzen, sichern, drehen und im Ernstfall sperren — eine Aufgabe für eine Organisation mit Schlüsseltresor und Verfahren, nicht für ein Vorhaben, dessen Kern ist, dass ein Roboter auch ohne Cloud fährt.
| Schritt | Was passiert |
|---|---|
| 1 | Techniker gibt auf der Technikerseite den einmaligen Beitrittscode ein → POST /api/wolke {aktion:"anmelden", beitrittscode} |
| 2 | Das Gerät liest seine Seriennummer vom Fahrgestell, erzeugt Schlüssel und CSR |
| 3 | POST <WOLKE_ANMELDUNG_URL> mit {beitrittscode, seriennummer, typ, csr} |
| 4 | Der Dienst prüft Code und Rumpf, legt Ding, Zertifikat und Verknüpfungen an und antwortet |
| 5 | Das Gerät legt Zertifikat und Vermerk ab und verbindet sich neu |
Endpunkt: POST /anmeldung (HTTP-API, gedrosselt auf 10 Anfragen je Sekunde, Spitze 20). Es gibt genau diesen einen Pfad — keinen Zweig, keinen Parameter und keinen Fehlerfall, aus dem ein Fahrbefehl entstehen könnte.
| Feld der Anfrage | Prüfung |
|---|---|
beitrittscode |
Zeichenkette, höchstens 64 Zeichen |
seriennummer |
höchstens 64 Zeichen, ^[A-Za-z0-9_-]+$ — sie wird Dingname und Teil eines Themenpfades, es darf nichts Fremdes hinein |
typ |
^[A-Za-z0-9_-]{1,32}$. Das ist die Baureihe (uGo, uServe, …), nicht die Einsatzart. Bewusst eine Zeichenprüfung statt einer Liste: der Katalog der Baureihen ist offen, und eine geschlossene Liste hiesse, dass ein Roboter einer neuen Baureihe im Krankenhaus stehenbleibt, bis jemand eine Lambda neu ausrollt |
csr |
höchstens 8192 Zeichen, muss -----BEGIN (NEW )?CERTIFICATE REQUEST----- enthalten. Ein fertiges Zertifikat wird abgewiesen — wer eines einreicht, versucht etwas anderes als eine Anmeldung |
| Feld der Antwort | Bedeutung |
|---|---|
zertifikatPem |
das ausgestellte Zertifikat |
thingName |
= Seriennummer, zugleich die clientId |
kunde |
Kurzkennzeichen des Betreibers, kein Klarname |
iotEndpunkt |
MQTT-Endpunkt |
Fehlerverhalten, das bewusst so ist: unbekannter, abgelaufener und verbrauchter Code ergeben dieselbe Meldung mit 403. Wer Codes rät, darf aus der Antwort nicht lernen, ob er nah dran war; der Techniker vor Ort braucht die Unterscheidung nicht, sein nächster Schritt ist in allen drei Fällen derselbe. Der Ablauf wird zusätzlich geprüft, nicht nur dem TTL der Tabelle überlassen — DynamoDB löscht abgelaufene Einträge träge (bis 48 Stunden).
Wiederholung nach Abbruch: ein bereits verbrauchter Code wird noch einmal angenommen, wenn dieselbe Seriennummer mit demselben CSR-Fingerabdruck wiederkommt; dann wird dasselbe Zertifikat erneut herausgegeben, statt ein zweites auszustellen.
Auf dem Gerät gilt: ganz oder gar nicht. Schlägt ein Schritt fehl, bleibt kein halbes Zertifikat und kein halber Vermerk zurück. War das Gerät vorher schon angemeldet, wird an der vorhandenen Identität nichts angefasst — sonst nähme ein Tippfehler im Code einem laufenden Roboter seine Anmeldung. Der Beitrittscode wird nirgends protokolliert.