MQTT-Gateway

Das MQTT-Gateway bringt Peer-to-Peer LoRa-Knoten ins Internet und umgekehrt. In dieser Dokumentation werden sie Sie Schritt für Schritt durch diesen Prozess geführt. Die Gateway-Anwendung ist sofort einsatzbereit und erfordert für ihren Betrieb keine weiteren Programmierarbeiten. Der gesamte Quellcode für das LoRa-Gateway ist jedoch verfügbar und kann bei Bedarf angepasst werden.

Dieser Leitfaden beginnt mit der Basiseinrichtung und fügt später weitere Funktionen hinzu, wie z. B. der Empfang von LoRa-Nachrichten auf einem Mobiltelefon.

Wenn Sie den Anweisungen in diesem Leitfaden folgen, sollten Sie für die Einrichtung nicht mehr als 20 Minuten benötigen.

Merkmale des MQTT-Gateways

  • RadioShuttle LoRa Peer-to-Peer-Protokollunterstützung
  • Weiterleitung von MQTT-Nachrichten an bestimmte LoRa-Knoten
  • Weiterleitung von LoRa-NAchrichten an einen MQTT-Server (MQTT broker)
  • Umfangreiche Statusberichte auf OLED-Display (zusätzliche Protokollierung auf dem seriellen Monitor)
  • Automatisches Verbinden/Wiederverbinden mit einem WiFi-Netzwerk (und/oder einem alternativen WiFi-Netzwerk)
  • Automatisches Verbinden/Wiederverbinden mit einem MQTT-Server (und oder einem alternativen MQTT-Server)
  • Automatische Aktualisierung der Uhr über NTP (beim Start und wöchentlich)
  • Betriebsüberwachung durch Watchdog sowie Neustart bei keiner Reaktion
  • SSL-Verschlüsselung für MQTT-Kommunikation möglich (mqtts)
  • AES-Verschlüsselung für LoRa-Nachrichten möglich
  • Unterstützung 1000 LoRa-Knoten

Vorbereitung

  • Sie benötigen einen LoRa-Knoten, z. B. ein „ECO Power“- oder Turtle-Board oder ein zweites Eagle-Board.
  • Sie benötigen eine funktionsfähige Arduino IDE. Einzelheiten finden Sie auf der Seite Inbetriebnahme.
  • Des Weiteren benötigen Sie ein MQTT-Konto mit Benutzernamen, Passwort, Hostnamen, Port sowie Topic.
  • Vergewissern Sie sich, dass Sie Zugriff auf ein WiFi-Netzwerk haben (SSID und Passwort).

Konfiguration des MQTT-Gateways

  • Starten Sie aus den mitgelieferten Arduino-Beispielen das Programm „PropertyEditor“, indem Sie die „Reset“-Taste einmal drücken und die „User“-Taste dann für ca. 5 Sekunden gedrückt halten (bis das Programm „PropertyEditor“ im Fenster „Serieller Monitor“ startet).
  • Nehmen Sie folgende WiFi-Einstellungen vor: WIFI_SSID, WIFI_PASSWORD (eine alternative WiFi-Konfiguration ist für den Fall, dass das eigentliche WiFi-Netzwerk nicht verfügbar ist, möglich). Sie können optional auch die Eigenschaft HOSTNAME festlegen, um dem MQTT-Gateway einen Namen zu geben, z. B. „mygateway1“.
  • Geben Sie eine URL für MQTT_SERVER ein:
    mqtt://user:password@hostname:port
    oder per SSL:
    mqtts://user:password@hostname:port
  • Setzen Sie die Eigenschaft MQTT_TOPIC_GATEWAY. Diese wird für den Nachrichtenaustausch mit dem MQTT-Server verwendet (das Topic muss auf dem MQTT-Server ebenfalls konfiguriert bzw. erlaubt werden). Eine alternative Konfiguration des MQTT-Servers (MQTT_SERVER_ALT) ist möglich, wenn der eigentliche MQTT-Server nicht verfügbar ist. Über die Eigenschaft LORA_APP_PWD lässt sich optional ein Passwort für die AES-Verschlüsselung setzen (bei Nutzung eines Passworts für eine LoRa-Anwendung muss dieses für ale LoRa-Knoten gesetzt werden und übereinstimmen). Um eine Testnachricht an einen anderen LoRa-Knoten versenden zu können, müssen Sie auch die Eigenschaft LORA_REMOTE_ID des anderen Boards setzen.

Hinweis:
Anonyme MQTT-Konten, also solche ohne Benutzernamen und Passwort , werden nicht unterstützt, da dies bei der Verwendung der „MQTT Push App“, die einen Benutzernamen erfordert, zu Einschränkungen führen würde.

MQTT-Gateway: Software auf dem Eagle-Board installieren

  • Laden Sie das Programm „ESP32RadioShuttleMQTT“ aus den mitgelieferten Arduino-Beispielen. Es befindet sich in der Arduino IDE im Menü: Datei -> Beispiele -> Arduino-mbed-APIs Library
  • Wählen Sie das Board: “Heltec WiFi LoRa 32(V2)” aus dem Menü Werkzeuge -> Board -> ESP32 Arduino aus.

Wenn das Programm gestartet wird, sollte es sich mit dem WiFi-Netzwerk verbinden und dann eine Verbindung mit dem MQTT-Server herstellen. Das OLED-Display auf dem Board zeigt den WiFi- und MQTT-Status an.

Die Anzeige wird nach kurzer Zeit abgedunkelt, durch kurzes Drücken der „User“-Taste wird sie wieder aktiviert.

MQTT-Gateway: Status

Im Fenster „Serieller Monitor“ der Arduino IDE kann der erweiterte Status in der Protokolldatei, die zu Debugging-Zwecken viele Details einschließlich der Passwörter von WiFi und MQTT protokolliert, eingesehen werden. Sollen die Passwörter nicht protokolliert werden, muss die Debug-Option in der Funktion setup() im Gateway-Programm („ESP32RadioShuttleMQTT.ino“) ausgeschaltet werden. Dazu ändern Sie SetDebug(true) in SetDebug(false).

Display im Modus „MQTT gateway“

Zeile 1

  • RadioShuttle Geräte-ID des Gateways (aus Platzgründen werden nur die letzten drei Ziffern dargestellt)
  • Die aktuelle Uhrzeit (im Format hh:mm:ss)
    Zuerst wird die Uhrzeit der Programminstallation angezeigt. Nach kurzer Zeit wechselt die Anzeige auf die korrekte Uhrzeit, die vom NTP-Server bezogen wird (vorausgesetzt, dass WiFi verfügbar ist)

Zeile 2

  • WiFi SSID (Name des WiFi-Netzwerks) und WiFi RSSI (Stärke)
    Nachdem das Gateway gestartet ist, zeigt die Anzeige die WiFi SSID. Ist die WiFi-Verbindung hergestellt, kommt der Wert der WiFI RSSI dazu (z. B. „HELIOSOG (-62)“)
  • Eine WiFi RSSI von weniger als -85 deutet auf eine schwache WiFi-Signalstärke hin
  • Die WiFi SSID wird nur so lange dargestellt bis die erste LoRa-Nachricht empfangen wird
  • Die letzte empfangene LoRa-Nachricht wird angezeigt (nur einige Zeichen). Falls die Nachricht Binärdaten enthält, wird ein Hex Dump der letzten Nachricht angezeigt

Zeile 3

  • MQTT-Serveradresse und -port

Zeile 4

  • Empfangene RX(xx) / gesendete LoRa-Pakete TX(xx)
  • Signalstärke der zuletzt empfangenen Pakete in dBm(xxx)
    Manchmal wird dieser Wert auch RSSI genannt und bewegt sich für gewöhnlich zwischen -40 und -150 (wobei -40 dBm in der Nähe ist und -150 dBm weit entfernt)

Zeile 5

  • WiFi-Status: Offline oder Online
  • MQTT-Status: Offline oder Online

Um zu verhindern, dass das OLED-Display einbrennt, wird dieses nach kurzer Zeit abgedunkelt. Ein kurzer Druck auf die „User“-Taste aktiviert es wieder. Das Display schaltet sich auch dann wieder ein, wenn eine LoRa-Nachricht empfangen wird.

Einrichten eines LoRa-Knotens

Jedes RadioShuttle-Board kann verwendet werden, derzeit sind dies LongRa, ECO Power, Turtle und Eagle.

Arduino-boards (ECO Power, Eagle, LongRa)

In diesem Beispiel verwenden wir eines der Arduino-Boards, ECO Power.

  • Installieren Sie die RadioShuttle-Software auf dem „ECO Power“-Board (siehe Inbetriebnahme).
  • Starten Sie das Programm „PropertyEditor“, indem Sie die „Reset“-Taste einmal drücken und die „User“-Taste dann für ca. 5 Sekunden gedrückt halten (bis das Programm „PropertyEditor“ im Fenster „Serieller Monitor“ startet).
  • Weisen Sie LORA_REMOTE_ID die Geräte-ID des MQTT-Gateway-Boards (Eagle) zu. Die Geräte-ID des Eagle-Boards wird während des Starts im Fenster „Serieller Monitor“ der Arduino IDE angezeigt.
  • Weisen Sie LORA_RADIO_TYPE = 3 (node online) oder 1 (node offline) zu. Siehe dazu auch die Tabelle in RadioShuttle Sketch Installation für ECO Power.

Nach dem Start des „ECO Power“-Boards wird durch Drücken der „User“-Taste eine Beispielnachricht an das MQTT-Gateway gesendet. Dies lässt sich im Display des Gateways verfolgen. Die Nachricht wird auch an den MQTT-Server weitergeleitet.

Mbed-boards (Turtle)

In diesem Beispiel verwenden wir unser Mbed-basiertes Board, Turtle.

  • Installieren Sie die RadioShuttle-Software auf dem Turtle-Board (siehe Inbetriebnahme).
  • Nachdem die Software erfolgreich installiert wurde, startet das Terminalprogramm. Geben Sie innerhalb von 10 Sekunden p ein und drücken Sie ENTER, um das Programm „PropertyEditor“ zu starten.
  • Weisen Sie LORA_REMOTE_ID die Geräte-ID des MQTT-Gateway-Boards (Eagle) zu:
    s12=<ID of the Eagle board>
    Die Geräte-ID des Eagle-Boards während des Starts im Fenster „Serieller Monitor“ der Arduino IDE angezeigt.
  • Weisen Sie LORA_RADIO_TYPE = 3 (node online) oder 1 (node offline) zu. Siehe dazu auch die Tabelle in RadioShuttle-Programminstallation für Turtle.

Ist die Eigenschaft PROG_CMDLINE nicht gesetzt, startet die Software das Programm „RadioTestNew“. Um mit einem anderen Programm zu starten, geben Sie den Code des gewünschten Programms ein, z. B. s80=b für „Blinky“ (siehe Abb. 2 in RadioShuttle Programminstallation für Turtle).

Nach dem Start des Turtle-Bords wird durch Drücken der „User“-Taste eine Beispielnachricht an das MQTT-Gateway gesendet. Dies lässt sich im Display des Gateways verfolgen. Die Nachricht wird auch an den MQTT-Server weitergeleitet.

MQTT-Nachrichten vom / an den MQTT-Server

Normalerweise sind mehrere MQTT-Clients mit dem MQTT-Server verbunden. Dies kann ein PC, ein Smartphone oder auch ein Arduino MQTT-Client sein. Wir erklären anhand der folgenden drei Beispiele, was zwischen dem MQTT-Gateway und dem MQTT-Server gesendet/empfangen wird:

LoRa-Nachricht, die vom MQTT-Gateway empfangen und an den MQTT-Server weitergeleitet wird

Nachdem das MQTT-Gateway eine Nachricht von einem LoRa-Knoten empfangen hat, leitet es diese an den MQTT-Server weiter. Das Topic sieht folgendermaßen aus:
loratest/HELIOS/myHost/LoRaRECV/11616/1/2
Der Inhalt der MQTT-Nachricht ist der Inhalt der LoRa-Nachricht. Es wird empfohlen, sehr kurze Nachrichten (z. B. nur wenige Bytes) zu verwenden, um beim Senden auf dem LoRa-Knoten Energie zu sparen und die Netzauslastung gering zu halten.

Eine Nachricht setzt sich wie folgt zusammen:

  • MQTT-Topic (loratest/HELIOS) wie in der Gateway-Eigenschaft MQTT_TOPIC_GATEWAY angegeben
  • Hostname wie in der Gateway-Eigenschaft HOSTNAME angegeben (myHost, falls nicht gesetzt)
  • Der Key (LoRaRECV) zeigt an, dass das Gateway eine empfangene LoRa-Nachricht weiterleitet
  • Die Zahl 11616 gibt die Geräte-ID des LoRa-Knotens, der die Nachricht sendet, an
  • Die Zahl 1 ist die Programm-ID des LoRa-Knotens, der die Nachricht sendet (ID 1 wird von sämtlichen Beispielprogrammen verwendet)
  • Die letzte Zahl zeigt den Empfangsstatus des Knotens an. Gültige Statusnummern sind:
    2 = bestätigte Daten wurden empfangen
    1 = Daten wurden empfangen (Bestätigung nicht angefordert)

LoRa-Nachricht vom MQTT-Server zum MQTT-Gateway

Empfängt das Gateway eine Nachricht vom MQTT-Server – und das konfigurierte Topic stimmt überein – leitet es den Nachrichteninhalt an den entfernten LoRa-Knoten weiter. Das Topic sieht folgendermaßen aus:
loratest/HELIOS/myHost/LoRaSEND/11616/1/1

  • MQTT-Topic (lorates/HELIOS) wie in der Gateway-Eigenschaft MQTT_TOPIC_GATEWAY angegeben
  • Hostname wie in der Gateway-Eigenschaft HOSTNAME angegeben (myHost, falls nicht gesetzt)
  • Der Key (LoRaSEND) zeigt an, dass das Gateway eine Nachricht an einen LoRa-Knoten senden soll
  • Die Zahl 11616 ist die ID des LoRa-Knotens für den diese Nachricht bestimmt ist
  • Die Zahl 1 ist die ID des Programms, für das diese Nachricht bestimmt ist
  • Die letzte Zahl zeigt an, dass eine Nachricht gesendet werden soll:
    1 = mit Bestätigung
    0 = ohne Bestätigung an den MQTT-Server
    Das zweite Bit (2) zeigt an, dass die Nachricht per AES verschlüsselt ist, z. B.
    2 AES-Verschlüsselung ohne Bestätigungsaufforderung
    3 AES-Verschlüsselung mit Bestätigungsaufforderung

Bestätigungsnachricht vom MQTT-Gateway an den MQTT-Server

Nachdem eine Nachricht vom MQTT-Server an einen LoRa-Knoten weitergeleitet wurde, wird eine Statusmeldung an den MQTT-Server gesendet, um ihn über eine erfolgreiche oder fehlgeschlagene Nachrichtenübertragung an den LoRa-Knoten zu informieren. Ein Status-Topic sieht folgendermaßen aus:
loratest/HELIOS/myHost/LoRaSTAT/11616/1/2
Der Nachrichteninhalt ist der Status-String, z. B. MS_SentCompletedConfirmed

  • MQTT-Topic (loratest/HELIOS) wie in der Gateway-Eigenschaft MQTT_TOPIC_GATEWAY angegeben
  • Ein Key (LoRaSTAT), dass das Gateway eine Nachricht an den LoRa-Knoten senden soll
  • Die Zahl 11616 ist die ID des LoRa-Knotens, für den diese Nachricht bestimmt ist
  • Die Zahl 1 ist die ID des Programms, für das diese Nachricht bestimmt ist
  • Die letzte Zahl ist der Beendigungsstatus der Nachricht. Gültige Statusnummern sind:
    1 = die Nachrichtenübermittlung ist abgeschlossen
    2 = die Nachrichtenübermittlung ist abgeschlossen und vom empfangenden LoRa-Knoten bestätigt
    3 = die Nachrichtenübermittlung wurde nach einem Time-out abgebrochen (3 Wiederholungsversuche)
    4 = Der Knoten hat die Nachricht nicht akzeptiert, weil die Autorisierung fehlgeschlagen ist

MQTT-Nachrichten auf ein Smartphone senden

Nachdem wir gelernt haben, wie Nachrichten an den/vom MQTT-Server weitergeleitet werden, gehen wir einen Schritt weiter und zeigen, wie eine Nachricht direkt an ein Smartphone gesendet werden kann. Das Smartphone kann über das MQTT-Gateway sogar eine Nachricht an den LoRa-Knoten senden.

  • Installieren Sie die App „MQTT Push Client“ für iOS oder Android.
  • Konfigurieren Sie ein MQTT-Konto (MQTT-Benutzer, Passwort, Host).
  • Konfigurieren Sie das MQTT-Topic in der App, z. B. „loratest/HELIOS“, wie in den Einstellungen für das Gateway angegeben:

Das war’s! Neue Nachrichten zu diesem Thema erscheinen auf dem Smartphone, nachdem der LoRa-Knoten eine Nachricht gesendet hat.

Nachrichten von einem Smartphone senden

Legen Sie eine MQTT-Aktion mit folgenden Einstellungen an:

  • Name: „Hallo LoRa-Node 11609“
  • Topic: loratest/HELIOS/LoRaSEND/phonename/11609/1/0
  • Name des Smartphones: beliebiger Name, z. B. „iPhone-Ingo“
  • Die Zahl 11609 ist die ID des LoRa-Knotens, für den diese Nachricht bestimmt ist
  • Die Zahl 1 ist die ID des Programms, für das diese Nachricht bestimmt ist
  • Die letzte Zahl (Flags für die Nachrichtenübermittlung):
    0 = keine Bestätigung
    1 = erstes Bit an => Sende eine Nachricht mit Bestätigung
    Das zweite Bit (2) zeigt an, dass die Nachricht per AES verschlüsselt ist, z. B.
    2 AES-Verschlüsselung ohne Bestätigungsaufforderung
    3 AES-Verschlüsselung mit Bestätigungsaufforderung

Vom Fenster „Dashboard“ in der Anwendung aus erlaubt die Aktion das Senden von Daten an den LoRa-Knoten. Dies kann eine einfache Steuernachricht sein, z. B. das Ein- und Ausschalten der Beleuchtung.

Zusammenfassung

Das MQTT-Gateway ermöglicht eine vielseitige Nachrichtenweiterleitung zwischen den Peer-to-Peer-Knoten des RadioShuttle LoRa und der IoT-Welt über MQTT. Dabei kann es sich um einfache Temperaturberichte oder um eine erweiterte Verwaltung von Maschinen handeln. Das gesamte MQTT-Gateway erfordert keine Programmierungsarbeiten; einfach die WiFi- und MQTT-Parameter über die Anwendung „PropertyEditor“ eingeben und los geht’s. Dasselbe gilt für den LoRa-Knoten. Ein Dutzend Beispielanwendungen sind enthalten. Laden bzw. aktivieren Sie einfach die gewünschte Sensoranwendung und die Kommunikation kann beginnen.

Hinweise für Fortgeschrittene

Standardmäßig verwenden alle RadioShuttle-Beispielprogramme die Anwendungs-ID „1“ innerhalb der Nachricht. Ein magisches Feld in der Nachricht bestimmt, ob die Nachricht verarbeitet oder ignoriert wird. Für größere Projekte können benutzerdefinierte Anwendungs-IDs verwendet werden, wenn sie über die Funktion rs->RegisterApplication() am Ende der Funktion setup() in der „.ino“-Datei des Beispielprogramms registriert werden.
Werden AES-verschlüsselte Nachrichten verwendet, muss das Passwort auf allen LoRa-Knoten und dem Gateway mit „PropertyEditor“ identisch gesetzt werden. Wenn mehrere Anwendungs-IDs verwendet werden, muss das Passwort pro Anwendungs-ID über die Funktion rs->RegisterApplication() angegeben werden.

Anmerkungen zur Leistung

MQTT-Nachrichten können alle Arten von Daten enthalten, z. B. binäre Daten, Zeichenketten, HTML oder sogar JSON-kodierte Nachrichten. Bei WiFi-Netzen ist die Länge der Nachrichten nicht wichtig, während bei LoRa-Netzen die Nachrichtenlänge so kurz wie möglich sein sollte. Das Beispielprogramm des RadioShuttle-Temperatursensors beispielsweise verwendet nur 6 Bytes oder sogar weniger für die Übertragung von Luftfeuchtigkeit, Temperatur und Batteriestatus.

Es gibt drei Hauptgründe, die Nachricht so kurz wie möglich zu halten:

  1. Vermeidet ein ausgelastetes LoRa-Funknetzwerk (ermöglicht die Kommunikation von mehreren Geräten, überwindet die Besetztgrenze von 1% pro Stunde)
  2. Spart Energie auf den batteriebetriebenen LoRa-Knoten
    (Zum Beispiel verbraucht eine 12-Byte-Nachricht doppelt so viel Energie wie eine 6-Byte-Nachricht)
  3. Beschleunigt die Durchlaufzeit der Kommunikation bei kleinen Nachrichten. Die LoRa-Modulation ermöglicht große Entfernungen, hat aber eine niedrige Datenrate. Kleine Nachrichten liefern im Vergleich zu großen Nachrichten eine um ein Vielfaches schnellere Durchlaufzeit.