Tutoriel du binding MQTT d'openHAB : broker, Things et canaux

Le binding MQTT d'openHAB relie openHAB à n'importe quel broker MQTT en deux niveaux : un Thing broker (un bridge qui porte la connexion : hôte, port, TLS, identifiants) et un ou plusieurs Generic MQTT Things en dessous, dont les canaux associent des topics précis à des Items openHAB. Installez le binding, ajoutez le broker, créez un Thing avec un canal par valeur, liez les Items : chaque message sur ces topics met à jour vos Items, et les commandes de l'interface ou des règles sont republiées.

Ce tutoriel couvre la configuration par l'interface et par fichiers texte, montre comment interpréter des payloads JSON et comment vérifier chaque saut en ligne de commande.

Prérequis

• openHAB 4.x ou plus récent avec le MQTT Binding installé (Settings → Add-on Store → Bindings → MQTT).
• L'add-on JSONPath Transformation si vos appareils envoient du JSON (c'est le cas de la plupart).
• Un broker. openHAB n'en inclut pas : lancez Mosquitto en local ou utilisez un broker hébergé. Les exemples utilisent broker.connectmq.com avec TLS sur le port 8883 et des topics de test sous testmqtt/openhab/....

Étape 1 : le Thing bridge du broker

Dans l'interface, allez dans Settings → Things → + → MQTT Binding → MQTT Broker et renseignez :

Laissez le pinning de certificat et de clé publique désactivé si votre broker utilise un certificat public renouvelé automatiquement : le pinning mémorise le premier certificat vu et échoue dès que le broker le remplace. Pour dépanner la partie TLS, voir tester une connexion TLS.

Le Thing broker doit passer ONLINE en quelques secondes. S'il affiche OFFLINE - COMMUNICATION_ERROR, le détail du statut contient la raison, en général une incohérence port/TLS ou de mauvais identifiants.

Vous pouvez aussi configurer un Last Will (lwtTopic, lwtMessage) ainsi que des messages de naissance et d'arrêt, pour que d'autres systèmes sachent si openHAB est connecté ; utile quand un dashboard ou Node-RED en dépend.

Étape 2 : un Generic MQTT Thing et ses canaux

Ajoutez un Generic MQTT Thing, choisissez le broker comme bridge, puis ajoutez des canaux dans l'onglet Channels. Chaque canal a un type et, au minimum, un state topic :

Les paramètres de canal importants :

• State Topic : openHAB s'y abonne et met à jour l'Item.
• Command Topic : openHAB y publie quand l'Item reçoit une commande. Utilisez un topic différent du state topic (par exemple .../set), sinon vos propres commandes reviennent comme des mises à jour d'état.
• Incoming Value Transformations : par exemple JSONPATH:$.temperature.
• Outgoing Value Format : une chaîne de format comme %s ou {"state":"%s"} pour envelopper les commandes en JSON.
• Retained : publie les commandes en messages retenus ; lisez messages retenus avant de l'activer.
• Custom On/Open Value et Custom Off/Closed Value : associent des payloads d'appareil comme 1/0 ou true/false.
• Is Command (postCommand) : traite les valeurs entrantes comme des commandes plutôt que comme des mises à jour d'état, afin qu'elles déclenchent d'autres bindings et règles.

La même configuration en fichiers texte

Pour le contrôle de version, définissez le broker et les Things dans un fichier .things :

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" ]
    }
}

L'UID du canal est mqtt:topic:connectmq:livingroom:<canal>. Liez-y les Items :

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" }

Deux canaux partagent un state topic et extraient des champs JSON différents : le schéma habituel pour les appareils multicapteurs. L'availabilityTopic passe le Thing en OFFLINE quand le Last Will de l'appareil se déclenche.

Publier depuis des règles

Le Thing broker expose une action publishMQTT, pratique pour des notifications ou pour dialoguer avec des appareils sans 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

Pour une écoute générique, ajoutez un canal Publish trigger sur le Thing broker lui-même : son state topic accepte les wildcards (testmqtt/openhab/+/event) et les règles reçoivent topic#payload comme événement.

Tester chaque saut

Entrant : publiez une mesure de capteur simulée et regardez les Items changer :

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 avec les paquets Linux) doit afficher Item 'LivingRoom_Temperature' changed from NULL to 21.5 °C.

Sortant : abonnez-vous au command topic et basculez l'interrupteur dans l'interface ou depuis la console openHAB :

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

# dans un autre shell : openhab-cli console, puis
openhab> openhab:send LivingRoom_Lamp ON

Vous devez voir testmqtt/openhab/livingroom/lamp/set ON. Si vous préférez le navigateur, le client MQTT en ligne fonctionne tout aussi bien dans les deux sens.

Observer le trafic MQTT d'openHAB dans le navigateur

Si rien ne se passe, augmentez le niveau de log dans la console avec log:set DEBUG org.openhab.binding.mqtt et log:set DEBUG org.openhab.core.io.transport.mqtt. Causes fréquentes : l'Item est lié à un autre UID de canal, le JSONPath ne correspond pas (la valeur reste NULL et un avertissement de transformation est journalisé) ou le topic diffère d'un caractère ; collez les deux dans le topic matcher pour vérifier.

Découverte automatique : Homie et Home Assistant

Le binding comprend aussi deux conventions de découverte. Les appareils qui s'annoncent via la convention Homie ou la Home Assistant MQTT discovery (Tasmota, ESPHome, Zigbee2MQTT avec la discovery activée) apparaissent dans l'Inbox d'openHAB avec leurs canaux déjà créés. Cela évite de la saisie, mais les Generic Things restent l'option la plus prévisible pour un firmware maison et pour des appareils comme Shelly ou Zigbee2MQTT lorsque vous voulez maîtriser entièrement les noms de topics. Quel que soit votre choix, une conception cohérente des topics pour la maison connectée garde la configuration des canaux concise.

Le binding MQTT d'openHAB devient simple dès que les deux niveaux sont clairs : un Thing broker par connexion, des Generic MQTT Things avec un canal par valeur, des Items liés aux canaux. Commencez par un seul canal, validez-le avec mosquitto_pub et events.log, puis ajoutez le reste de la maison.

Questions fréquentes