Mit einer guten Mosquitto-Bridge-Konfiguration bedient ein lokaler Broker auf einem Raspberry Pi weiterhin die Geräte im LAN und leitet zugleich genau die Topics, die Sie auswählen, an einen Cloud-Broker weiter. In diesem Tutorial bauen Sie eine Bridge, die sich per TLS mit den Zugangsdaten aus dem Portal bei ConnectMQ anmeldet, Topics so umschreibt, dass jeder Standort seinen eigenen Namespace erhält, Befehle zurück nach unten sendet, Nachrichten über Internetausfälle hinweg puffert und die klassische Nachrichtenschleife vermeidet. Jede Option wird erklärt, sodass Sie die Datei anpassen können, statt sie blind zu kopieren.
So funktioniert eine Mosquitto-Bridge
Eine Bridge ist kein spezielles Protokoll. Der lokale Mosquitto-Broker öffnet eine ausgehende Verbindung zum entfernten Broker und verhält sich wie ein normaler MQTT-Client: Er abonniert auf der einen Seite und republiziert auf der anderen, gemäß den topic-Zeilen in seiner Konfiguration. Das hat drei nützliche Folgen:
- Keine eingehenden Ports. Der Pi verbindet sich nach außen über Port 8883, so wie ein Browser eine Website aufruft. Ihr Router bleibt geschlossen.
- Der entfernte Broker braucht nichts Besonderes. Jeder standardkonforme Broker akzeptiert eine Bridge, denn er sieht lediglich einen Client, der sich mit Benutzername, Passwort und Client-ID anmeldet.
- Sie bestimmen, was die Grenze passiert. Nur Topics, die zu einer
topic-Zeile passen, verlassen oder erreichen den Standort.
In diesem Aufbau ist die entfernte Seite ConnectMQ, ein verwalteter MQTT-Broker. Die Bridge authentifiziert sich wie jedes andere Gerät mit den im Portal generierten Zugangsdaten. Falls Sie den lokalen Broker noch nicht eingerichtet haben, folgen Sie zuerst der Anleitung Mosquitto auf dem Raspberry Pi installieren.
Sensors / PLC gateway / Node-RED (LAN)
| mqtt://pi:1883 (local users)
v
+---------------------------+
| Mosquitto on Raspberry Pi |
| bridge "connectmq" |
+---------------------------+
| mqtts://broker.connectmq.com:8883
| remote_username / remote_password / remote_clientid
v
+---------------------------+
| ConnectMQ cloud broker | dashboards, phones, other sites
+---------------------------+
Bevor Sie beginnen
- Ein Raspberry Pi, auf dem Mosquitto 2.0 mit mindestens einem authentifizierten lokalen Listener läuft.
- Ein Cloud-Broker mit Zugangsdaten. Registrieren Sie sich im Portal, wählen Sie einen Plan, erstellen Sie einen Broker und kopieren Sie den generierten Benutzernamen, das Passwort und die Client-ID. Die Client-ID ist an diese Zugangsdaten gebunden, die Bridge muss sie also exakt verwenden.
- Ein Konzept für Topic-Namen. Legen Sie fest, wie lokale Topics in der Cloud aussehen sollen. Ein Standortpräfix wie
site1/verhindert, dass mehrere Pis kollidieren.
Für ein schnelles Experiment ohne Konto können Sie die Bridge mit dem Öffentlichen MQTT-Broker auf Port 1883 verbinden, ohne Zugangsdaten und mit einer beliebigen eindeutigen Client-ID sowie einem zufälligen Präfix wie connectmq/demo/3c7d52/. Dort ist alles öffentlich lesbar; er dient nur Tests und Prototypen, verwenden Sie also ausschließlich Dummy-Daten.
Die vollständige Mosquitto-Bridge-Konfiguration
Legen Sie /etc/mosquitto/conf.d/bridge-connectmq.conf an:
# ---- Verbindung ----
connection connectmq
address broker.connectmq.com:8883
bridge_protocol_version mqttv311
try_private false
start_type automatic
restart_timeout 5 60
keepalive_interval 60
# ---- TLS ----
bridge_capath /etc/ssl/certs
bridge_insecure false
# ---- Zugangsdaten aus dem ConnectMQ-Portal ----
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
# ---- Session und Queueing ----
cleansession false
local_clientid bridge-connectmq-local
# ---- Status-Topic (wird auf der entfernten Seite publiziert) ----
notifications true
notifications_local_only false
notification_topic site1/bridge/state
# ---- Topic-Zuordnung ----
# Telemetrie nach oben: lokal "sensors/#" -> entfernt "site1/sensors/#"
topic sensors/# out 1 "" site1/
# Maschinenzustände nach oben, retained-Werte bleiben erhalten
topic machines/+/state out 1 "" site1/
# Befehle nach unten: entfernt "site1/cmd/#" -> lokal "cmd/#"
topic cmd/# in 1 "" site1/
Starten Sie neu und verfolgen Sie das Log:
sudo chmod 0640 /etc/mosquitto/conf.d/bridge-connectmq.conf
sudo chown root:mosquitto /etc/mosquitto/conf.d/bridge-connectmq.conf
sudo systemctl restart mosquitto
sudo journalctl -u mosquitto -f
Sie sollten Connecting bridge connectmq (broker.connectmq.com:8883) sehen, gefolgt von keinen Fehlern. Die Rechteänderung ist wichtig, weil die Datei das entfernte Passwort enthält.
Option für Option
| Option | Wert hier | Warum |
|---|---|---|
address |
broker.connectmq.com:8883 |
TLS-Port des Cloud-Brokers |
bridge_protocol_version |
mqttv311 |
Breit unterstützt; MQTT-5-Bridging ist mit aktuellen Mosquitto-Versionen ebenfalls möglich |
try_private |
false |
Vermeidet ein Mosquitto-eigenes Bridge-Flag, das andere Broker ablehnen könnten |
restart_timeout |
5 60 |
Wartezeit zwischen Reconnect-Versuchen steigt von 5 s bis 60 s |
bridge_capath |
/etc/ssl/certs |
Der System-CA-Store validiert das Let's-Encrypt-Zertifikat des Brokers |
bridge_insecure |
false |
Hostname-Prüfung immer eingeschaltet lassen |
remote_clientid |
Client-ID aus dem Portal | Muss zu den ausgegebenen Zugangsdaten passen |
cleansession |
false |
Sessions behalten, damit QoS-1-Nachrichten bei Ausfällen gepuffert werden |
notifications |
true |
Publiziert 1, wenn die Bridge verbunden ist, und 0 (als Last Will), wenn sie abbricht |
notification_topic |
site1/bridge/state |
Hält den Status in Ihrem eigenen Namespace |
Die topic-Zeile verstehen
Die Syntax lautet topic <pattern> <direction> <qos> <local-prefix> <remote-prefix>. Mosquitto entfernt beim Weiterleiten nach außen das lokale Präfix vom lokalen Topic und fügt das entfernte Präfix hinzu; bei in geschieht das Umgekehrte. Mit leerem lokalem Präfix (geschrieben als "") und dem entfernten Präfix site1/ gilt:
- Lokal
sensors/boiler/tempwird entfernt zusite1/sensors/boiler/temp. - Entfernt
site1/cmd/pump1/setwird lokal zucmd/pump1/set.
Beachten Sie, dass das entfernte Präfix mit einem Schrägstrich endet. Ohne ihn erhalten Sie site1sensors/..., ein Fehler, der leicht passiert und schwer zu entdecken ist.
QoS auf der Bridge
Die QoS in einer topic-Zeile ist das Maximum, das über die Bridge verwendet wird. QoS 1 ist die praktische Wahl: Sie garantiert die Zustellung mit Bestätigungen und wird in jedem Plan unterstützt, auch im kostenlosen Serverless-Plan, der QoS auf 1 begrenzt. Verwenden Sie QoS 2 nur, wenn Ihr Plan sie unterstützt und die Daten wirklich keine Duplikate vertragen. Der Artikel MQTT-QoS-Stufen erklärt beschreibt die Abwägungen.
Puffern bei Internetausfällen
Mit cleansession false behält der lokale Broker die Session der Bridge, solange die Verbindung unterbrochen ist, und puffert QoS-1-Nachrichten für sie. Kehrt die Verbindung zurück, fließt der Rückstau in die Cloud ab. Die Warteschlange wird durch max_queued_messages (und optional max_queued_bytes) in Ihrer Hauptkonfiguration begrenzt. Dimensionieren Sie sie für den längsten Ausfall, den Sie abdecken möchten; auf einem Pi mit SD-Karte sollten Sie maßvoll bleiben, weil persistierte Warteschlangen bei jedem Autosave auf die Karte geschrieben werden. QoS-0-Nachrichten werden nicht gepuffert, ein weiterer Grund, Telemetrie mit QoS 1 zu bridgen.
Denken Sie daran, dass auch die Cloud-Seite eigene Grenzen hat. Trifft ein langer Rückstau auf einmal ein, kann ein Broker mit Kontingenten pro Plan und Flood-Schutz ihn drosseln. Sehr lange Ausfälle lassen sich daher besser mit einem Puffer auf Anwendungsebene abfangen, wie im Leitfaden zum Offline-Puffern von Nachrichten.
Die Bridge Ende-zu-Ende testen
Abonnieren Sie auf der Cloud-Seite. Beim öffentlichen MQTT-Broker können Sie mosquitto_sub direkt verwenden; bei einem privaten Broker nutzen Sie einen zweiten Satz Zugangsdaten oder den MQTT-Client im Browser im Portal:
mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
-u YOUR_USERNAME_2 -P YOUR_PASSWORD_2 -i YOUR_CLIENT_ID_2 \
-t 'site1/#' -v
Publizieren Sie lokal auf dem Pi:
mosquitto_pub -h localhost -u sensors -P 'sensors-password' -i t1 -q 1 \
-t sensors/boiler/temp -m 64.2
Der Cloud-Abonnent gibt site1/sensors/boiler/temp 64.2 und site1/bridge/state 1 aus. Testen Sie nun den Downlink. Abonnieren Sie lokal cmd/# und publizieren Sie dann von der Cloud-Seite an site1/cmd/pump1/set. Die Nachricht kommt lokal als cmd/pump1/set an.
Testen Sie zum Schluss einen Ausfall: Schalten Sie das Netzwerk auf dem Pi ab (sudo nmcli networking off), publizieren Sie lokal einige QoS-1-Nachrichten, aktivieren Sie das Netzwerk wieder und beobachten Sie, wie sie in der Cloud ankommen. Das Status-Topic der Bridge wechselt während der Unterbrechung auf 0, zugestellt vom Broker als Last Will der Bridge.
Schleifen in Ihrer Mosquitto-Bridge-Konfiguration vermeiden
Eine Schleife entsteht, wenn eine nach außen weitergeleitete Nachricht wieder hereinkommt und erneut nach außen geleitet wird. Die häufigste Ursache ist eine both-Regel oder überlappende in- und out-Muster auf denselben Topics:
# Gefährlich: alles unter site1/ springt hin und her
topic # both 1 "" site1/
Halten Sie die Richtungen in getrennten Teilbäumen: Telemetrie und Zustände gehen out, Befehle kommen in unter einem anderen Zweig (cmd/). Wenn Sie wirklich both brauchen, bevorzugen Sie MQTT-5-Bridging mit No-Local-Subscriptions, sofern Ihre Mosquitto-Version es unterstützt, und testen Sie sorgfältig. Bridgen Sie # niemals ohne Präfix, in keiner Richtung.
Mehrere Standorte, ein Cloud-Broker
Jeder Pi erhält eigene Zugangsdaten und ein eigenes Präfix (site1/, site2/, ...). Dashboards abonnieren +/sensors/#, um alle Standorte zu sehen, oder ein einzelnes Präfix für einen Standort. Weil jede Bridge eine eindeutige, an ihre Zugangsdaten gebundene Client-ID hat, beeinträchtigt der Widerruf eines Standorts nie die anderen. Kostenpflichtige Serverless-Pläne bieten zusätzlich Shared Subscriptions, die helfen, wenn mehrere Cloud-Abnehmer den gemeinsamen Datenstrom aufteilen müssen. Industrielle Standorte können noch weiter gehen und eine ISA-95-Hierarchie wie enterprise/site/area/line/cell übernehmen, etwa acme/werk-augsburg/montage/linie-1/zelle-2. So wird aus den Bridges aller Werke ein gemeinsamer Unified Namespace (UNS), dessen Struktur das Portal erkennt und in seiner Geräteansicht anzeigt.
Fehlerbehebung
| Log-Meldung oder Symptom | Ursache | Lösung |
|---|---|---|
Connection Refused: not authorised |
Falsche Zugangsdaten oder Client-ID | Alle drei erneut aus dem Portal kopieren |
certificate verify failed |
Fehlender CA-Store oder falsche Uhrzeit | ca-certificates installieren, NTP mit timedatectl prüfen |
| Bridge verbindet sich, aber nichts kommt an | Topic-Muster oder Präfix passt nicht | An den abschließenden Schrägstrich im Präfix denken |
| Verbindung bricht alle paar Sekunden ab | Ein anderer Client nutzt dieselbe Client-ID | Eine Client-ID pro Verbindung |
| Nachrichten gehen bei Ausfällen verloren | QoS 0 oder cleansession true |
QoS 1 und cleansession false verwenden |
| Nachrichtensturm nach Aktivieren der Bridge | Schleife durch überlappende in/out-Regeln | Getrennte Teilbäume pro Richtung |
Verbinden Sie Ihren Pi mit ConnectMQ
Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ohne Kreditkarte, fügen Sie den generierten Benutzernamen, das Passwort und die Client-ID in Ihre Bridge-Datei ein und beobachten Sie, wie die Topics Ihres Standorts im Live-Topic-Explorer des Portals erscheinen. Zum übergeordneten Gateway-Design rund um diese Bridge lesen Sie Raspberry Pi als IoT-Gateway, und für die gesamte Pi-Reihe das Raspberry-Pi-MQTT-Tutorial.
Häufig gestellte Fragen
Braucht ConnectMQ eine spezielle Bridge-Funktion für Mosquitto?
Nein. Die Mosquitto-Bridge verbindet sich als normaler MQTT-Client mit Benutzername, Passwort und Client-ID aus dem Portal, daher funktioniert jeder Plan.
Sollte ich mit MQTT 3.1.1 oder MQTT 5 bridgen?
MQTT 3.1.1 ist die einfachste und am breitesten getestete Wahl für Bridges. Aktuelle Mosquitto-Versionen unterstützen mqttv50-Bridging, wenn Sie MQTT-5-Funktionen auf der Bridge-Verbindung benötigen.
Warum try_private auf false setzen?
Ist die Option aktiv, signalisiert Mosquitto über ein nicht standardkonformes Protokoll-Flag, das für Verbindungen zwischen Mosquitto-Brokern gedacht ist, dass es eine Bridge ist. Ausgeschaltet bleibt die Verbindung gegenüber anderen Brokern vollständig standardkonform.
Wie viele Nachrichten puffert die Bridge während eines Ausfalls?
So viele, wie max_queued_messages und max_queued_bytes zulassen, für QoS-1- und QoS-2-Nachrichten mit cleansession false. QoS-0-Nachrichten werden verworfen, solange die Verbindung unterbrochen ist.
