JSON Selektoren für Nutzung mit MQTT

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 Objekt verknüpfen kann.

Für die selbe JSON Struktur können mehrere Eintragungen angelegt werden. Auf diese Weise können die Positionen mehrerer spezifischen Werte in einer JSON Dateistruktur definiert und mit jeweils einem Objekt verknüpft werden.

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 Trigger (bei “gemeinsamen Trigger” werden alle Transaktionen ausgeführt, eine zusammenhängende JSON Datenstruktur erzeugt und diese gesendet)

Übersicht

Einfacher Selektor

In diesem Beispiel befinden sich alle Werte auf einer Ebene und die JSON Datenstruktur besteht nur aus einem 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 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 der Schlüssel in Anführungszeichen in das Feld Selektor einzutragen. Beispiel: "test: 3"

Selektor bei verschachtelten Datenstrukturen

Hier soll auf das erste Ereignis 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.events kö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 Array events nur 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 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 Array mit zwei Elementen. Insofern die Reihenfolge der Elemente nicht sicher ist, kann man anhand der Werte der enthaltenen Elemente eine Selektierung angeben. Hier wollen wir dasjenige Element 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.

{
  "consumption": {
    "total": 343,
    "phases": [
      38.57,
      290.38,
      14.29
    ]
  }
}

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