Metainformationen zur Seite

MQTT-Gateway - Generischer POST / GET / JSON Empfänger

Als "Generischer Empfänger" ist gemeint, dass ein beliebiges (nicht MQTT-kompatibles) Gerät einen beliebigen HTTP-Request an die hier genannten URL's absetzen kann. Der generische Empfänger (engl. receiver) parst die Eingangsdaten und sendet diese via MQTT Gateway an den MQTT Broker und folglich an den Miniserver.

Der Verwendungszweck ist folgender:

  • Ein beliebiges Gerät / Software kann bei einem Event eine frei definierbare URL ausführen und sendet mit dem Request seine Daten mit. Bezeichnet wird das beispielsweise als "HTTP-Event" oder "Callback".
  • Der generische Empfänger des Plugins empfängt diese Daten, wandelt sie um und übermittelt sie an den MQTT-Broker.
  • Mit der Subscription im MQTT Gateway können die Daten an den Miniserver weitergesendet werden.

Unterstützt werden automatisch: (keine Konfiguration erforderlich!)

  • Als Querystring übermittelte Daten (GET-Request)
  • Als Formular übermittelte Daten (POST-Request)
  • als JSON übermittelte Daten

Einrichtung

Am Gerät bzw. der Software

Es gibt zwei Empfänger-URLs des Plugins:

  • http://loxberry/system/tools/mqtt/receive.php - Eingehende Daten werden mit dem RETAIN-Flag weitergegeben.
  • http://loxberry/system/tools/mqtt/receive_pub.php - Eingehende Daten als PUBLISH weitergegeben (kein retain).

In der Konfiguration des Geräts bzw. der Software muss eine der URLs eingetragen werden. Es ist keine Authentifizierung erforderlich.

Im MQTT Gateway Plugin

Alle eingehenden Daten werden im topic rcvr/# gesendet. Dieses Topic muss bei den Subscriptions eingetragen werden.

Datenmodell

Die Topicstruktur sieht folgendermaßen aus:

Topic Topic via Gateway (HTTP Virtual Inputs) Beschreibung
rcvr/<HOST>/REMOTEADDR rcvr_<HOST>_REMOTEADDR IP-Adresse des Absenders
rcvr/<HOST>/REMOTEHOST rcvr_<HOST>_REMOTEHOST Hostname des Absenders
rcvr/<HOST>/loxtime rcvr_<HOST>_loxtime Loxone Timestamp der letzten Übermittlung
rcvr/<HOST>/GET/... rcvr_<HOST>_GET_... Alle Querystring-Parameter (GET-Request)
rcvr/<HOST>/POST/... rcvr_<HOST>_POST_... Alle Formulardaten (POST-Request)
rcvr/<HOST>/BODY/... rcvr_<HOST>_BODY_... Alle als JSON im Content übertragene Daten

<HOST> entspricht (je nach Verfügbarkeit in dieser Reihenfolge):

  • Der Hostname des Absenders - bei vollem Domänennamen (FQDN) wird nur der kurze Hostname verwendet
  • Die IP-Adresse (IPv4 oder IPv6)
  • local wenn keines der anderen Kennzeichen gesetzt ist.

Die Datenstruktur von GET- und POST-Daten ist flach. Eingehende JSON-Daten hingegen werden in ihrer Hierarchie aufgelöst.

Am besten ist es, sich die eingehenden Daten in der Incoming Overview anzusehen.

Besonderheiten und Hinweise

  • Wenn ein HTTP-Request lokal am LoxBerry abgesetzt wird, kann der <HOST> "127.0.0.1" oder "::1" sein (lokale IP-Adresse).
  • POST- und GET-Daten haben keine Hierarchie. Der Receiver erzeugt daher eine Hierarchiestufe durch den Absender (<HOST>). Jeder Datensatz, der vom <HOST> gesendet wird, überschreibt daher den letzten Datensatz vom gleichen Host. Das muss bei der Programmierung in der Loxone Config berücksichtigt werden.
  • Dementsprechend kann es notwendig sein, bei den Eingangsdaten das "Reset after send" flag zu setzen, um Impulse zu generieren.
  • Die "Conversions" funktionieren identisch wie mit anderen Daten.

Fehlersuche

Bitte das Logfile "Receiver" kontrollieren, welche Daten hereinkommen und was bei der Übertragung passiert.

Scripte kopieren und anpassen

Man kann die Scripts ohne Probleme kopieren und z.B. das Topic anpassen, wenn man aus dem Eingangsdaten z.B. eine Hierarchie auslesen kann.

Dazu folgendermaßen vorgehen:

Kopiere die beiden Dateien aus /opt/loxberry/webfrontend/html/plugins/mqttgateway/receive*.php nach /opt/loxberry/webfrontend/legacy/receive*.php

Die Aufruf-URL ist dann:

http://loxberry/legacy/receive.php bzw. http://loxberry/legacy/receive_pub.php

Erstelle keine Kopien innerhalb des LoxBerry Verzechnisses außerhalb von legacy! Diese würden bei einem LoxBerry-Update gelöscht werden.