openHAB MQTT-Binding Anleitung: Broker, Things und Channels

Das openHAB MQTT-Binding verbindet openHAB in zwei Ebenen mit jedem MQTT-Broker: einem Broker-Thing (eine Bridge, die die Verbindung hält: Host, Port, TLS, Zugangsdaten) und einem oder mehreren Generic MQTT Things darunter, deren Channels einzelne Topics auf openHAB-Items abbilden. Binding installieren, Broker anlegen, ein Thing mit einem Channel pro Wert erstellen, Items verknüpfen – und jede Nachricht auf diesen Topics aktualisiert deine Items, während Befehle aus der UI oder aus Regeln zurückpubliziert werden.

Dieses Tutorial zeigt sowohl die Konfiguration über die UI als auch über Textdateien, erklärt die Auswertung von JSON-Payloads und wie du jeden Hop auf der Kommandozeile prüfst.

Voraussetzungen

• openHAB 4.x oder neuer mit installiertem MQTT Binding (Settings → Add-on Store → Bindings → MQTT).
• Das Add-on JSONPath Transformation, wenn deine Geräte JSON senden (die meisten tun das).
• Einen Broker. openHAB bringt keinen mit, also betreibe Mosquitto lokal oder nutze einen gehosteten Broker. Die Beispiele verwenden broker.connectmq.com mit TLS auf Port 8883 und Test-Topics unter testmqtt/openhab/....

Schritt 1: das Broker-Bridge-Thing

Gehe in der UI zu Settings → Things → + → MQTT Binding → MQTT Broker und trage ein:

Lass Certificate- und Public-Key-Pinning aus, wenn dein Broker ein öffentliches, automatisch erneuertes Zertifikat nutzt: Pinning speichert das erste gesehene Zertifikat und schlägt fehl, sobald der Broker es austauscht. Zur Fehlersuche auf der TLS-Seite siehe TLS-Verbindung testen.

Das Broker-Thing sollte innerhalb weniger Sekunden auf ONLINE wechseln. Zeigt es OFFLINE - COMMUNICATION_ERROR, steht der Grund im Status-Detail – meist eine Port/TLS-Unstimmigkeit oder falsche Zugangsdaten.

Du kannst außerdem einen Last Will (lwtTopic, lwtMessage) sowie Birth- und Shutdown-Nachrichten konfigurieren, damit andere Systeme wissen, ob openHAB verbunden ist – nützlich, wenn ein Dashboard oder Node-RED davon abhängt.

Schritt 2: ein Generic MQTT Thing und seine Channels

Lege ein Generic MQTT Thing an, wähle den Broker als Bridge und füge im Tab Channels Channels hinzu. Jeder Channel hat einen Typ und mindestens ein State-Topic:

Die wichtigen Channel-Parameter:

• State Topic – openHAB abonniert es und aktualisiert das Item.
• Command Topic – openHAB publiziert hierhin, wenn das Item einen Befehl erhält. Nimm ein anderes Topic als das State-Topic (z. B. .../set), sonst kommen deine eigenen Befehle als Zustandsänderungen zurück.
• Incoming Value Transformations – z. B. JSONPATH:$.temperature.
• Outgoing Value Format – ein Format-String wie %s oder {"state":"%s"}, um Befehle in JSON zu verpacken.
• Retained – publiziert Befehle als Retained Messages; lies Retained Messages, bevor du das aktivierst.
• Custom On/Open Value und Custom Off/Closed Value – bilden Geräte-Payloads wie 1/0 oder true/false ab.
• Is Command (postCommand) – behandelt eingehende Werte als Befehle statt als Zustandsupdates, damit sie andere Bindings und Regeln auslösen.

Dieselbe Konfiguration als Textdateien

Für die Versionsverwaltung definierst du Broker und Things in einer .things-Datei:

Bridge mqtt:broker:connectmq "ConnectMQ broker" [
    host="broker.connectmq.com", port=8883, secure=true,
    certificatepin=false, publickeypin=false,
    protocol="TCP", mqttVersion="V5",
    clientID="openhab-home", username="username", password="password",
    keepAlive=60, qos=1
] {
    Thing topic livingroom "Living room" [
        availabilityTopic="testmqtt/openhab/livingroom/status",
        payloadAvailable="online", payloadNotAvailable="offline"
    ] {
        Channels:
            Type number : temperature "Temperature" [
                stateTopic="testmqtt/openhab/livingroom/sensor",
                transformationPattern="JSONPATH:$.temperature", unit="°C" ]
            Type number : humidity "Humidity" [
                stateTopic="testmqtt/openhab/livingroom/sensor",
                transformationPattern="JSONPATH:$.humidity", unit="%" ]
            Type switch : lamp "Lamp" [
                stateTopic="testmqtt/openhab/livingroom/lamp/state",
                commandTopic="testmqtt/openhab/livingroom/lamp/set",
                on="ON", off="OFF" ]
            Type trigger : button "Wall button" [
                stateTopic="testmqtt/openhab/livingroom/button" ]
    }
}

Die Channel-UID lautet mqtt:topic:connectmq:livingroom:<channel>. Verknüpfe Items damit:

Number:Temperature   LivingRoom_Temperature "Temperature [%.1f %unit%]" { channel="mqtt:topic:connectmq:livingroom:temperature" }
Number:Dimensionless LivingRoom_Humidity    "Humidity [%.0f %%]"        { channel="mqtt:topic:connectmq:livingroom:humidity" }
Switch               LivingRoom_Lamp        "Lamp"                      { channel="mqtt:topic:connectmq:livingroom:lamp" }

Zwei Channels teilen sich ein State-Topic und extrahieren unterschiedliche JSON-Felder – das übliche Muster für Multisensoren. Das availabilityTopic setzt das Thing auf OFFLINE, wenn der Last Will des Geräts ausgelöst wird.

Aus Regeln publizieren

Das Broker-Thing stellt eine publishMQTT-Action bereit, praktisch für Benachrichtigungen oder für Geräte ohne eigenes Thing:

rule "Publish lamp changes as an event"
when
    Item LivingRoom_Lamp changed
then
    val mqtt = getActions("mqtt", "mqtt:broker:connectmq")
    mqtt.publishMQTT("testmqtt/openhab/events/lamp", newState.toString, false)
end

rule "Wall button pressed"
when
    Channel "mqtt:topic:connectmq:livingroom:button" triggered
then
    LivingRoom_Lamp.sendCommand(if (LivingRoom_Lamp.state == ON) OFF else ON)
end

Für Catch-all-Listener fügst du dem Broker-Thing selbst einen Publish trigger-Channel hinzu: Sein State-Topic akzeptiert Wildcards (testmqtt/openhab/+/event), und Regeln erhalten topic#payload als Event.

Jeden Hop testen

Eingehend – publiziere einen simulierten Sensorwert und beobachte, wie sich die Items ändern:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/openhab/livingroom/sensor' -m '{"temperature": 21.5, "humidity": 48}'

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/openhab/livingroom/status' -m online -r

events.log (/var/log/openhab/events.log bei Linux-Paketen) sollte Item 'LivingRoom_Temperature' changed from NULL to 21.5 °C zeigen.

Ausgehend – abonniere das Command-Topic und schalte den Switch in der UI oder über die openHAB-Konsole:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/openhab/#' -v

# in einer anderen Shell: openhab-cli console, dann
openhab> openhab:send LivingRoom_Lamp ON

Du solltest testmqtt/openhab/livingroom/lamp/set ON sehen. Wenn dir der Browser lieber ist, funktioniert der Online-MQTT-Client genauso gut in beide Richtungen.

openHABs MQTT-Traffic im Browser beobachten

Wenn nichts passiert, erhöhe in der Konsole den Log-Level mit log:set DEBUG org.openhab.binding.mqtt und log:set DEBUG org.openhab.core.io.transport.mqtt. Typische Ursachen: Das Item ist mit einer anderen Channel-UID verknüpft, der JSONPath passt nicht (der Wert bleibt NULL, und eine Transformations-Warnung wird geloggt), oder das Topic weicht um ein Zeichen ab – kopiere beide in den Topic Matcher, um es zu prüfen.

Auto-Discovery: Homie und Home Assistant

Das Binding versteht außerdem zwei Discovery-Konventionen. Geräte, die sich über die Homie-Konvention oder per Home Assistant MQTT Discovery ankündigen (Tasmota, ESPHome, Zigbee2MQTT mit aktivierter Discovery), erscheinen in der openHAB-Inbox mit fertigen Channels. Das spart Tipparbeit, aber Generic Things bleiben die berechenbarste Option für eigene Firmware und für Geräte wie Shelly oder Zigbee2MQTT, wenn du die volle Kontrolle über Topic-Namen willst. Was auch immer du wählst: Ein konsistentes Topic-Design fürs Smart Home hält die Channel-Konfiguration kurz.

Das openHAB MQTT-Binding ist einfach, sobald die zwei Ebenen klar sind: ein Broker-Thing pro Verbindung, Generic MQTT Things mit einem Channel pro Wert, Items mit Channels verknüpft. Beginne mit einem einzigen Channel, belege ihn mit mosquitto_pub und events.log und füge dann den Rest des Hauses hinzu.

Häufig gestellte Fragen