openHAB MQTT Binding: Broker, Things und Regeln

Q: Kann openHAB MQTT 5 verwenden?

Die Broker-Bridge hat einen Parameter mqttVersion, der auf V5 gesetzt werden kann. Version 3.1.1 bleibt der Standard und funktioniert mit nahezu allen Geräten.

Q: Warum werden meine Items aktualisiert, aber keine Befehle gesendet?

Wahrscheinlich hat der Kanal kein commandTopic, oder das Item ist nur lesend verknüpft. Ergänzen Sie ein Befehls-Topic und prüfen Sie mit einem Subscriber, ob die Nachricht veröffentlicht wird.

Das openHAB MQTT Binding macht aus jedem MQTT-Topic Kanäle, die Sie mit Items verknüpfen, auf Dashboards anzeigen und in Regeln verwenden können. In diesem Tutorial verbinden Sie openHAB mit einem externen Broker, definieren generische MQTT-Things für einen Sensor und einen Schalter, parsen JSON-Payloads, veröffentlichen Befehle aus Regeln und härten das Setup mit TLS und Zugangsdaten.

So ist das openHAB MQTT Binding aufgebaut

openHAB bildet MQTT in zwei Ebenen ab. Die Broker-Bridge (mqtt:broker) ist die Verbindung: Host, Port, TLS, Client-ID und Zugangsdaten. Darunter liegen Things, die jeweils ein Gerät über seine Topics beschreiben. Der flexibelste Thing-Typ ist das generische MQTT-Thing (mqtt:topic), bei dem Sie jeden Kanal samt den verwendeten Zustands- und Befehls-Topics deklarieren. Items werden dann genau wie bei jedem anderen Binding mit diesen Kanälen verknüpft.

Ebene	Thing-Typ	Enthält
Verbindung	`mqtt:broker` (Bridge)	Host, Port, TLS, Client-ID, Benutzername, Passwort, Last Will
Gerät	`mqtt:topic` (generisches Thing)	Kanäle mit Zustands- und Befehls-Topics
Gerät (automatisch)	Home-Assistant- oder Homie-Things	Aus Discovery-Nachrichten erzeugt
Modell	Items	Mit Kanälen verknüpft, in UI und Regeln verwendet

Eine einzige Broker-Bridge kann Hunderte Things bedienen und nutzt dabei nur eine MQTT-Verbindung. Das ist bei Plänen mit Verbindungskontingenten wichtig: openHAB zählt als ein Client, egal wie viele Geräte es abbildet.

Installieren Sie das Binding über Einstellungen > Add-on Store > Bindings > MQTT Binding. Wenn Ihre Geräte JSON senden, installieren Sie außerdem die JSONPath Transformation aus dem Bereich der Transformationen.

openHAB mit einem MQTT-Broker verbinden

Sie können die Bridge in der UI anlegen (Things > + > MQTT Binding > MQTT Broker) oder in einer .things-Datei. Textkonfiguration lässt sich leichter teilen und sichern, daher verwendet dieses Tutorial sie. Erstellen Sie conf/things/mqtt.things:

Bridge mqtt:broker:connectmq "ConnectMQ Broker" [
    host="broker.connectmq.com",
    port=1883,
    secure=false,
    clientID="openhab-r4t8w1",
    lwtTopic="connectmq/demo/r4t8w1/openhab/status",
    lwtMessage="offline",
    lwtRetain=true,
    birthTopic="connectmq/demo/r4t8w1/openhab/status",
    birthMessage="online",
    birthRetain=true
] {
    Thing topic greenhouse "Greenhouse Sensor" {
    Channels:
        Type number : temperature "Temperature" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/telemetry",
            transformationPattern="JSONPATH:$.temp",
            unit="°C"
        ]
        Type number : humidity "Humidity" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/telemetry",
            transformationPattern="JSONPATH:$.hum",
            unit="%"
        ]
        Type switch : fan "Vent Fan" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/fan/state",
            commandTopic="connectmq/demo/r4t8w1/greenhouse/fan/set",
            on="ON",
            off="OFF"
        ]
        Type contact : door "Door" [
            stateTopic="connectmq/demo/r4t8w1/greenhouse/door",
            on="OPEN",
            off="CLOSED"
        ]
    }
}

Damit verbinden Sie sich anonym mit dem öffentlichen MQTT-Broker, der für Tests und Prototypen gedacht ist, nicht für echte Gerätedaten. Ersetzen Sie r4t8w1 durch eine eigene Zufallszeichenkette, denn der öffentliche Bereich wird gemeinsam genutzt und ist für alle lesbar. Die Client-ID darf nicht leer sein und muss eindeutig sein; verwenden Sie eine ID, die bereits ein anderer Client hält, brechen beide Verbindungen immer wieder ab.

Prüfen Sie Einstellungen > Things: Die Bridge sollte innerhalb weniger Sekunden ONLINE sein, gefolgt vom Greenhouse-Thing.

Items verknüpfen

Erstellen Sie conf/items/greenhouse.items:

Number:Temperature GH_Temperature "Temperature [%.1f °C]" <temperature> { channel="mqtt:topic:connectmq:greenhouse:temperature" }
Number:Dimensionless GH_Humidity "Humidity [%.0f %%]" <humidity> { channel="mqtt:topic:connectmq:greenhouse:humidity" }
Switch GH_Fan "Vent Fan" <fan> { channel="mqtt:topic:connectmq:greenhouse:fan" }
Contact GH_Door "Door [%s]" <door> { channel="mqtt:topic:connectmq:greenhouse:door" }

Beachten Sie das Muster der Kanal-UID: mqtt:topic:<bridge id>:<thing id>:<channel id>. Ein Tippfehler dort ist der häufigste Grund, warum ein Item NULL bleibt.

Die openHAB-MQTT-Kanäle testen

Simulieren Sie das Gerät aus einem Terminal:

# Sensorwert (JSON, per JSONPath geparst)
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/telemetry' -m '{"temp":24.6,"hum":71}'

# Türkontakt
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/door' -m 'OPEN'

# die von openHAB gesendeten Befehle beobachten
mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/fan/set' -v

Schalten Sie den Lüfter in der openHAB-UI um, und der Befehl ON oder OFF erscheint im Subscriber-Fenster. Ein echtes Gerät würde ihn ausführen und seinen neuen Zustand auf fan/state veröffentlichen, womit openHAB das Item aktualisiert. Getrennte Befehls- und Zustands-Topics bedeuten, dass die UI den bestätigten Zustand zeigt und nicht nur den letzten Klick.

JSON parsen und Befehle formatieren

Die meisten modernen Geräte veröffentlichen JSON. Neben transformationPattern für eingehende Werte unterstützt das generische Thing formatBeforePublish für ausgehende. Zum Beispiel ein Dimmer, der {"brightness": 40} erwartet:

Type dimmer : lamp "Grow Lamp" [
    stateTopic="connectmq/demo/r4t8w1/greenhouse/lamp/state",
    commandTopic="connectmq/demo/r4t8w1/greenhouse/lamp/set",
    transformationPattern="JSONPATH:$.brightness",
    formatBeforePublish="{\"brightness\": %s}",
    min=0,
    max=100
]

Transformationen lassen sich mit dem Zeichen ∩ im Muster verketten, wenn Sie mehrere Schritte brauchen, etwa JSONPath gefolgt von einer MAP-Abfrage. Halten Sie Ketten kurz; wenn die Logik wächst, ist eine Regel leichter zu debuggen.

MQTT-Nachrichten aus openHAB-Regeln veröffentlichen

Mit Kanälen verknüpfte Befehle decken die meisten Anforderungen ab, aber manchmal möchten Sie auf ein beliebiges Topic veröffentlichen, etwa um einen Zeitplan an einen Controller zu senden. Die Broker-Bridge stellt dafür die Aktion publishMQTT bereit. In einer DSL-Regeldatei conf/rules/greenhouse.rules:

rule "Greenhouse overheat"
when
    Item GH_Temperature changed
then
    val temp = (GH_Temperature.state as QuantityType<Number>).toUnit("°C").doubleValue
    if (temp > 30.0 && GH_Fan.state != ON) {
        GH_Fan.sendCommand(ON)
        val mqtt = getActions("mqtt", "mqtt:broker:connectmq")
        mqtt.publishMQTT("connectmq/demo/r4t8w1/greenhouse/event",
            "{\"event\":\"overheat\",\"temp\":" + temp + "}", false)
    }
end

Dieselbe Aktion steht in JavaScript-Regeln über actions.get("mqtt", "mqtt:broker:connectmq") zur Verfügung. Veröffentlichen Sie nicht auf dasselbe Topic, das ein Kanal abonniert, es sei denn, Sie wollen bewusst eine Schleife erzeugen.

Regeln über rohe Topics auslösen

Wenn Sie nur auf eine Nachricht reagieren wollen, ohne ein Item abzubilden, fügen Sie der Bridge einen Trigger-Kanal hinzu:

Bridge mqtt:broker:connectmq "ConnectMQ Broker" [ ... ] {
    Channels:
        Type publishTrigger : alarms "Alarms" [
            stateTopic="connectmq/demo/r4t8w1/+/alarm",
            separator="#"
        ]
}

Eine Regel, die durch Channel "mqtt:broker:connectmq:alarms" triggered ausgelöst wird, erhält Topic und Payload durch den Separator verbunden, sodass eine einzige Regel Alarme aller Geräte verarbeiten kann.

Produktiv-Setup mit TLS und Zugangsdaten

Bevor Sie echte Geräte verbinden, verlassen Sie den öffentlichen MQTT-Broker. Legen Sie einen privaten Broker an und aktualisieren Sie dann die Bridge:

Bridge mqtt:broker:connectmq "ConnectMQ Broker" [
    host="broker.connectmq.com",
    port=8883,
    secure=true,
    certificatepin=false,
    publickeypin=false,
    clientID="YOUR_CLIENT_ID",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
    lwtTopic="site1/openhab/status",
    lwtMessage="offline",
    lwtRetain=true
]

Das Zertifikat von ConnectMQ wird von Let's Encrypt ausgestellt, dem Java standardmäßig vertraut, daher ist kein zusätzlicher Zertifikatsimport nötig. Certificate Pinning wird ausdrücklich abgeschaltet, weil Let's-Encrypt-Zertifikate alle paar Monate erneuert werden; ein gepinntes Zertifikat würde die Bridge den Broker nach der nächsten Erneuerung ablehnen lassen. Verwenden Sie die Client-ID exakt wie ausgegeben, da sie an die Zugangsdaten gebunden ist. Mehr zur Absicherung des gesamten Systems lesen Sie in den MQTT-Sicherheits-Best-Practices.

Wenn Sie Ihren Broker lieber lokal im Netzwerk von openHAB betreiben, können Sie ihn später immer noch per Bridge an die Cloud anbinden; ein verwalteter MQTT-Broker erspart Ihnen jedoch die Pflege eines separaten Broker-Hosts und lässt entfernte Standorte und Smartphones dieselben Topics erreichen.

Geräteverfügbarkeit anzeigen

Ein generisches Thing bleibt ONLINE, solange die Bridge verbunden ist, selbst wenn das Gerät dahinter schon vor Stunden den Strom verloren hat. Um das sichtbar zu machen, lassen Sie jedes Gerät beim Verbinden eine retained online-Nachricht veröffentlichen und einen retained Last Will offline setzen. Ergänzen Sie dann Verfügbarkeitseinstellungen am Thing:

Thing topic greenhouse "Greenhouse Sensor" [
    availabilityTopic="connectmq/demo/r4t8w1/greenhouse/status",
    payloadAvailable="online",
    payloadNotAvailable="offline"
] {
    // Kanäle wie zuvor
}

Fällt das Gerät aus, veröffentlicht der Broker dessen Will, openHAB markiert das Thing als OFFLINE, und verknüpfte Items werden UNDEF. Regeln und Dashboards können dann „der Sensor misst 0“ von „der Sensor ist weg“ unterscheiden, was bei allem, das Heizung, Bewässerung oder Alarme steuert, sehr wichtig ist.

Checkliste zur Fehlersuche

Die Bridge bleibt OFFLINE. Prüfen Sie Host und Port und dass secure=true nur zusammen mit Port 8883 gesetzt ist. Suchen Sie in openhab.log nach dem Reason Code.
Die Bridge wechselt ständig zwischen ONLINE und OFFLINE. Doppelte Client-ID; eine andere openHAB-Instanz oder ein Testtool verwendet dieselbe.
Thing ONLINE, aber Item NULL. Falsche Kanal-UID im Item, ein Tippfehler im Topic oder das JSONPath-Add-on fehlt. Mit log:set DEBUG org.openhab.binding.mqtt in der Konsole sehen Sie jede empfangene Nachricht.
Der Schalter zeigt UNDEF. Der Payload entspricht nicht exakt on oder off; die Werte unterscheiden Groß- und Kleinschreibung.
Befehle bewirken nichts. Stellen Sie sicher, dass das Gerät auf dem Befehls-Topic lauscht und dass Sie nicht auf seinem Zustands-Topic veröffentlichen.

Wo openHAB in ein größeres System passt

openHAB ist ein Konsument am Broker, nicht der Eigentümer der Daten. ESPHome-Knoten, Tasmota-Steckdosen und Zigbee2MQTT können alle auf denselben Broker veröffentlichen, und andere Tools können dieselben Topics lesen. Das Tutorial zu ESPHome MQTT zeigt, wie Sie von per YAML konfigurierten Geräten veröffentlichen, und Tasmota MQTT behandelt geflashte smarte Steckdosen. Wer openHAB in gewerblichen Gebäuden oder auf einem Werksgelände einsetzt, sollte die Topics früh hierarchisch ordnen (Standort, Gebäude, Etage, Raum), damit sie sich später in einen Unified Namespace (UNS) nach ISA-95 einfügen lassen. Das große architektonische Bild finden Sie im Leitfaden zur IoT-Automatisierung. Und falls Sie noch Broker vergleichen, erklärt der Überblick über einen Cloud-MQTT-Broker die Abwägungen.

openHAB auf einem ConnectMQ-Broker betreiben

ConnectMQ stellt einen privaten MQTT-3.1.1- und 5.0-Broker mit TLS, generierten Zugangsdaten und einem Live-Topic-Explorer bereit, der das Debugging von openHAB-Kanälen unkompliziert macht. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker ohne Kreditkarte, fügen Sie die Zugangsdaten in Ihre Bridge ein, und Ihre openHAB-Things sind online.

Häufig gestellte Fragen

Bringt openHAB einen eigenen MQTT-Broker mit?

Nein. Aktuelle openHAB-Versionen liefern nur das Client-Binding, Sie benötigen also einen externen Broker, etwa eine lokale Mosquitto-Instanz oder einen Cloud-Broker wie ConnectMQ.

Kann openHAB MQTT 5 verwenden?

Die Broker-Bridge hat einen Parameter mqttVersion, der auf V5 gesetzt werden kann. Version 3.1.1 bleibt der Standard und funktioniert mit nahezu allen Geräten.

Wie viele MQTT-Verbindungen nutzt openHAB?

Eine pro Broker-Bridge, unabhängig davon, wie viele generische Things darunter liegen. Das macht es auf Plänen mit begrenzten Verbindungen effizient.

Warum werden meine Items aktualisiert, aber keine Befehle gesendet?

Wahrscheinlich hat der Kanal kein commandTopic, oder das Item ist nur lesend verknüpft. Ergänzen Sie ein Befehls-Topic und prüfen Sie mit einem Subscriber, ob die Nachricht veröffentlicht wird.

openHAB MQTT Binding Tutorial: Broker-Bridge, generische Things und Regeln