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:
-
Über der Tabelle steht der Button Save.
-
Die vorhandenen Einträge werden in einer editierbaren Tabelle angezeigt.
-
Neue Zeilen können am Ende der Tabelle hinzugefügt werden (Klick in die letzte, leere Zeile).
-
Bestehende Zellen lassen sich direkt durch Doppelklick bearbeiten.
-
Zeilen können ausgewählt und über das Kontextmenü der Tabelle (Papierkorb‑Symbol) gelöscht werden.
-
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 |
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. |