JSON Selektoren für Nutzung mit MQTT
- Matthias Schmidt
- Stefan Werner (Org-Admin)
Um aus Datenstrukturen wie JSON einzelne Werte - für die Nutzung im Objektsystem - extrahieren zu können, nutzen Sie bitte das Leistungsmerkmal “Selektor”.
Der Selektor ist eine Zeichenkette, den Sie im entsprechenden Feld des Eingabeassistenten angeben.
Dieser Selektor dient dazu, einen spezifischen Wert, der in einem verschachtelten JSON enthalten ist, entsprechend der Position in der Datenstruktur zu selektieren (= adressieren), damit der Timberwolf Server diesen Wert mit einem einzelnen TWS Objekt verknüpfen kann.
Für die selbe JSON Datenstruktur können mehrere Eintragungen (= Transaktionen) angelegt werden. Auf diese Weise können die Positionen mehrerer spezifischer Elemente in einer JSON Dateistruktur definiert und mit jeweils einem TWS Objekt verknüpft werden.
Hinweis zu TWS-Objekt und JSON-Objekt
JSON Datenstrukturen ermöglichen verschachtelte Dateninhalte. Diejenige Struktur, die in geschweiften Klammern {} eingeschlossen ist, wird in der JSON Syntax als ‘Objekt’ bezeichnet. Der Inhalt eines solchen JSON Objektes wird als Liste von ‘Eigenschaften’ bezeichnet. Bitte verwechseln Sie die JSON-Objekte nicht mit dem Objekten des Timberwolf Servers in der folgenden Beschreibung.
Senderichtung beachten: Bitte beachten Sie, dass Selektoren sowohl in eingehender als auch in ausgehender Richtung (von / zum externen Gerät) genutzt werden können.
Das bedeutet bei ausgehender Richtung, dass aus den Objektverknüpfungen und den angegebenen Selektoren eine JSON-Dateistruktur erzeugt wird, die an das entfernte Gerät gesandt wird. Beachten Sie hierzu unbedingt die entsprechenden Einstellungen für den Auslöser. Bei “gemeinsamen Auslöser” werden alle Transaktionen zusammen ausgeführt, damit eine zusammenhängende JSON Datenstruktur erzeugt und diese komplett an das entfernte Gerät gesendet.
NEU! Unterstützung für JSON Arrays als Startelemente bei der Abfrage
Bis Firmware V 4.0 IP 5 wurden als Startobjekte in der JSON Struktur nur einzelne Objekte unterstützt.
Ab Firmware V 4.0 IP 5 darf ein Selektor auch mit [ beginnen. Die eckigen Klammern können eine Zahl für den Array Index oder für einen Filter (siehe unten) enthalten.
Senden von JSON Arrays
Bis Firmware V 4.0 IP 5 können Selektoren, die ein Array erzeugen, nicht zum Erzeugen einer JSON Struktur beim Senden von Daten genutzt werden. Ab Firmware V 4.0 IP 5 ist dies nun möglich.
Übersicht
Einfacher Selektor
In diesem Beispiel befinden sich alle Eigenschaften (Elemente in dem JSON Objekt als Schlüssel-Werte Paare) auf einer Ebene und diese JSON Datenstruktur besteht nur aus einem JSON Objekt, welches durch { } gekennzeichnet ist.
{
"ison": false,
"mode": "white",
"brightness": 6
}Beispiel Möchte man auf den Helligkeitswert, der in der oben dargestellten JSON Datenstruktur mit dem Schlüssel brightness definiert ist, zugreifen, muss nur brightness im Feld Selektor eingetragen werden.
NEU (IP4 V4) Beinhaltet der Schlüssel andere Zeichen als Buchstaben, Zahlen, Unterstrich und Minus-Zeichen (z.B. einen Doppelpunkt), dann ist dieser Schlüssel in Anführungszeichen in das Feld Selektor einzutragen. Beispiel: "test: 3"
Selektor bei verschachtelten Datenstrukturen
Hier soll auf das erste Ereignis (der Wert ‘sleep’ mit dem Schlüssel eventaus dem ersten Element in dem Array events) zugriffen werden.
{
"src": "shellyplusht-c049ef8ad9c8",
"dst": "shellyplusht-c049ef8ad9c8/events",
"method": "NotifyEvent",
"params": {
"ts": 1677071174.05,
"events": [
{
"component": "sys",
"event": "sleep",
"ts": 1677071174.05
}
]
}
}Beispiel
Das JSON-Objekt params enthält das JSON-Array events. Mit dem Selektor
params.eventskönnen die im Array enthaltenen Objekte angesprochen werden.Zwischen den Array-Begrenzern [ ] wird eine Liste von Elementen gleichen oder verschiedenen Typs in der JSON Datenstruktur eingeschlossen. Mit
params.events[0]wird das erste Element aus diesem Array gewählt (im obigen Beispiel gibt es im Arrayeventsnur ein Element, hier vom Typ Objekt).Um die in dem Element enthaltene Eigenschaft mit dem Schlüssel event auszuwählen, lautet der gesamte Selektor:
params.events[0].event(dieser enthält den Wert sleep als Eigenschaft vom Typ Zeichenkette).
Der damit extrahierte Wert sleep wird vom Timberwolf Server an das TWS-Objekt übergeben und dieses kann nun beliebig verknüpft und in anderen Subsystemen weiterverarbeitet werden, beispielsweise durch eine Logik ausgewertet.
Selektor um ein Array aus einer Auflistung anhand eines Wertes auszuwählen
Im vorigen Beispiel ist beschrieben, wie ein Element aus einem JSON-Array über den Index (Zahl entsprechend der Position in der Auflistung im Array, beginnend mit 0) ausgewählt werden kann. Häufig ist die Position von Daten einer JSON Datenstruktur nicht fix und kann sich seitens des fremden Gerätes verändern.
Beispiel In dieser JSON Datenstruktur befindet sich ein JSON-Array mit zwei Elementen. Insofern die Reihenfolge der Elemente durch das sendende Gerät nicht sicher ist, kann man das richtige Element auch anhand des Wertes eines der enthaltenen Elemente in der Selektierung angeben.
In diesem Beispiel wollen wir dasjenige Element aus dem JSON-Array auswählen, das den Wert sys im Schlüssel component enthält.
{
"src": "shellyplusht-c049ef8ad9c8",
"dst": "shellyplusht-c049ef8ad9c8/events",
"method": "NotifyEvent",
"params": {
"ts": 1677071174.05,
"events": [
{
"component": "input:0",
"id": 0,
"event": "single_push",
"ts": 1631266595.44
},
{
"component": "sys",
"event": "sleep",
"ts": 1677071174.05
}
]
}
}Als Selektor ist hierfür params.events[component="sys"].event einzutragen, um damit dasjenige Element aus dem Array events auswählen, welches im Schlüssel component einen bestimmten Wert (hier “sys”) gesetzt hat, um darüber den Wert “sleep” mit dem Schlüssel “event” zu selektieren.
Senden von Daten in einer JSON-Datenstuktur
Über dem Timberwolf Server erfasste oder beispielsweise durch eine Logik weiterverarbeitete Daten können als JSON Datenstruktur, welche mehrere Werte gleichzeitig beinhalten kann, an ein anderes Gerät gesendet werden. Empfänger können etwa Aktoren, andere SmartHome-Produkte oder Cloud-Dienste sein.
In diesem Beispiel wird eine JSON Datenstruktur erzeugt, welches die aktuelle Leistungsaufnahme sowie einzelne Stromflüsse enthält. Das empfangende Gerät erwartet ein JSON Objekt welches den Schlüssel consumption enthält. In consumption befinden sich der Schlüssel total welcher eine Zahl als Wert enthält. Unter phases befindet sich ein Array in dem jedes Element den Stromfluss pro Außenleiter darstellt.
Um die oben dargestellte JSON Datenstruktur zu erzeugen, werden vier Werte benötigt. Hierzu wurden vier publizierende Transaktionen angelegt. Die Gesamtheit der vier Transaktionen erzeugt, abhängig von den Einstellungen für den Auslöser, eine zusammengehörige JSON Datenstruktur. Um diese zu senden, wurde im Beispiel der Auslöser nur für die Transaktion Verbrauch aktiviert und dabei festgelegt dass eine Wertänderung dieses Objektes die Werte alle Transaktionen (hier im Screenshot “Applikation”) dieses Topics aussendet.
Durch die Selektoren consumption.phases[0 ... 2] wird definiert, dass phases eine Array darstellt und an welchen Index die Elemente mit den Schlüsseln und zugehörigen Werte eingesetzt werden sollen.
Wird ein Array Index im Selektor angegeben, bei dem für einen oder mehrere vorherige Indexe kein Wert vorhanden ist, wird für diese leeren Index-Positionen der Wert vom Typ NULL eingefügt. Ein fehlender Wert und damit das automatische Einfügen von NULL-Werten kann aus drei verschiedenen Gründen auftreten:
Es ist keine publizierende Transaktion angelegt, welche den damit nicht definierten Index befüllen würde
Seit dem Start des Subsystems oder dem erstmaligen Anlegen der Transaktion wurde noch kein Wert aus dem Objektsystem an diese publizierende Transaktion gesendet, jedoch hat eine andere Transaktion das Aussenden der Werte aller Transaktionen dieses Topics angefordert
Der Trigger der von der NULL Aussendung betroffenen Transaktion wurde bei der Einrichtung auf das Senden nur bei Aktualisierung dieses Objektwertes beschränkt, damit werden alle anderen Elemente der JSON Datenstruktur ausgelassen