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.