Nutzerdokumentation Thingsboard Frost Adapter

Willkommen in der Nutzerdokumentation des Thingsboard Frost Adapter.

Einleitung

Der Thingsboard Frost Adapter überträgt Gerätedaten aus ThingsBoard in einen FROST‑Server und macht sie dort über die standardisierte OGC SensorThings API verfügbar. Dadurch können Telemetriedaten, die bereits in ThingsBoard erfasst werden, ohne zusätzlichen Integrationsaufwand von anderen Systemen genutzt werden, die die SensorThings API sprechen (z. B. Kartenanwendungen, Auswertungswerkzeuge oder andere IoT‑Plattformen).

Ein Mandant, ein FROST‑Server

Der Adapter bedient mehrere Mandanten gleichzeitig. Ein Mandant ist die Zusammenfassung eines ThingsBoard‑Mandanten mit genau einem FROST‑Server: Die Geräte dieses ThingsBoard exportieren ausschließlich dorthin, und dieser FROST‑Server nimmt ausschließlich Daten von dort entgegen. Diese Zuordnung ist strikt eins‑zu‑eins.

Adressiert wird ein Mandant über seinen Slug — eine kurze, unveränderliche Kennung. Sie steht in der URL, an die die Rule Chain im ThingsBoard des Mandanten ihre Nachrichten schickt:

http://thingsboard-frost-adapter:8000/ingest/<slug>/telemetry

Weil der Slug damit in einem fremden System steht, lässt er sich nachträglich nicht ändern; siehe Mandanten verwalten.

Die Zuordnungen zwischen Telemetrie und SensorThings‑API‑Begriffen — Units of Measurement und Observed Properties — gelten dagegen mandantenübergreifend: Sie werden einmal gepflegt und gelten für alle Mandanten gleichermaßen.

Wegweiser

Diese Dokumentation richtet sich an drei Leserinnen und Leser:

Technische Hintergründe zur Implementierung, zum Datenmodell und zur SensorThings API selbst finden sich in der technischen Dokumentation. Alles, was einen Shell‑Zugang voraussetzt — eine FROST‑Instanz bereitstellen, die Rule Chain je Mandant verteilen, Wiederherstellung nach Fehlbedienung — steht in den Betriebsanleitungen.

Gerät an FROST veröffentlichen

Dieser Abschnitt beschreibt, wie ein Gerät in ThingsBoard mittels des Thingsboard Frost Adapter zum Frost-Server „veröffentlicht“ wird, welches Datenmodell in ThingsBoard dafür vorausgesetzt wird, und wie sich Änderungen bzw. das Entfernen des Geräts auswirken.

Diese Seite setzt voraus, dass für diesen ThingsBoard‑Mandanten bereits eingerichtet ist:

Diese Einrichtung selbst ist nicht Gegenstand dieser Seite.

Voraussetzungen: Datenmodell in ThingsBoard

Damit ein Gerät korrekt als SensorThings‑API‑Entität (Thing) im FROST‑Server abgebildet werden kann, müssen in ThingsBoard folgende Voraussetzungen erfüllt sein:

Voraussetzung Beschreibung

Geräteprofil (Device Profile)

Jedes Gerät muss einem Geräteprofil zugeordnet sein. Name und Beschreibung des Profils werden als Sensor in FROST angelegt. Ein Geräteprofil entspricht also einem Sensor; alle Geräte mit demselben Profil teilen sich diesen Sensor.

Verknüpfung mit einem Standort‑Asset

Das Gerät muss über eine Relation vom Typ Contains mit einem Asset verbunden sein, wobei die Relation vom Asset zum Gerät zeigt (Asset „Contains“ Gerät). Der Typ dieses Assets muss aktuell zwingend building sein – andere Asset‑Typen werden nicht berücksichtigt.

lat/lon‑Attribute am Standort‑Asset

Das verknüpfte building‑Asset benötigt die numerischen Attribute lat und lon. Daraus wird die geografische Position der FROST‑Location erzeugt.

Telemetrie‑Schlüssel‑Zuordnung

Für jeden Telemetrie‑Schlüssel, der als Datastream in FROST erscheinen soll, muss vorab ein passender Eintrag unter Telemetry Keys in der Zuordnungspflege existieren (Zuordnung zu einer Observed Property und einer Default UOM).

Zusätzlich werden folgende optionale Felder ausgewertet:

Optionales Feld Wirkung

Beschreibung des Geräts (additional_info)

Wird als Beschreibung des Things in FROST übernommen. Ist keine Beschreibung gepflegt, wird stattdessen der Gerätename verwendet.

Beschreibung des Standort‑Assets (additional_info)

Wird als Beschreibung der Location in FROST übernommen. Ist keine Beschreibung gepflegt, wird stattdessen der Asset‑Name verwendet.

Geräteattribut device_definition

Sollte eine URL zu einem Datenblatt (z. B. als PDF) enthalten und wird als metadata des FROST‑Sensors übernommen. Ist das Attribut nicht gepflegt, wird stattdessen der Platzhaltertext „no device definition maintained“ gesetzt.

Geräteattribut <telemetrie_key>_uom

Überschreibt für dieses eine Gerät die Default UOM eines Telemetrie‑Schlüssels. Der Wert muss dem key eines bestehenden Eintrags unter Unit of Measurement Keys in der Zuordnungspflege entsprechen.

Alle sonstigen Geräteattribute werden unverändert als properties des Things in FROST übernommen.

Gerät veröffentlichen

Ein Gerät wird veröffentlicht, indem es in ThingsBoard der Entitätsgruppe (Entity Group) publish-to-frost hinzugefügt wird.

  1. Öffnen Sie das gewünschte Gerät in ThingsBoard.

  2. Fügen Sie es der Entitätsgruppe publish-to-frost hinzu.

  3. Die Rule Chain des Adapters setzt daraufhin automatisch das Server‑Attribut publish_to_frost = true am Gerät.

  4. Sobald das nächste Telemetrie‑Datenpaket des Geräts eintrifft, legt der Adapter – sofern noch nicht vorhanden – das Thing, die zugehörige Location, den Sensor sowie je Telemetrie‑Schlüssel einen Datastream in FROST an und beginnt, Observations zu erzeugen.

Die eigentliche Anlage in FROST erfolgt erst mit der ersten Telemetrie‑Nachricht nach der Aufnahme in die Gruppe, nicht durch das Hinzufügen zur Gruppe selbst.

Fehler werden als Alarm in ThingsBoard sichtbar

Der Adapter meldet einen Fehler an die Rule Chain zurück, die ihn daraufhin als Alarm auf dem auslösenden Gerät anlegt. Jeder der vier REST‑Knoten hat dafür seinen eigenen Alarmtyp, alle mit der Schwere MAJOR:

Alarmtyp Ausgelöst durch

FROST telemetry export failed

eine Telemetrie‑Nachricht, die nicht exportiert werden konnte

FROST device update failed

eine Änderung am Gerät, die nicht übertragen werden konnte

FROST device deletion failed

ein Gerät, das nicht aus FROST entfernt werden konnte

FROST asset update failed

eine Änderung am Standort‑Asset, die nicht übertragen werden konnte

Die Alarm‑Details tragen status, statusCode und error — also den Grund, den der Adapter in seiner Antwort genannt hat. Damit lässt sich in aller Regel schon in ThingsBoard erkennen, woran es lag, ohne in die Protokolle des Adapters zu sehen.

Der Alarm entsteht in der Rule Chain, nicht im Adapter. Fehlt in einer von Hand gebauten Rule Chain die Failure‑Verdrahtung eines REST‑Knotens auf seinen Alarmknoten, verschwindet der zugehörige Fehler spurlos.

Gerät aus FROST entfernen

Wird das Gerät wieder aus der Entitätsgruppe publish-to-frost entfernt, geschieht Folgendes:

  1. Das Server‑Attribut publish_to_frost wird am Gerät gelöscht.

  2. Der Adapter löscht das zugehörige Thing vollständig aus dem FROST‑Server – inklusive aller zugehörigen Datastreams und Observations.

Das Entfernen aus der Gruppe pausiert die Veröffentlichung nicht nur, sondern löscht den kompletten Datenbestand des Geräts in FROST unwiderruflich. Soll die Historie erhalten bleiben, darf das Gerät nicht aus der Gruppe entfernt werden.

Verhalten bei nachträglichen Änderungen

Solange sich ein Gerät in der Gruppe publish-to-frost befindet, werden Änderungen am Gerät in ThingsBoard (z. B. Attribute, Beschreibung, Zuordnung zu einem anderen Standort‑Asset) automatisch an FROST übertragen: Beschreibung, properties und – falls sich das verknüpfte Standort‑Asset geändert hat – auch die Location des Things werden aktualisiert.

Nicht automatisch aktualisiert werden dagegen bereits angelegte Datastreams bzw. der Sensor. Das bedeutet insbesondere:

  • Eine Änderung des Geräteprofils wirkt sich nicht auf bereits bestehende Datastreams aus.

  • Ein nachträglich gesetztes oder geändertes Attribut <telemetrie_key>_uom ändert die Unit of Measurement eines bereits bestehenden Datastreams nicht rückwirkend.

Die Unit of Measurement eines bereits bestehenden Datastreams lässt sich unabhängig davon jederzeit manuell über den Eintrag Units of Measurement in der Zuordnungspflege anpassen; eine dort vorgenommene Umbenennung wird automatisch an die betroffenen FROST‑Datastreams übertragen.

Neu hinzukommende Telemetrie‑Schlüssel eines bereits veröffentlichten Geräts erhalten dagegen ganz normal einen neuen Datastream auf Basis der zu diesem Zeitpunkt gültigen Zuordnungen.

Besonderheiten bei Standort‑Assets (building)

Änderungen an einem building‑Asset (z. B. eine geänderte lat/lon‑Position) werden – anders als bei Geräten – unabhängig von jeder Gruppenzugehörigkeit immer an FROST übertragen.

Eine solche Aktualisierung wirkt sich jedoch nur aus, wenn zu diesem Asset bereits eine Location in FROST existiert. Diese Location wird ausschließlich als Nebeneffekt der Veröffentlichung eines Geräts angelegt, das auf dieses Asset verweist – ein eigenständiges „Veröffentlichen“ eines Standort‑Assets ohne zugehöriges Gerät gibt es nicht.

Daten kommen nicht in FROST an

Die drei häufigsten Ursachen lassen sich allein von ThingsBoard aus unterscheiden:

Beobachtung Wahrscheinliche Ursache Nächster Schritt

Am Gerät steht ein Alarm FROST … failed

Der Adapter oder der FROST‑Server hat die Nachricht abgelehnt.

Die Alarm‑Details lesen: statusCode und error nennen den Grund. Ein 404 bedeutet, dass der Slug in der Rule‑Chain‑URL zu keiner Mandantenzeile passt; ein 502, dass ein Fremdsystem nicht erreichbar war oder die Zugangsdaten des Mandanten nicht mehr gelten — beides zu prüfen über Test connection auf der Seite Mandanten.

Kein Alarm, und in FROST steht überhaupt nichts zu diesem Gerät

Die Nachricht hat den Adapter nie erreicht.

Prüfen, ob das Gerät in der Gruppe publish-to-frost ist und das Server‑Attribut publish_to_frost gesetzt wurde. Trifft beides zu, filtert die Rule Chain die Nachricht vorher aus — die ausgelieferte Chain enthält dafür einen Filterknoten (siehe Rule Chain je Mandant verteilen).

Kein Alarm, Thing und Datastreams stehen in FROST, aber ein einzelner Messwert fehlt

Für diesen Telemetrie‑Schlüssel gibt es keinen Eintrag unter Telemetry Keys.

Den Schlüssel unter Telemetry Keys anlegen. Der Wert wird bis dahin stillschweigend verworfen — es entsteht weder ein Fehler in ThingsBoard noch ein Alarm, nur ein Debug‑Eintrag im Protokoll des Adapters.
Ob in einem Mandanten überhaupt noch Daten ankommen, zeigt die Spalte Connection Status auf der Seite Mandanten: sie nennt nach einem Klick auf Test connection den Zeitpunkt der neuesten Observation in dessen FROST‑Server.

Zuordnungen pflegen: ThingsBoard‑Telemetrie → SensorThings API

Der Thingsboard Frost Adapter bringt eine schlanke Weboberfläche mit, über die sich die Zuordnungen zwischen ThingsBoard‑Telemetrie und der SensorThings API (FROST‑Server) pflegen lassen.

Diese Zuordnungen entscheiden, was aus einem Telemetrie‑Schlüssel in FROST wird: welche Observed Property er misst, in welcher Unit of Measurement, und wie ein einzelnes Gerät diese für sich überschreiben kann (Unit of Measurement Key). Ohne passende Zuordnung wird ein Messwert stillschweigend verworfen.

Sie gelten mandantenübergreifend: Sie werden einmal gepflegt und gelten für alle Mandanten gleichermaßen.

Zugriff auf die Oberfläche

Die Verwaltungsoberfläche wird als eigene Streamlit‑Anwendung bereitgestellt und ist getrennt vom eigentlichen Adapter‑Backend erreichbar. Beim Aufruf ist ein Login erforderlich; ohne gültige Anmeldung wird lediglich eine Login‑Seite angezeigt. Über den Button Logout in der Seitenleiste kann die Sitzung jederzeit beendet werden.

Nach der Anmeldung erscheint links eine Navigation mit fünf Seiten, in dieser Reihenfolge:

  • Tenants – die Mandanten des Adapters; beschrieben unter Mandanten verwalten

  • Units of Measurement – z. B. Grad Celsius, ppm

  • Unit of Measurement Keys – Schlüssel, mit denen ein Gerät die Default UOM überschreibt

  • Observed Properties – z. B. Temperatur, CO₂

  • Telemetry Keys – Zuordnung von ThingsBoard‑Telemetrie‑Schlüsseln zu Observed Property und Default UOM

Die vier letztgenannten Seiten sind Gegenstand dieser Seite.

Bedienung der Tabellen

Alle vier Seiten folgen demselben Muster:

  1. Über der Tabelle steht der Button Save.

  2. Die vorhandenen Einträge werden in einer editierbaren Tabelle angezeigt.

  3. Neue Zeilen können am Ende der Tabelle hinzugefügt werden (Klick in die letzte, leere Zeile).

  4. Bestehende Zellen lassen sich direkt durch Doppelklick bearbeiten.

  5. Zeilen können ausgewählt und über das Kontextmenü der Tabelle (Papierkorb‑Symbol) gelöscht werden.

  6. Erst ein Klick auf Save überträgt alle Änderungen (Anlegen, Bearbeiten, Löschen) an das Backend.

Ist noch kein Eintrag vorhanden, zeigt die Seite stattdessen den Hinweis „No data to display.“ an.

Änderungen werden erst mit Save wirksam. Ein Neuladen der Seite ohne vorheriges Speichern verwirft alle Eingaben.

Wo eine Zuordnung auf einen bestehenden Eintrag einer anderen Seite verweist, geschieht das über ein Auswahlfeld. Ein Wert, den es dort nicht gibt, lässt sich damit gar nicht erst eintragen.

Die vier Seiten

Units of Measurement

Verwaltet die Units of Measurement, die Datastreams im FROST‑Server zugeordnet werden. Die Tabelle hat drei Spalten — name, symbol und definition —, wobei definition die URL zur formalen Definition der Unit of Measurement aufnimmt (z. B. ein QUDT‑Eintrag).

Unit of Measurement Keys

Ordnet einen Schlüssel einer bestehenden Unit of Measurement zu.

Spalte Bedeutung

UOM Key

Der Schlüssel, den ein Gerät im Attribut <telemetrie_key>_uom angibt

UOM Name

Die zugeordnete Unit of Measurement, ausgewählt aus den Einträgen der Seite Units of Measurement

Damit überschreibt ein einzelnes Gerät die Default UOM eines Telemetrie‑Schlüssels: Trägt es das Attribut temperature_uom mit dem Wert degF, wird für dieses Gerät der Datastream in Grad Fahrenheit angelegt statt in der unter Telemetry Keys hinterlegten Default UOM. Die Wirkung tritt bei der Anlage des Datastreams ein und nicht rückwirkend; siehe Gerät an FROST veröffentlichen.

Observed Properties

Verwaltet die Observed Properties.

Spalte Bedeutung

Observed Property Name

Der Name der Observed Property; darf nur einmal vorkommen

Description

Eine Beschreibung

URL to definition

Die URL zur formalen Definition

Alle drei Felder sind Pflichtfelder.

Diese Seite wird einmal gepflegt und gilt für alle Mandanten: Beim Speichern schreibt der Adapter die Änderung zunächst in seine eigene Datenbank und überträgt sie anschließend in den FROST‑Server jedes Mandanten. Ist einer davon gerade nicht erreichbar, bleibt die Änderung trotzdem gespeichert, und ein Hinweis nennt die nicht erreichten Mandanten — nachgeholt wird sie mit Sync observed properties auf der Seite Tenants.

Telemetry Keys

Ordnet einen ThingsBoard‑Telemetrie‑Schlüssel einer Observed Property und einer Default UOM zu. Diese Seite ist der Schalter, der darüber entscheidet, ob ein Messwert überhaupt in FROST erscheint.

Spalte Bedeutung

Telemetry Key

Der Telemetrie‑Schlüssel, so wie er in ThingsBoard heißt

Default UOM Name

Die Default UOM, ausgewählt aus den Einträgen der Seite Units of Measurement

Observed Property Name

Die Observed Property, ausgewählt aus den Einträgen der Seite Observed Properties

Alle drei Felder sind Pflichtfelder. Beide Zuordnungen sind Auswahlfelder, eine nicht existierende Observed Property oder Unit of Measurement lässt sich also nicht eintragen.

Schutz vor inkonsistenten Zuordnungen

Damit die Zuordnungen nicht in einen inkonsistenten Zustand geraten, prüft das Backend beim Speichern automatisch, ob ein Eintrag noch an anderer Stelle verwendet wird. Ist das der Fall, wird die Änderung abgelehnt und eine Fehlermeldung angezeigt statt der Eintrag stillschweigend zu löschen oder zu ändern.

Folgende Regeln gelten:

  • Eine Unit of Measurement kann nicht gelöscht werden, solange sie noch von einem Telemetry Key, einem Unit of Measurement Key oder einem Datastream im FROST‑Server irgendeines Mandanten verwendet wird. Auch ein Mandant, der gerade nicht erreichbar ist, verhindert das Löschen — die Meldung nennt ihn.

  • Eine Observed Property kann nicht gelöscht werden, solange sie noch von einem Telemetry Key oder von einem Datastream im FROST‑Server irgendeines Mandanten verwendet wird. Auch ein Mandant, der gerade nicht erreichbar ist, verhindert das Löschen — „nicht erreichbar“ ist kein Beleg dafür, dass dort nichts daran hängt. Ein Löschen zu erzwingen ist nicht vorgesehen: Für einen endgültig stillgelegten Mandanten ist der Weg, dessen Zeile auf der Seite Tenants zu löschen.

  • Ein Telemetry Key kann nicht gelöscht werden, solange im FROST‑Server irgendeines Mandanten noch ein Datastream dafür existiert — auch nicht, solange einer dieser Mandanten nicht erreichbar ist. Auch hier nennt die Meldung den Mandanten.

Umbenennungen und ihre Nachwirkung in FROST

Wird eine Unit of Measurement oder ein Telemetry Key umbenannt, überträgt der Adapter die Änderung automatisch auf alle betroffenen Datastreams im FROST‑Server jedes Mandanten. Wird eine Observed Property umbenannt, wird der neue Name auf alle Telemetry Keys übertragen, die darauf verweisen, sowie auf die Kopie in jedem Mandanten‑FROST — dort auf denselben Datensatz, es entsteht also kein zweiter Eintrag.

Schlägt die Übertragung zu FROST fehl, bleibt die lokale Änderung bestehen, und ein Hinweis nennt die nicht erreichten Mandanten. Wie es dann weitergeht, hängt davon ab, was umbenannt wurde:

Umbenannt Wiederholung

Observed Property

Sync observed properties auf der Seite Tenants holt die Übertragung nach.

Unit of Measurement, Telemetry Key

Es gibt keine. Diese Werte stehen nur in den Datastreams selbst, und sobald der Adapter den neuen Namen führt, findet keine Abfrage die alten Datastreams mehr. Der Hinweis nennt deshalb den Mandanten, in dessen FROST‑Server Datastreams noch den alten Namen tragen; welche das sind, steht im Protokoll. Dort müssen sie von Hand korrigiert werden.

Mandanten verwalten

Die Seite Tenants der Verwaltungsoberfläche führt die Mandanten des Adapters. Jeder Mandant exportiert in seinen eigenen FROST‑Server; das Löschen eines Mandanten entfernt nur die Registry‑Zeile — seine FROST‑Instanz und jede bereits exportierte Observation bleiben unberührt.

Diese Seite beschreibt, was die Oberfläche tut und was sie ablehnt. Alles, was einen Shell‑Zugang voraussetzt — eine FROST‑Instanz samt Datenbank und Keycloak‑Client bereitstellen, die Rule Chain je Mandant verteilen, Wiederherstellung nach Fehlbedienung — steht in den Betriebsanleitungen und wird von hier aus an der passenden Stelle verlinkt.

Aufbau der Seite

Über der Tabelle stehen zwei Buttons:

  • Save überträgt alle Änderungen (Anlegen, Bearbeiten, Löschen) an das Backend.

  • Check all connections prüft alle Mandanten auf einmal.

Die Tabelle selbst hat folgende Spalten:

Spalte Bedeutung

Slug

Die unveränderliche Kennung des Mandanten. Sie steht in der Rule‑Chain‑URL seines ThingsBoard, deshalb lässt sie sich nachträglich nicht ändern.

Display Name

Der Anzeigename des Mandanten. Frei änderbar.

FROST Server URL

Der Service‑Root des FROST‑Servers dieses Mandanten. Eindeutig — ein FROST‑Server gehört zu genau einem Mandanten.

Keycloak Client ID

Der Keycloak‑Client, mit dem sich der Adapter gegenüber diesem FROST‑Server authentifiziert.

ThingsBoard API Key
(nur bei Professional Edition)

Der Zugang zum ThingsBoard des Mandanten. Wird nie zurückgeliefert; die Spalte ist beim Rendern immer leer. Leer lassen bedeutet „den gespeicherten Key behalten“, eine Eingabe ersetzt ihn. Für einen neuen Mandanten ist er Pflicht.

ThingsBoard Username
(nur bei Community Edition)

Der ThingsBoard‑Benutzer, als der die Geräte dieses Mandanten gelesen werden. Kein Geheimnis, wird deshalb angezeigt und lässt sich wie jedes andere Feld ändern.

ThingsBoard Password
(nur bei Community Edition)

Das Passwort dieses Benutzers. Verhält sich wie der API Key: nie zurückgeliefert, beim Rendern leer, leer lassen behält das gespeicherte, eine Eingabe ersetzt es.

Connection Status

Das Ergebnis der letzten Prüfung. Nicht editierbar.

Test connection

Ein Button je Zeile: prüft diesen einen Mandanten.

Sync observed properties

Ein Button je Zeile: überträgt die Observed Properties in den FROST‑Server dieses Mandanten.

Unterhalb der Tabelle erscheinen Fehlermeldungen und Warnungen zu einzelnen Zeilen — der Grund eines fehlgeschlagenen Checks steht dort, nicht in der Tabellenzelle.

Welche ThingsBoard‑Felder die Tabelle zeigt, hängt davon ab, gegen welche ThingsBoard‑Edition der Adapter konfiguriert ist: Die Professional Edition meldet sich mit einem API Key an, die Community Edition mit Benutzername und Passwort — sie kennt keine API‑Key‑Anmeldung. Die Seite fragt den Adapter danach; einstellen lässt sich das hier nicht (siehe Wechsel der ThingsBoard‑Edition).

Zugangsdaten der jeweils anderen Edition weist der Adapter mit einer Fehlermeldung ab, statt sie zu speichern — sie könnten nie funktionieren.

Einen Mandanten aufnehmen

Voraussetzung ist, dass sein FROST‑Server samt Datenbank und Keycloak‑Client bereitsteht (siehe Betriebsanleitungen) und sein ThingsBoard‑Mandant angelegt ist.

  1. Eine neue Zeile am Ende der Tabelle ausfüllen. Alle angezeigten Eingabefelder sind Pflicht; fehlt eines, nennt eine Meldung die fehlenden Felder und die Zeile wird nicht angelegt.

  2. Save klicken.

  3. Danach die Rule Chain im ThingsBoard des Mandanten einrichten und den Slug in ihren vier REST‑Knoten eintragen — siehe Rule Chain je Mandant verteilen.

Ein Neustart des Adapters ist an keiner Stelle nötig. Die Rule Chain legt der Betreiber selbst an — der Adapter schreibt nie nach ThingsBoard.

Was beim Speichern geschieht

Zuerst prüft das Backend, ob die eingetragenen Angaben tatsächlich funktionieren: Keycloak‑Token, FROST‑Service‑Root und ThingsBoard‑Login. Schlägt eine der Prüfungen fehl, wird die Zeile nicht angelegt bzw. nicht geändert, und die fehlgeschlagene Prüfung wird benannt. Ein Mandant lässt sich daher nicht registrieren, solange sein FROST gerade nicht erreichbar ist.

Ist die Prüfung bestanden, folgt die Übertragung der Observed Properties in den neuen FROST‑Server. Scheitert sie, bleibt die Zeile trotzdem bestehen und es erscheint ein Hinweis: Die fehlenden Einträge entstehen spätestens bei der ersten Telemetrie des Mandanten, und Sync observed properties holt sie sofort nach.

Wird bei einem bestehenden Mandanten die FROST Server URL geändert, läuft dieselbe Übertragung automatisch für den neuen Server; jede andere Änderung löst sie nicht aus.

Der Slug lässt sich nicht ändern

Der Slug steht in der Rule‑Chain‑URL des jeweiligen ThingsBoard. Eine Umbenennung würde dort jede Telemetrie‑Nachricht ins Leere laufen lassen, deshalb lehnen sowohl die Oberfläche als auch die API sie ab. Umbenennen heißt löschen und neu anlegen; siehe Einen Mandanten umbenennen.

Einen Mandanten prüfen

Jede Zeile hat einen Button Test connection, über der Tabelle steht Check all connections für alle Zeilen auf einmal. Beide führen dieselbe Prüfung aus und schreiben ihr Ergebnis in die Spalte Connection Status:

Anzeige Bedeutung

not checked

Für diesen Mandanten wurde in dieser Sitzung noch nichts geprüft.

✅ Keycloak ✅ FROST ✅ ThingsBoard · newest observation <Zeitpunkt>

Alle drei Verbindungen stehen, und der genannte Zeitpunkt ist der neueste phenomenonTime im FROST‑Server dieses Mandanten — der einzige Beleg dafür, dass dort tatsächlich Daten ankommen.

… · no observations yet

Die Verbindungen stehen, aber im FROST‑Server dieses Mandanten liegt noch keine einzige Observation.

ein ❌ bei einer der drei Prüfungen

Diese Verbindung steht nicht. Der Grund erscheint als Fehlermeldung unterhalb der Tabelle.

Geprüft wird ausschließlich auf Klick: Die Liste selbst lädt ohne einen einzigen Aufruf an ein Fremdsystem und bleibt damit auch dann schnell, wenn eines davon ausgefallen ist.

Observed Properties abgleichen

Der Button Sync observed properties überträgt die Seite Observed Properties in den FROST‑Server dieser Zeile: fehlende Einträge werden angelegt, vorhandene auf den aktuellen Stand gebracht. Gelöscht wird dort nichts — auch Einträge nicht, die der Adapter nicht kennt.

Der Abgleich ist beliebig oft wiederholbar. Er ist zugleich der Einrichtungsschritt für einen neuen Mandanten und die Wiederholung, wenn eine Änderung einen Mandanten nicht erreicht hat.

Gelingt der Abgleich, erscheint kurz eine Bestätigung. Ist der FROST‑Server nicht erreichbar, erscheint eine Fehlermeldung mit dem betroffenen Mandanten; der Abgleich lässt sich dann einfach erneut anstoßen.

Warnung „unknown to the adapter but in use“

Findet der Abgleich im FROST‑Server einen Eintrag, den der Adapter nicht kennt, an dem aber Datastreams hängen, bleibt unter der Tabelle eine Warnung mit dessen Namen stehen. Das bedeutet, dass diese Observed Property dort doppelt vorliegt: einmal unter der Verwaltung des Adapters, einmal daneben mit älteren Messdaten.

Der Adapter greift hier bewusst nicht ein — ein Löschen würde in SensorThings auch die Datastreams und alle Observations mitnehmen. Was mit dem Eintrag geschehen soll, entscheidet die Administration von Hand im FROST‑Server.

Einen Mandanten stilllegen

Ein Mandant lässt sich erst löschen, wenn in seinem FROST‑Server kein Gerät mehr steht. Die Reihenfolge ist deshalb verbindlich:

  1. Die Geräte des Mandanten in ThingsBoard aus der Gruppe publish-to-frost entfernen. Der Adapter räumt daraufhin die zugehörigen Things im FROST‑Server ab, samt ihrer Datastreams und Observations.

  2. Die Zeile auf dieser Seite auswählen und mit Save löschen. Steht dort noch ein Gerät, oder ist der FROST‑Server nicht erreichbar, wird das Löschen mit einer Meldung abgelehnt — auch „nicht erreichbar“ verhindert es, denn es ist kein Beleg dafür, dass dort nichts mehr steht. Ein Erzwingen ist nicht vorgesehen.

  3. Erst danach die FROST‑Instanz, ihre Datenbank und ihren Keycloak‑Client abbauen. Dieser Schritt findet außerhalb der Oberfläche statt; siehe Mandant stilllegen.

Wird Schritt 3 vor Schritt 2 ausgeführt, lässt sich der Mandant über die Oberfläche nie mehr löschen: Die Löschprüfung fragt seinen FROST‑Server und bekommt keine Antwort mehr.

Das trifft nicht nur diesen Mandanten — die tote Zeile lässt danach auch jedes Löschen einer Observed Property, einer Unit of Measurement und eines Telemetry Keys dauerhaft scheitern, weil auch diese Prüfungen über alle Mandanten laufen. Die Wiederherstellung erfordert einen Eingriff in die Datenbank des Adapters; siehe Wiederherstellung nach falscher Reihenfolge.
Ein Mandant, der nur vorübergehend nichts exportieren soll, muss nicht gelöscht werden. Eine Zeile ohne Telemetrieverkehr kostet nichts.

Einen Mandanten umbenennen

Gemeint ist der Slug; der Display Name ist jederzeit frei änderbar. Ein Slug wird nicht umbenannt, sondern der Mandant gelöscht und neu angelegt:

  1. Die Schritte 1 und 2 aus Einen Mandanten stilllegen ausführen — ohne Schritt 3, die FROST‑Instanz bleibt stehen.

  2. Eine neue Zeile mit dem neuen Slug und derselben FROST Server URL anlegen.

  3. Den neuen Slug in den vier REST‑Knoten der Rule Chain dieses ThingsBoard eintragen.

Dabei bleiben die Observed‑Property‑Kopien des alten Slugs im FROST‑Server liegen: Der Adapter legt beim Neuanlegen eigene Kopien an und löscht nie etwas. Sie stören nichts, tauchen aber in der öffentlichen SensorThings‑Sammlung doppelt auf, und mit jedem weiteren Umbenennen wächst der Stapel.

Sie sollten deshalb von Hand im FROST‑Server entfernt werden, solange noch klar ist, welcher Satz der aktuelle ist — zu entfernen sind nur Einträge, an denen keine Datastreams hängen. Das Vorgehen samt der Abfrage, die den aktuellen Satz von den verwaisten unterscheidet, steht unter Umbenennen in den Betriebsanleitungen.