ZENNER Datahub Howto: Weiterleitungen einrichten am Beispiel MQTT

1. Allgemeines

Zur Weiterleitung des Traffics der eigenen Endgeräte unterstützt der ZENNER Datahub drei verschiedene Netzwerkprotokolle. Abhängig von eigenen Anforderungen und der Architektur des Zielsystems kann aus folgenden Optionen gewählt werden:

• http-Weiterleitung
  • RESTful-API POST an selbstgehosteten Endpunkt
• MQTT
  • Weiterleitung an selbstgehosteten Broker
  • Weiterleitung und Subscriben eines von der Plattform zur Verfügung gestellten Brokers
• AMQP
  • Weiterleitung an selbstgehosteten Broker

2. Einrichten der Weiterleitung

Nachfolgend wird für die drei Weiterleitungsarten beschrieben, wie diese innerhalb der Plattform zu konfigurieren sind und was bei der Nutzung zu beachten ist. Unabhängig vom Typ der Weiterleitung, ist diese einmalig initial im Menüpunkt Management, unter Forwarding durch einen Klick auf den Button „Add new forward rule“ mit den Zugangsdaten des Endpunktes einzurichten.

 

2.1 http-Weiterleitung

2.1.1 Allgemeines

Voraussetzung für die Nutzung der http-Weiterleitung ist ein aus dem Internet erreichbarer Endpunkt mit einer statischen IP-Adresse/URL. Ist die Weiterleitungsregel aktiv, sendet die Plattform bei jedem eingehenden Telegramm einen http POST an die hinterlegte URL. Im Body dieses POST befindet sich ein json-Objekt mit den Nutzdaten sowie den Metainformationen des Empfangs. Dieses ist wie folgt aufgebaut:

 

Weitere, tiefergehende Meta-Informationen wurden im obigen Bild für eine bessere Übersichtlichkeit ausgeblendet.

2.1.2 Konfiguration der Plattform

Nach dem Klick auf „Add new forward rule“ kann in der sich öffnenden Maske im Feld „Name“ frei eine gewünschte Bezeichnung vergeben werden. Als Type wird „HTTP“ ausgewählt. Des Weiteren muss die Ziel-URL des eigenen Endpunkts eingetragen werden. Diese setzt sich, abhängig ob eine Authentifizierung gegenüber dem Endpunkt gewünscht ist oder nicht, wie folgt zusammen:

 

Die Weiterleitung muss anschließend noch für die gewünschten Geräte aktiviert werden (s. Abschnitt 3: Zuweisen der Weiterleitung)

2.1.3 Nutzungsbeispiel mit flask

Eine einfache Möglichkeit die http-Weiterleitung zu nutzen, ist das Aufsetzen eines API-Endpunktes mit flask. Mit wenigen Codezeilen lässt sich damit eine Ziel-URL definieren und den Inhalt des POST-Bodys in eigenem python-Code weiterverarbeiten. Im gezeigten python-Beispiel wird jedes empfangene json-Dokument in ein Log-file geschrieben.

Hier stehen jedoch prinzipiell alle Möglichkeiten offen – vom Zwischenspeichern bspw. in einer MongoDB bis zum direkten Anstoßen einer Aktion, wenn ein bestimmtes Telegramm eintrifft.

2.2 MQTT

2.2.1 Allgemeines

Ist die MQTT-Weiterleitung eingerichtet, published die Plattform Telegramme an einen selbstgehosteten oder von der Plattform zur Verfügung gestellten Broker. Der Anwender kann als „Client“ den jeweiligen Broker subscriben.

Die Nachrichten werden mit QoS 0 (at most once) gepublished – sie werden also weder zwischengespeichert noch wiederholt, sollten sie nicht vom Client abgeholt werden.

Für jedes Gerät wird unterhalb des Basic-Topics eine Unterstruktur mit der jeweiligen DevEUI erzeugt. So finden sich Telegramme des Beispiel Adeunis-Testers 0018B20000FFFFFF unter dem topic:

/basic-topic/devices/0018B20000FFFFFF/up

Unterhalb dieses topics wird zu jedem empfangenen Telegramm ein json-Objekt mit den Da-ten übertragen. Darin sind bspw. folgende keys enthalten:

• payload_raw: Die entschlüsselte FRMPayload – also die Nutzdaten im base64 Format

• counter: Frame-Counter des LoRaWAN-Telegramms

Sollte zum betrachteten Gerät ein Parser in der Plattform hinterlegt sein, werden zusätzlich dazu gerätespezifische, weitere Felder ebenfalls als eigenes topic übertragen. Beim Adeunis-Tester also bspw. der aus dem Telegramm geparste Breitengrad “latitude” und Längengrad “longitude”.

2.2.2 Konfiguration der Plattform

Nach dem Klick auf „Add new forward rule“ kann in der sich öffnenden Maske im Feld „Name“ frei eine gewünschte Bezeichnung vergeben werden. Als Type wird „MQTT“ ausgewählt. Des Weiteren muss die Ziel-URL des gewünschten Brokers eingetragen werden. Diese setzt sich wie folgt zusammen:

Beispiel: 
mqtt://mustermann:Passwort123@mustermannsbroker:1883?base_topic=sensor/lora

Alternativ zur Nutzung eines eigenen Brokers besteht auch die Möglichkeit einen von der Plattform zur Verfügung gestellten Broker zu verwenden. Die dafür benötigten Zugangsdaten können über das Community-Kontaktformular unter Angabe des eigenen Usernamen angefordert werden.

2.2.3 Subscriben des Brokers

Um die Nachrichten entgegennehmen zu können, ist ein geeigneter MQTT-Client nötig. Die Einstellungen zum Subscriben des Plattform-Brokers sind (username und password s. 2.2.2):

Als Client kann bspw. Mosquitto verwendet werden. Der folgende Beispielaufruf gibt alle weitergeleiteten Nachrichten des Accounts aus:

mosquitto_sub -h mqtt.bmz.cloud -p 1883 -t “Mandantenname/#” -P “password” -u “username” -v

2.3 AMQP

2.3.1 Allgemeines

Ist die AMQP-Weiterleitung eingerichtet, published die Plattform Telegramme an einen vom Anwender zur Verfügung gestellten Broker wie bspw. rabbitMQ. Dieser muss aus dem Internet erreichbar sein und über eine statische IP-Adresse/URL verfügen.

Die Plattform published immer an einen zuvor eingerichteten Exchange des Brokers. Dieser Exchange kann wiederum an eine oder mehrere Queues gebunden werden. Zur Weiterverarbeitung können die Daten von diesen Queues subscribed werden.

Die einzelnen Telegramme werden von der Plattform als json-Objekt gepublished. Die Objekte sind dabei wie folgt aufgebaut:

Weitere Meta-Informationen wurden in diesem Screenshot für eine bessere Übersichtlichkeit ausgeblendet.

2.3.2 Konfiguration der Plattform

Nach dem Klick auf „Add new forward rule“ kann in der sich öffnenden Maske im Feld „Name“ frei eine gewünschte Bezeichnung vergeben werden. Als Type wird „AMQP“ ausgewählt. Des Weiteren muss die Ziel-URL des Brokers eingetragen werden. Diese setzt sich wie folgt zusammen:

Die Weiterleitung muss im Anschluss dann noch für die Wunsch-Geräte aktiviert werden (s. Abschnitt 3: Zuweisen der Weiterleitung)

2.3.3 Subscriben des Brokers

Um die Nachrichten entgegennehmen zu können, ist ein geeigneter AMQP-Client nötig.

Als Client kann bspw. pika verwendet werden. Das folgende python-Beispielskript nimmt alle Nachrichten der Queue „hello“ entgegen und bestätigt diese:

3. Zuweisen der Weiterleitung

Es gibt zwei verschiedene Möglichkeiten die Weiterleitung zu nutzen:

3.1 Weiterleitung aller Geräte des Accounts

Es werden alle eingehenden Telegramme von Geräten innerhalb des Accounts weitergeleitet. Zur Einrichtung unter dem Menüpunkt Management/Forwarding bei der im vorherigen Abschnitt erstellten Regel auf „Add“ klicken.

Die neue Regel wird anschließend unter „Already added Forwarding Rules to this Tenant“ angezeigt und kann falls erforderlich über „Delete“ wieder inaktiv geschalten werden.

3.2 Weiterleitungsregel einzelnen Geräten des Accounts zuordnen

Alternativ zu einer globalen Weiterleitung kann die Weiterleitungsregel auch für einzelne Geräte aktiviert werden. Hierzu aus der Geräteliste in die Detailansicht des gewünschten Gerätes wechseln. Im Reiter Forwarding kann die Regel anschließend durch den Button „Add“ für das jeweilige Gerät aktiv geschalten werden.

Bereits vorhandene Einträge werden unter „Already added Forwarding Rules to this Device“ angezeigt und können über „Delete“ wieder inaktiv geschalten werden.

Die Plattform unterstützt auch die Authentifizierung mithilfe von „Basic Authentication“. Username und Passwort müssen hierzu in folgender Notation übergeben werden: