Skip to content

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:

  1. Parameter — der kurze Weg, wenn AWS ihn zulässt.
  2. Zeiger — sind die Felder unersetzt geblieben, lädt das Gerät zeiger.dokument und 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.

  1. Gerät → …/karte/anfrage: nur der Steckbrief — {vorgang:"ablageadressen", archivId, name, pruefsumme, dateien:[{name, bytes}], anfrageId}. Das ist klein und passt immer.
  2. Lambda legt eine vorläufige Zeile an („erwartet") und antwortet auf …/karte/antwort mit 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.
  3. Gerät lädt per HTTPS unmittelbar nach S3, beschreibung.json zuletzt. Reisst die Verbindung ab, wird wiederholt; die Schlüssel bleiben dieselben.
  4. S3 meldet die eingetroffene beschreibung.json zurü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.