uSuite — console and administration, state 12.11.2026¶
For IT, technicians and integration partners
Technical reference for IT departments, URG technicians and trained partners. It is not written as operating instructions for end users.
Info
This page describes what the uSuite console and its administration interface can do as of 15.09.2026, extended by the sections State 25.10.2026, State 08.11.2026, State 10.11.2026 and State 12.11.2026. The device side — MQTT, job document, rollout stages, enrolment — is unchanged and documented in URG cloud (uSuite). Nothing on this page adds a driving command: the cloud still sends the device exactly two things, a release and a lock.
What is new for operators and service¶
| Area | What it does | Since |
|---|---|---|
| Device master data (Stammblatt) | Per device: delivery date, warranty months, contract level and end, maintenance interval, last maintenance, display name, floor, contact. Without these entries the device shows as without data in the service view — nothing is estimated. | 14./15.09.2026 |
| Product series (Baureihe) and type records | Every device carries its series (ulog-deliver-80, ulog-deliver-150, ulog-lift-150, userve, …). Documents can be filed for the whole series in one go — data sheet, quick guide, service description, user manual, IT notes, network requirements, declaration of conformity. Service booklets are filed per device. The batch dialog classifies files by name and shows the class before anything is stored. |
15.09.2026 |
| Superseded editions | A newer edition of the same class, language and product marks the older one as superseded by …; operators and partners see only the valid edition. Older entries are never deleted. A dry-run stock pass links the existing duplicates (Rev. 02/Rev. 03, 2.0/2.1). | 15.09.2026 |
| Decommissioning | Two separate paths: retire (reversible, device stays in the list, messages keep flowing into the log) and revoke credential (final, two-step confirmation, log line). Revoking is prepared but not yet switched on. | 15.09.2026 |
| Certificate expiry | The watch service reads each device certificate's expiry and opens a case with a deadline below 90 days (notice / warning / fault at 90 / 30 / 7 days). Renewal itself is not part of this stage. | 15.09.2026 |
| Updates page — version distribution | A bar over the update page: 14 devices on 2.4.1, 3 on 2.3.9, 1 unknown. Clicking a segment filters the device list. Numbers come from the existing fleet and version data, no new route. | 15.09.2026 |
| Updates page — preselection before release | Choose the version, choose the target (one device, one site, one customer), read how many devices are affected and how many already run it, then release. Releasing does not mean immediately: every robot picks it up at its next charging break. | 15.09.2026 |
| Updates page — “What is new” | Per version a fold-out with the change list. The list is stored next to the signed package; the package itself is untouched. Rendered without a library, no links, no raw HTML. | 15.09.2026 |
| Session | The console now renews the sign-in ticket silently. Before, every session ended after 60 minutes with not signed in — a console-side omission, the identity provider was configured correctly. | 15.09.2026 |
| Thing groups per site | For every site node the administration keeps a device group (kunde-<customer>, haus-<customer>-<site>) next to the existing release group. Prepared for release by site; not yet switched on. |
in preparation |
| Automatic cases carry the device | Cases opened by the watch service (emergency stop, battery, wheel overload, reporting gap) now carry serial number, path, customer and type — before, they were visible to no site. A stock pass fills the missing fields on existing cases (dry run first). | in preparation |
Administration routes added¶
All routes sit behind the administration HTTP API, are authorised by the same JWT check as the existing ones, and write a log line per change. None of them deletes data.
| Route | Purpose | Roles |
|---|---|---|
POST /geraet/{seriennummer}/stammblatt |
Set the master data fields of one device | service, administrator |
POST /geraet/{seriennummer}/stilllegen |
Retire a device (reversible) | administrator, service |
POST /geraet/{seriennummer}/wieder-in-betrieb |
Put a retired device back into operation | administrator, service |
POST /geraet/{seriennummer}/kennung-entziehen |
Revoke the device credential (two-step; not yet switched on) | service only |
GET /fassung/{fassung}/{schicht}/neu |
Read the change list of a version (404 if none is stored, 501 in an environment without version management) |
everyone with a scope |
Routes that existed before this stage — knots, join codes, customers, accesses, cases, service requests, version release, records — are unchanged; see Services overview.
State 25.10.2026 — offerings, prices from the CRM, light and dark mode¶
In acceptance on the test site
The changes below are built and checked; they go live after acceptance on the test site. Prices from the CRM are switched off until the CRM provides its catalogue interface.
| Area | What it does |
|---|---|
| Offerings page — payment | Payment is on invoice only (payment term at most seven days net). There is no online payment; the former pay immediately by card route and the card markers are gone. |
| Offerings page — prices | Every amount is a guide price; the quote is binding. Everybody, URG administration included, reads prices outside the European Union on request; the console carries no internal pricing rule and no list prices. With the CRM connection switched on, each access sees the prices of its market in that market's currency (for example North America in US dollars); an offering without a price from the CRM, or with an amount of 0, shows on request. Guide prices appear only while the connection is off or against an older interface; an error, no answer within 10 seconds or an incomplete answer shows on request — never a guide price in euros instead of a market price. If the CRM data carry no date, the page names market and currency without the date. |
| Price market per node | URG administration (root with the structure right) assigns a price market to a distributor, partner, customer or site: DACH, RoE (rest of Europe), ME (Middle East), NAM (North America). The nearest node with a market applies to everything below it; without one the environment default applies, otherwise prices are on request. Partners and customers cannot see or change markets. |
| Light and dark mode | A button in the header switches System → Light → Dark. The choice is kept in the browser; without a choice the system setting applies. All texts in the six console languages. The maintenance record always prints on white with dark text, whatever the colour scheme. |
| Layout on wide screens | From 1200 px width the header becomes a sidebar on the left (navigation groups below each other, account, language, colour scheme and help at the bottom). Narrow screens keep the top bar with the menu button. |
Administration routes added (25.10.2026)¶
| Route | Purpose | Roles |
|---|---|---|
GET /katalog/preise |
Prices of the caller's market for the offerings. Answer: aktiv (false while the CRM connection is off), markt, waehrung (ISO 4217), stand (time of the CRM data), veraltet (true if the CRM could not be reached and the last state is shown), preise (offering id → amount above 0, net; only list prices — a CRM answer without preisart: "liste" is not used), grund when nothing could be priced (markt_fehlt, keine_abbildung, crm_nicht_erreichbar, crm_antwort_unbrauchbar). Never an error for a CRM problem — the worst case is on request. |
everyone with a scope |
POST /knoten/markt |
Set (markt: DACH, RoE, ME, NAM) or remove (markt: null) the price market of a node; writes a log line. 403 for everyone but the root with the structure right, 404 unknown node, 400 unknown market. |
root with structure right |
GET /knoten additionally returns maerkte (node path → market) — for the root only.
State 08.11.2026 — distribute maps across driving model series¶
Built, not yet deployed
Takes effect after the administration service and the console of the uSuite have been deployed. Operating steps: Distribute maps to other robots.
| Area | What it does |
|---|---|
| Targets | Device page › card Maps › Distribute to another device now offers every device of the same node that is in operation and belongs to the driving family with the same map format — uGo, uServe, uLog — not only devices of the source's own series. Humanoid, stationary systems, pre-registered devices, devices out of service, another node, an empty typ and series outside the family stay locked and are listed under Not selectable at this site with the reason. |
| Marking | A target of another series is marked different model series: uServe (and so on). |
| Mandatory confirmation | As soon as such a target is selected, the console shows why (dimensions, routes, zones and charging station differ between series) and the tick box Routes, narrow passages and zones have been checked on site for this model series. The button stays locked until it is ticked. |
| Record | The job and the log line record who confirmed and when (andereBaureiheBestaetigtVon, andereBaureiheBestaetigtAm) and the source series (quellTyp). |
The robot does not check the model series on import
The check in the uSuite is the only technical lock. The on-site confirmation by the technician is the decisive check. Activation still happens only on the robot.
Administration routes changed (08.11.2026)¶
No new route and no new right.
| Route | Change |
|---|---|
GET /geraet/{seriennummer}/karten |
ziele[].andereBaureihe is true for a target of another series; ausgeschlossen gives the reason from the same rule as the check on sending (now also humanoid, pre-registered, stationary system). |
POST /geraet/{seriennummer}/karte/verteilen |
New field andereBaureiheBestaetigt: exactly true is required as soon as a target is another series (for ziele, it covers the whole distribution). Without it: 409 with key kv.andereBaureiheUnbestaetigt; for ziele per target in ergebnisse, the other targets are kept. |
Interface details (German): URG cloud, 3.7.1 and 3.7.2.
State 10.11.2026 — edit points and zones (map editor)¶
Available once switched on
USU-114 (USU-111 stage B): the cloud switch karteneditor (default off) is permitted in the
production and the test environment. Route and console offer exist only while it is on.
Operating steps: Edit points and zones.
| Area | What it does |
|---|---|
| Console | In the map sheet of a backed-up version, accesses with the upload right (service, customer administrator) see the card Edit points and zones with the button Edit: move points, change zone corners, create points (station, door, waiting point) and slow zones, then Save as new map version. Charging stations can be neither created, moved nor removed (since 12.11.2026). From 12.11.2026 the button is called Edit as table; Edit opens the graphical editor (State 12.11.2026). |
| Result | The editor works on a copy and creates a new version with origin bearbeitet (archive identifier upload-bearbeitet-…). The source version stays unchanged. Nothing is sent to a device; distribution uses the existing route, activation happens only on the device. |
| Rights | No new right — the existing upload right. |
| On the device | An edited version is accepted from uGo service 1.0.37 (released 12.11.2026) with the setting karteneditorEmpfang (off by default, per device). The device notes it for activation and activates it at the next charge (on the charging station, no order, drive lock during the switch); moved points keep their identifier. Without that version or setting, the cloud switch has no effect on the device. |
| Way back | Switch off: the route disappears; versions already created are kept. |
Administration routes added and changed (10.11.2026)¶
| Route | Change |
|---|---|
POST /geraet/{seriennummer}/karte/bearbeiten |
New (only with the switch on, otherwise 404 ke.aus). lesen: true returns the points and zones of kartenname; aenderungen creates a new version (201, archivId). Roles: upload right; view only → 403. |
GET /geraet/{seriennummer}/karten |
darfBearbeiten (only with the switch on); sicherungen[].herkunft can be bearbeitet. |
POST /geraet/{seriennummer}/karte/verteilen |
An edited version goes only to a target that reports the capability bearbeitet-empfang-v1; otherwise 409 kv.zielOhneEmpfang, no job. |
Interface details (German): URG cloud, 3.7.4.
State 12.11.2026 — edit maps graphically (view #kartenbearbeitung)¶
Built, not yet rolled out
USU-115 stage 1. Effective after the administration Lambda verwaltung and the console have
been rolled out; same cloud switch karteneditor, same route and same right as the table
editor of 10.11.2026. Operating steps:
Edit maps graphically in the uSuite.
| Area | What it does |
|---|---|
| View | New view #kartenbearbeitung under Service (navigation entry Edit maps). Address #kartenbearbeitung, #kartenbearbeitung=<device>, or with a version <device> and <version> joined by a vertical bar: choose device → choose backed-up map version → editor. The entry is shown to the service role and the customer administrator, not to the sales role (sales may only view map versions: list, download, read mode; saving and uploading answer 403 ke.nurAnsehen, distributing answers 403 kv.rolle on every distribution path; the map list reports darfVerteilen: false and the new field darfHerunterladen, which now drives the download button; decisions 12.11.2026). The measured effect of the slow-moving area is not displayed in the editor; per device the view checks darfBearbeiten from GET …/karten. Without the right it shows No access and loads neither the read mode nor the map bundle. |
| Map sheet | In the card Edit points and zones, Edit now opens #kartenbearbeitung for this version; Edit as table keeps the table editor of 10.11.2026 as a second way until acceptance. |
| Map bundle | konsole/kartenbearbeitung/karte.js (ES module) and karte.css, built from the map area of the robot's operator interface (device version 1.0.37) at a fixed source state; source, tools and SHA-256 in konsole/kartenbearbeitung/HERKUNFT.json. Loaded with import() and <link>. The content security policy of the console is unchanged (no inline styles, no frame-src). The bundle contains no device paths, no driving or localisation commands, no device settings, no call to map distribution and no network access of its own. |
| Editing | Points: create (station, door, standby point, lift waiting point and lift cabin with fixed names), rename, drag, rotate (Shift: 15°), remove. Zones: create with kind (23 kinds known on the device, IoT control area excluded) and parameters, drag/insert/remove corners, move, rename, remove. Charging station and docking point: neither created, moved nor removed. Undo/redo (Ctrl+Z/Ctrl+Y), check and preview, Save as new map version; leaving with unsaved changes asks first; no autosave. |
| Language | Follows the console language; the kinds and zone names in the map come from the six-language tables of the operator interface, the texts of the view from the console tables. |
| Not offered | Driving commands, setting the robot position, points at the robot position, map recording, activation, device settings, live layers (robot, other robots, sensor data), distribution from the editor. |
Administration routes changed (12.11.2026)¶
| Route | Change |
|---|---|
POST /geraet/{seriennummer}/karte/bearbeiten (lesen: true) |
Additionally returns zeichnungen (full drawing text, redacted), rahmen, bild, bildGueltigSekunden; hinweisSchluessel: "ke.geschwaerztZurueckgehalten" when a redacted value could not be withheld safely (the field concerned is then missing). |
POST /geraet/{seriennummer}/karte/bearbeiten (aenderungen) |
New kinds punkt-umbenennen, punkt-entfernen, aufzugpunkt-ersetzen, zone-umbenennen, zone-entfernen; zone-anlegen with regionType and parameter; punkt-anlegen no longer accepts the charging station (ke.punktart). New error keys ke.zonenart, ke.iotGesperrt, ke.parameter*, ke.festerName, ke.zoneNameDoppelt, ke.nameZuLang, ke.ersetzenNurFest, ke.selbstschnitt, ke.ausserhalbBild; 201 carries imBildGeprueft. |
Interface details (German): URG cloud, 3.7.5.
Known gaps (15.09.2026)¶
- Documents whose file name names two product families (
uServe_uLog_Serie,uLog_uServe) — the declaration of conformity and the network requirements — could only be filed per device for the uLog series; the classifier treated them as uServe documents. A correction is in preparation; the documents will then be filed series-wide. - Where the credential is revoked (administration or enrolment service), and whether retired devices count in the fleet figures, are open decisions.
State 08.11.2026 — key figures per robot and per site¶
Built, effective with the next uSuite update
The changes below are built and checked. They take effect once the next uSuite update is installed; until then the console and the routes answer as before. Operating instructions for operators: Key figures in the uSuite.
| Area | What it does |
|---|---|
| Device page — card Key figures | Loaded after the rest of the device page, which does not wait for it. Per robot, for 7, 30 or 90 days ending with the last complete day (yesterday): distance, trips (logbook), failed trip rate, driving time, utilisation, technical availability (reports) — not contractual —, emergency stops, jobs completed / failed / cancelled (seen), open faults (current value) and battery min/max with a chart per day. Each figure carries its coverage (x of n days) and the trend against the previous period. |
| Overview — key figures per site and robot ranking | The same totals and rates per site, with trend; below, a ranking of all visible robots, sortable by every column, robots without data in the sort column last. An access with exactly one site sees the ranking only. |
| CSV export | One button per view (robot card, site table, ranking). Built in the browser from the answer already loaded; no new route. UTF-8 with byte order mark, CRLF; separator and decimal sign by console language (en: , and .; de, fr, es, it, nl: ; and ,). Text fields starting with =, +, -, @, tab or CR are prefixed with '. No data is an empty field. No serial number in files of accesses below the root. |
| No data, not zero | A figure without a source is null in JSON, no data on screen and an empty field in CSV — never 0. |
| Daily balance | Three new fields per row and a correction of how stored days are written, see Daily balance. |
Console routes added and extended (08.11.2026)¶
| Route | Purpose | Roles |
|---|---|---|
GET /geraet/{seriennummer}/kennzahlen |
Key figures of one robot for the device card. tage is 7, 30 or 90, default 30. |
everyone with a scope who can see the device |
GET /kennzahlen?tage=n&vergleich=1&jeGeraet=1&jeHaus=1 |
Existing route, three optional switches added. Without a switch the answer is field-for-field the same as before. | everyone with a scope |
Visibility is unchanged and depends on the scope, not on the role: an access sees exactly the
devices whose node path equals its scope or lies below it. Both routes filter before they read the
daily balance — the figures of a foreign site are never read. A device outside the scope, or an
unknown device, answers 404 with the same text as GET /geraet/{seriennummer}. There is no new
role and no role check of its own.
GET /geraet/{seriennummer}/kennzahlen¶
| Field | Content |
|---|---|
seriennummer, tage, zeitzone |
The device, the period in days, the time zone of the calendar days (Europe/Berlin). |
zeitraum {von, bis} |
The tage calendar days up to and including yesterday, the last complete day, as YYYY-MM-DD. Today's partial day counts neither in totals, daily means, coverage nor trend. |
vorzeitraum {von, bis} |
The same number of days directly before. |
werte |
The figures of the period (see Figure objects). |
vorher |
The same figures for the previous period. |
trend |
Per figure {wert, art, abdeckung} (see Trend). |
jeTag[] |
One row per day of the period: tag, meter, fahrsekunden, fahrtenGemeldet, fehlfahrtenGemeldet, erledigt, gescheitert, abgebrochen, notausEreignisse, akkuMin, akkuMax, meldungen, gesund, gesundSekunden. A field without a source is null. |
stoerungen |
{offen, stoerungen} — open cases and open cases with severity 3, a current value (not limited to the period) read from the 100 most recent cases of the device. null if the cases cannot be read; the answer is still 200. |
festlegungen |
The fixed values the console works with (see Fixed values). |
bereich, rolle |
Scope and role of the caller. |
The answer carries no destination name, no position and no location.
| Code | When |
|---|---|
200 |
Figures delivered (also when every figure is null). |
400 |
tage other than 7, 30, 90, or no serial number. |
404 |
Device unknown or outside the caller's scope. |
501 |
The daily balance is not set up in this environment. |
GET /kennzahlen — new switches¶
tage stays as before: 1 to 90, default 14. A switch is on only with the value 1.
| Switch | Additional fields |
|---|---|
| any of the three | zeitraum {von, bis} (ending with yesterday, as for the device route), werte (figures of all visible devices together), festlegungen |
vergleich=1 |
vorzeitraum {von, bis}, vorher, trend |
jeGeraet=1 |
geraeteWerte[]: per visible device seriennummer, pfad, haus, anzeigename, baureihe, werte, and with vergleich=1 also trend. The console shows accesses below the root the display name or the series with a running number, never the serial number. |
jeHaus=1 |
haeuser[]: per site haus, geraete (number of devices), werte, and with vergleich=1 also vorher and trend. Totals and rates are summed over reports and seconds, not averaged from device rates. |
A site (haus) is the customer node (k-…) in the device's path. Devices without a customer node
in their path form a group of their own per path.
Without a switch the fields leiste, jeTag, geraete, mitBilanz, verfuegbarkeit,
meterGesamt, auftraegeGesamt, erledigtGesamt, gescheitertGesamt, befunde, gestoert,
bereich, ebene, rolle are exactly as before. 501 if the daily balance is not set up, as
before.
Figure objects¶
Every figure in werte and vorher is an object with wert, tageMitDaten and tageImZeitraum.
wert is null when no day of the period has a source for it. Rates are fractions between 0 and 1
(utilisation may exceed 1).
| Key | wert |
Source and rule | Extra fields |
|---|---|---|---|
strecke |
metres | sum of meter, days with logbook |
— |
fahrzeit |
seconds | sum of fahrsekunden, days with logbook |
— |
fahrten |
count | sum of fahrtenGemeldet (completed trips only), days with logbook |
— |
fehlfahrtenQuote |
fraction | fehlfahrtenGemeldet ÷ (fahrtenGemeldet + fehlfahrtenGemeldet), days on which failed trips were reported |
fehlfahrten, fahrten |
auslastung |
fraction | sum of fahrsekunden ÷ sum of gesundSekunden, days with both values and gesundSekunden above 0; not capped |
fahrsekunden, gesundSekunden, ueber100 |
verfuegbarkeit |
fraction | sum of gesund ÷ sum of meldungen, days with reports — technical availability (reports), not contractual |
gesund, meldungen |
erledigt, gescheitert, abgebrochen |
count | jobs seen by the cloud, days with reports | — |
notaus |
count | sum of notausEreignisse, days with reports |
— |
akku |
— | instead of wert: min (lowest akkuMin) and max (highest akkuMax) |
min, max |
A day with reports has a daily balance row with meldungen above 0; a day with logbook has a
row with a numeric meter.
Trend¶
trend holds per figure (not for akku) wert, art and abdeckung {jetzt, vorher, tage}.
art: "prozent"for totals: change of the daily mean (over days with data) in percent, one decimal.art: "punkte"for rates: difference in percentage points, one decimal.wertisnullwhen one of the two values is missing, when the previous period has no day with data, or when its daily mean is 0.
The 90-day previous period lies before the start of the daily balance; its trend is null at
first.
Fixed values¶
festlegungen: zeitraeumeTage [7, 30, 90], zeitraumVorgabe 30, zeitraumEndetGestern true (the period ends with yesterday), gesundLueckeMs (15 minutes),
trendMindestTage 1, rangliste (verfuegbarkeit, ascending), haus "kunde",
auslastungGekappt false, stillgelegteZaehlen true, stand, herkunft. The console takes
these values from the answer and keeps no copy of its own.
Daily balance¶
The daily balance (one row per device and calendar day, computed every night at 02:20 UTC for the last days) gains three optional fields. Older rows without them stay valid; the figures then show no data.
| Field | Meaning |
|---|---|
fehlfahrtenGemeldet |
Failed trips of the day from the device logbook; only when the logbook of that day was reported. |
gesundSekunden |
Sum of the gaps between a healthy report and the next report of the same device, if the gap is at most 15 minutes; a longer gap counts 0. Cut at midnight and counted on the day of the first report. Healthy: no emergency stop, no overloaded wheel, no trip in state failed. |
notausEreignisse |
Number of changes from a report without to a report with emergency stop. |
Correction: the run reads one day more than it writes, starting at the beginning of that day in the calendar (also across the change to and from summer time), so that gaps and emergency-stop changes
across midnight are counted. Until now it also wrote that oldest, only partly read day, and each
stored row could lose the first hours of its day. The run now writes only fully read days. A refill
takes { "tage": n, "bis": "YYYY-MM-DD" } and computes exactly the n days up to bis; if the
record limit of a run is reached, nothing is written from the interrupted day onwards and the report
names it in abgeschnittenAb. With the update, the stored history is recalculated once, in windows
of at most 30 days.
Limits¶
- Days are counted by arrival in the cloud; reports sent late after a network outage appear on the day they arrived.
- Devices whose software does not count failed trips report 0 failed trips; such a 0 cannot be told apart from a real 0.
- Jobs (seen) are trip numbers seen in a status report; a trip entirely between two reports is missing. They are not offset against trips (logbook).
- Not part of this stage: counts per destination, positions, contractual availability or service levels, target values or thresholds, PDF reports or scheduled exports, figures for stationary laboratory systems.