Zigbee2MQTT mit Cloud-Broker: Zigbee-Geräte per TLS von überall steuern

Mit einem Zigbee2MQTT-Cloud-Broker lesen Sie Sensoren aus und schalten Zigbee-Geräte von überall, ohne Portweiterleitung oder VPN in Ihrem Heimnetz. In dieser Anleitung richten Sie eine bestehende Zigbee2MQTT-Installation auf einen TLS-gesicherten Broker auf Port 8883 aus, testen zunächst mit einem öffentlichen MQTT-Broker und wechseln dann für den Alltag zu privaten Zugangsdaten.

Warum ein Cloud-Broker für Zigbee2MQTT?

Die meisten Zigbee2MQTT-Installationen sprechen mit einem Mosquitto-Container auf demselben Raspberry Pi. Das funktioniert gut, bis etwas außerhalb des Hauses die Daten sehen soll: eine Smartphone-App im Mobilfunknetz, ein Dashboard im Büro, ein zweiter Standort wie ein Ferienhaus oder ein Backend-Dienst, der den Energieverbrauch protokolliert. Einen lokalen Broker ins Internet zu stellen, bedeutet Portweiterleitung, dynamisches DNS und Zertifikate, und jeder dieser Punkte ist eine neue Fehlerquelle.

Ein Broker in der Cloud dreht die Verbindungsrichtung um. Zigbee2MQTT baut eine ausgehende TLS-Verbindung zum Broker auf, genau wie ein Browser, der eine Website öffnet, sodass an Ihrem Router nichts geändert werden muss. Jeder autorisierte Client kann dann von überall dieselben Topics abonnieren. Wenn Ihnen die Rolle des Brokers in diesem Bild neu ist, bietet die kurze Erklärung, was ein MQTT-Broker macht, einen guten Einstieg.

Der Kompromiss ist klar: Ihre Gerätezustände laufen nun über einen Dienst im Internet, daher sind Verschlüsselung und private Zugangsdaten nicht optional. Der Rest dieser Anleitung behandelt sie als Standard.

Was Sie brauchen

• Eine funktionierende Zigbee2MQTT-Installation (1.x oder 2.x) mit angelerntem Koordinator. Wenn Sie bei null anfangen, folgen Sie zuerst der Anleitung zum Einrichten von Zigbee2MQTT und kommen dann hierher zurück.
• Zugriff auf die configuration.yaml von Zigbee2MQTT (im Ordner data oder auf der Konfigurationsseite des Add-ons in Home Assistant).
• Zum Testen: nichts weiter, denn der öffentliche MQTT-Broker akzeptiert anonyme Verbindungen.
• Für den Produktivbetrieb: einen Broker mit eigenem Benutzernamen, Passwort und eigener Client ID, zum Beispiel einen im Portal angelegten ConnectMQ-Broker.

Schritt 1: Auf dem öffentlichen MQTT-Broker testen

Bevor Sie sich um Zugangsdaten kümmern, prüfen Sie, ob Zigbee2MQTT das Internet erreicht und per TLS veröffentlichen kann. Der öffentliche MQTT-Broker unter broker.connectmq.com akzeptiert anonyme Clients mit jeder nicht leeren, eindeutigen Client ID. Alles, was dort veröffentlicht wird, kann jeder lesen; verwenden Sie daher ein zufälliges Topic-Präfix und nur harmlose Testgeräte.

Bearbeiten Sie den Abschnitt mqtt in configuration.yaml:

mqtt:
  base_topic: connectmq/demo/z2m-7f3k9q/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  client_id: z2m-7f3k9q
  version: 5
  keepalive: 60
  reject_unauthorized: true

Einige Hinweise zu diesen Werten:

• mqtts:// und Port 8883 aktivieren TLS. Der Broker verwendet ein Let's-Encrypt-Zertifikat, dem Node.js bereits vertraut; ein ca-Eintrag ist daher nicht nötig.
• base_topic mit Ihrer zufälligen ID hält Ihre Nachrichten von denen aller anderen getrennt. Zigbee2MQTT hängt den Anzeigenamen des Geräts und Suffixe wie /set an, sodass das vollständige Topic hier sechs Ebenen tief ist, innerhalb des Limits von acht Ebenen des öffentlichen MQTT-Brokers.
• version: 5 wählt MQTT 5. Version 4 (MQTT 3.1.1) funktioniert ebenfalls.
• reject_unauthorized: true ist der Standard; lassen Sie es aktiviert. Wer es abschaltet, akzeptiert jedes Zertifikat und macht TLS sinnlos.

Starten Sie Zigbee2MQTT neu und suchen Sie im Log nach einer Zeile wie Connected to MQTT server. Abonnieren Sie dann von einem beliebigen Rechner aus:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i watcher-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/#' -v

Sie sollten bridge/state, bridge/info, bridge/devices und ein Topic pro Gerät sehen. Schalten Sie eine Lampe von der anderen Seite:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i sender-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/living_lamp/set' \
  -m '{"state":"TOGGLE"}'

Unter Windows oder macOS ersetzen Sie --capath /etc/ssl/certs durch --cafile mit einem CA-Bundle, das ISRG Root X1 enthält.

Limits des öffentlichen MQTT-Brokers

Der öffentliche MQTT-Broker erlaubt 64 KB pro Nachricht und 10 Nachrichten pro Sekunde und Client. Ein großes Zigbee-Netzwerk kann beides erreichen: bridge/devices listet jedes Gerät mit seiner vollständigen Definition auf und kann in einem großen Mesh 64 KB überschreiten, und ein Schwall von Sensormeldungen kann das Ratenlimit überschreiten. Für einen Test mit einer Handvoll Geräte ist das kein Problem, aber ein weiterer Grund, für die echte Installation auf einen privaten Broker umzusteigen.

Schritt 2: Wechsel zu einem privaten Cloud-Broker für Zigbee2MQTT

Sobald der Test funktioniert, legen Sie einen privaten Broker an. In ConnectMQ wählen Sie einen Tarif, erstellen einen Broker und erhalten einen generierten Benutzernamen, ein Passwort und eine Client ID. Client IDs sind an die ausgestellten Zugangsdaten gebunden; verwenden Sie also genau die Client ID aus dem Portal.

Halten Sie Geheimnisse mit der !secret-Syntax von Zigbee2MQTT aus der Hauptdatei heraus. Legen Sie secret.yaml neben configuration.yaml an:

mqtt_user: YOUR_USERNAME
mqtt_password: YOUR_PASSWORD
mqtt_client_id: YOUR_CLIENT_ID

Und verweisen Sie darauf:

mqtt:
  base_topic: home/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: '!secret mqtt_user'
  password: '!secret mqtt_password'
  client_id: '!secret mqtt_client_id'
  version: 5
  keepalive: 60
  reject_unauthorized: true
  include_device_information: false

frontend:
  enabled: true
  port: 8080

advanced:
  last_seen: ISO_8601

Ersetzen Sie den Host durch den im Portal für Ihren Broker angezeigten, falls er abweicht. Starten Sie neu und bestätigen Sie die Verbindung im Log und im Live-Topic-Explorer des Portals, wo home/zigbee2mqtt/bridge/state erscheinen sollte, sobald Zigbee2MQTT startet.

last_seen fügt jeder Gerätenachricht einen Zeitstempel hinzu, wodurch Sie einen verstummten Sensor aus der Ferne viel leichter erkennen. Lassen Sie include_device_information deaktiviert, sofern kein Abnehmer es braucht, denn es fügt jedem einzelnen Payload einen Block Metadaten hinzu.

Schritt 3: Zigbee-Geräte aus der Ferne steuern

Mit Zigbee2MQTT auf einem Cloud-Broker kann jeder MQTT-Client mit Zugangsdaten auf Ihre Geräte zugreifen. Der Topic-Vertrag ist derselbe wie bei einem lokalen Broker:

Das Topic bridge/state ist retained und als Last Will gesetzt, sodass ein entferntes Dashboard zwischen „die Lampe ist aus“ und „das gesamte Zigbee-Gateway ist offline“ unterscheiden kann. Nutzen Sie das in Ihrer Oberfläche, statt dem letzten Gerätezustand für immer zu vertrauen.

Ein minimaler Fernsteuerungs-Client in Python mit paho-mqtt 2.x sieht so aus:

import json
import paho.mqtt.client as mqtt

BASE = "home/zigbee2mqtt"

def on_connect(client, userdata, flags, reason_code, properties):
    print("connected:", reason_code)
    client.subscribe(f"{BASE}/bridge/state")
    client.subscribe(f"{BASE}/living_lamp")
    client.publish(f"{BASE}/living_lamp/set", json.dumps({"state": "ON", "brightness": 120}))

def on_message(client, userdata, msg):
    print(msg.topic, msg.payload.decode())

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 8883, keepalive=60)
client.loop_forever()

Beachten Sie, dass dieses Skript eine eigene Client ID braucht. Mit derselben ID wie Zigbee2MQTT würde es das Gateway bei jeder Verbindung trennen, denn ein Broker erlaubt nur eine Session pro Client ID. Geben Sie jeder Anwendung eigene Zugangsdaten.

Home Assistant und andere Abnehmer

Soll Home Assistant die Zigbee-Geräte erkennen, aktivieren Sie homeassistant: enabled: true in Zigbee2MQTT und richten die MQTT-Integration von Home Assistant auf denselben Broker mit denselben Zugangsdaten aus. Die Schritt-für-Schritt-Version, einschließlich der TLS-Einstellungen in der Home-Assistant-Oberfläche, finden Sie in der Anleitung zu Home Assistant mit einem externen MQTT-Broker. Discovery-Nachrichten sind retained und kommen daher auch an, wenn Home Assistant nach Zigbee2MQTT startet.

Andere Systeme werden genauso angebunden: Node-RED, Telegraf oder ein kleines Skript verbindet sich als MQTT-Client, abonniert home/zigbee2mqtt/# und schreibt in den Speicher Ihrer Wahl. Der Broker selbst leitet nur Nachrichten weiter, was die Architektur einfach und austauschbar hält. Dasselbe Muster nutzen auch Betriebe, die Funksensoren für Raumklima oder Energiemonitoring in einer Halle nachrüsten; dort ordnet man die Topics sinnvollerweise in einen Unified Namespace (UNS) ein, dessen Struktur der ISA-95-Hierarchie aus Werk, Bereich und Linie folgt.

Checkliste zur Fehlersuche

1. Connection refused: Not authorized - prüfen Sie Benutzername und Passwort und ob client_id exakt mit der für diese Zugangsdaten ausgestellten ID übereinstimmt.
2. Gateway verbindet sich alle paar Sekunden neu - ein anderer Client verwendet dieselbe Client ID. Durchsuchen Sie Ihre Skripte, Node-RED-Flows und alte Container.
3. self signed certificate oder unable to verify - Sie befinden sich hinter einem TLS-abfangenden Proxy, oder die Systemuhr geht falsch. Korrigieren Sie zuerst die Uhr (häufig bei einem Pi ohne Netzwerkzeit).
4. Beim Subscriber kommt nichts an - prüfen Sie, ob base_topic auf beiden Seiten identisch geschrieben ist; MQTT-Topics unterscheiden Groß- und Kleinschreibung.
5. bridge/devices fehlt auf dem öffentlichen MQTT-Broker - die Nachricht ist vermutlich größer als das öffentliche Limit von 64 KB. Testen Sie mit weniger Geräten oder wechseln Sie zu einem privaten Broker, wo der Free-Tarif 256 KB erlaubt.
6. Verbindungslimit erreicht - jede Zigbee2MQTT-Instanz, jedes Dashboard und jedes Skript zählt als eine Verbindung. Der Free-Tarif erlaubt bis zu 25.

Einen umfassenderen Überblick über TLS, Zugangsdaten und Topic-Design bietet der Leitfaden zu MQTT-Security-Best-Practices.

Einen verwalteten MQTT-Broker für Zigbee2MQTT wählen

Zigbee2MQTT stellt keine großen Anforderungen an einen Broker: MQTT 3.1.1 oder 5, TLS, retained Messages und ein Last Will. Wichtiger für ein Fernzugriffs-Setup ist, dass der Broker erreichbar, verschlüsselt und von anderen Mandanten isoliert ist. Ein verwalteter MQTT-Broker wie ConnectMQ kümmert sich um Zertifikate, Verfügbarkeit und Upgrades, sodass Ihr Raspberry Pi nur noch Zigbee2MQTT ausführen muss. Kostenlose Serverless-Broker unterstützen QoS 0 und 1, was die standardmäßige QoS-0-Veröffentlichung von Zigbee2MQTT ohne Änderungen abdeckt. Einen breiteren Blick auf Hosting-Optionen bietet der Leitfaden zum Cloud-MQTT-Broker, weitere Automatisierungsprojekte auf Basis desselben Brokers finden Sie im IoT-Automatisierungsleitfaden.

Bringen Sie Ihr Zigbee-Netzwerk auf ConnectMQ

Erstellen Sie einen kostenlosen Serverless-Broker unter app.connectmq.com (ohne Kreditkarte), fügen Sie die generierten Zugangsdaten in secret.yaml ein und sehen Sie zu, wie Ihre Zigbee-Geräte innerhalb einer Minute nach dem Neustart von Zigbee2MQTT im Live-Topic-Explorer erscheinen.

Häufig gestellte Fragen

Kann sich Zigbee2MQTT per TLS mit einem Cloud-Broker verbinden?

Ja. Setzen Sie server im Abschnitt mqtt von configuration.yaml auf mqtts://host:8883. Bei Brokern mit öffentlich vertrauenswürdigen Zertifikaten wie Let's Encrypt ist keine zusätzliche CA-Datei nötig.

Ist ein öffentlicher MQTT-Broker für Zigbee2MQTT sicher?

Nur für kurze Tests mit harmlosen Geräten. Auf einem öffentlichen MQTT-Broker kann jeder Topics lesen und darauf veröffentlichen; ein Türschloss oder eine Alarmanlage darf daher nie so angebunden werden. Verwenden Sie für alles Echte private Zugangsdaten.

Brauche ich weiterhin einen lokalen Mosquitto-Broker?

Nein. Zigbee2MQTT kann direkt an den Cloud-Broker veröffentlichen. Manche behalten einen lokalen Broker für rein lokale Automatisierungen, die auch bei einem Internetausfall funktionieren müssen, was eine legitime Designentscheidung ist.

Warum trennt sich mein Zigbee2MQTT-Gateway, wenn ich eine andere App öffne?

Die andere App verwendet fast sicher dieselbe Client ID. Ein Broker hält eine Session pro Client ID und trennt die ältere Verbindung; geben Sie also jedem Client eine eigene ID und eigene Zugangsdaten.