openHAB MQTT : bridge broker, things et règles

Q: openHAB peut-il utiliser MQTT 5 ?

Le bridge broker dispose d'un paramètre mqttVersion qui peut être réglé sur V5. La version 3.1.1 reste la valeur par défaut et fonctionne avec presque tous les appareils.

Q: Pourquoi mes items se mettent-ils à jour alors que les commandes ne sont pas envoyées ?

Le canal n'a probablement pas de commandTopic, ou l'item est lié en lecture seule. Ajoutez un topic de commande et vérifiez avec un abonné que le message est bien publié.

Le binding MQTT d'openHAB transforme n'importe quel topic MQTT en canaux que vous pouvez lier à des items, afficher dans des tableaux de bord et utiliser dans des règles. Dans ce tutoriel, vous allez connecter openHAB à un broker externe, définir des generic MQTT things pour un capteur et un interrupteur, analyser des payloads JSON, publier des commandes depuis des règles, puis renforcer la configuration avec TLS et des identifiants. openHAB est l'une des plateformes open source de maison connectée les plus répandues ; Jeedom et Domoticz savent aussi communiquer en MQTT.

Organisation du binding MQTT d'openHAB

openHAB modélise MQTT en deux couches. Le bridge broker (mqtt:broker) représente la connexion : hôte, port, TLS, client ID et identifiants. En dessous se trouvent des things, chacun décrivant un appareil par ses topics. Le type de thing le plus souple est le generic MQTT thing (mqtt:topic), dans lequel vous déclarez chaque canal ainsi que les topics d'état et de commande qu'il utilise. Les items se lient ensuite à ces canaux exactement comme avec n'importe quel autre binding.

Couche	Type de thing	Contient
Connexion	`mqtt:broker` (bridge)	Hôte, port, TLS, client ID, nom d'utilisateur, mot de passe, last will
Appareil	`mqtt:topic` (generic thing)	Canaux avec topics d'état et de commande
Appareil (auto)	Things Home Assistant ou Homie	Créés à partir des messages de découverte
Modèle	Items	Liés aux canaux, utilisés dans l'interface et les règles

Un seul bridge broker peut desservir des centaines de things, et il n'utilise qu'une seule connexion MQTT. C'est important sur les offres soumises à un quota de connexions : openHAB compte pour un seul client, quel que soit le nombre d'appareils qu'il modélise.

Installez le binding depuis Settings > Add-on Store > Bindings > MQTT Binding. Si vos appareils envoient du JSON, installez aussi la JSONPath Transformation dans la section des transformations.

Connecter openHAB à un broker MQTT

Vous pouvez créer le bridge dans l'interface (Things > + > MQTT Binding > MQTT Broker) ou dans un fichier .things. La configuration textuelle est plus facile à partager et à sauvegarder ; c'est donc elle que nous utilisons dans ce tutoriel. Créez 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"
        ]
    }
}

Cette configuration se connecte anonymement au serveur MQTT public gratuit, réservé aux tests. Remplacez r4t8w1 par votre propre chaîne aléatoire, car l'espace public est partagé et lisible par tous. Le client ID doit être non vide et unique ; en réutiliser un déjà détenu par un autre client fera tomber les deux connexions à répétition.

Consultez Settings > Things : le bridge doit passer à ONLINE en quelques secondes, suivi du thing de la serre.

Lier les items

Créez 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" }

Notez le format de l'UID de canal : mqtt:topic:<bridge id>:<thing id>:<channel id>. Une faute de frappe à cet endroit est la raison la plus fréquente pour laquelle un item reste à NULL.

Tester les canaux MQTT d'openHAB

Simulez l'appareil depuis un terminal :

# mesure du capteur (JSON analysé par JSONPath)
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/telemetry' -m '{"temp":24.6,"hum":71}'

# contact de porte
mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/door' -m 'OPEN'

# observer les commandes envoyées par openHAB
mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-r4t8w1 \
  -t 'connectmq/demo/r4t8w1/greenhouse/fan/set' -v

Basculez le ventilateur dans l'interface d'openHAB : la commande ON ou OFF apparaît dans la fenêtre de l'abonné. Un véritable appareil l'exécuterait et publierait son nouvel état sur fan/state, qu'openHAB utilise pour mettre l'item à jour. Séparer les topics de commande et d'état permet à l'interface d'afficher l'état confirmé, et pas seulement le dernier clic.

Analyser le JSON et formater les commandes

La plupart des appareils modernes publient du JSON. En plus de transformationPattern pour les valeurs entrantes, le generic thing prend en charge formatBeforePublish pour les valeurs sortantes. Par exemple, pour un variateur qui attend {"brightness": 40} :

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
]

Les transformations peuvent être enchaînées avec le caractère ∩ dans le motif si vous avez besoin de plusieurs étapes, par exemple un JSONPath suivi d'une table MAP. Gardez des chaînes courtes ; lorsque la logique se complexifie, une règle est plus facile à déboguer.

Publier des messages MQTT depuis les règles openHAB

Les commandes liées aux canaux couvrent la plupart des besoins, mais il arrive que vous vouliez publier sur un topic arbitraire, par exemple pour envoyer un planning à un contrôleur. Le bridge broker expose pour cela une action publishMQTT. Dans un fichier de règles DSL 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

La même action est disponible depuis les règles JavaScript via actions.get("mqtt", "mqtt:broker:connectmq"). Évitez de publier sur un topic auquel un canal est abonné, sauf si vous souhaitez créer une boucle.

Déclencher des règles à partir de topics bruts

Si vous voulez simplement réagir à un message sans modéliser d'item, ajoutez un canal de déclenchement au bridge :

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

Une règle déclenchée par Channel "mqtt:broker:connectmq:alarms" triggered reçoit le topic et le payload joints par le séparateur : une seule règle peut ainsi traiter les alarmes de tous les appareils.

Configuration de production avec TLS et identifiants

Avant de connecter de vrais appareils, quittez l'espace de test public. Créez un broker privé, puis mettez à jour le 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
]

Le certificat de ConnectMQ est émis par Let's Encrypt, autorité à laquelle Java fait confiance par défaut : aucune importation de certificat supplémentaire n'est nécessaire. L'épinglage de certificat est explicitement désactivé, car les certificats Let's Encrypt sont renouvelés tous les quelques mois ; un certificat épinglé ferait rejeter le broker par le bridge après le renouvellement suivant. Utilisez le client ID exactement tel qu'il a été attribué, puisqu'il est lié aux identifiants. Pour sécuriser l'ensemble du système, lisez les bonnes pratiques de sécurité MQTT.

Si vous préférez faire tourner votre broker localement dans le réseau d'openHAB, vous pourrez toujours le relier au cloud plus tard, mais un broker MQTT managé vous évite d'entretenir un hôte dédié au broker et permet aux sites distants et aux téléphones d'accéder aux mêmes topics.

Afficher la disponibilité des appareils

Un generic thing reste ONLINE tant que le bridge est connecté, même si l'appareil qui se trouve derrière a perdu son alimentation depuis des heures. Pour rendre cela visible, faites publier à chaque appareil un message online retenu lors de sa connexion et définissez un last will offline retenu. Ajoutez ensuite des paramètres de disponibilité au thing :

Thing topic greenhouse "Greenhouse Sensor" [
    availabilityTopic="connectmq/demo/r4t8w1/greenhouse/status",
    payloadAvailable="online",
    payloadNotAvailable="offline"
] {
    // canaux comme précédemment
}

Lorsque l'appareil disparaît, le broker publie son will, openHAB marque le thing OFFLINE et les items liés passent à UNDEF. Les règles et les tableaux de bord peuvent alors distinguer « le capteur indique 0 » de « le capteur a disparu », ce qui compte énormément pour tout ce qui pilote le chauffage, l'arrosage ou des alarmes.

Liste de contrôle de dépannage

Le bridge reste OFFLINE. Vérifiez l'hôte et le port, et que secure=true n'est défini qu'avec le port 8883. Cherchez le code de raison dans openhab.log.
Le bridge oscille entre ONLINE et OFFLINE. Client ID en double : une autre instance openHAB ou un outil de test utilise le même.
Thing ONLINE mais item à NULL. UID de canal erroné dans l'item, faute de frappe dans un topic, ou module JSONPath manquant. Utilisez log:set DEBUG org.openhab.binding.mqtt dans la console pour voir chaque message reçu.
L'interrupteur affiche UNDEF. Le payload ne correspond pas exactement à on ou off ; les valeurs sont sensibles à la casse.
Les commandes n'ont aucun effet. Assurez-vous que l'appareil écoute le topic de commande et que vous ne publiez pas sur son topic d'état.

La place d'openHAB dans un système plus large

openHAB est un consommateur parmi d'autres sur le broker, pas le propriétaire des données. Des nœuds ESPHome, des prises Tasmota et Zigbee2MQTT peuvent tous publier sur le même broker, et d'autres outils peuvent lire les mêmes topics. Le tutoriel ESPHome MQTT montre comment publier depuis des appareils configurés en YAML, et Tasmota MQTT traite des prises connectées reflashées. Pour une vision architecturale plus large, consultez le guide d'automatisation IoT. Et si vous comparez encore les brokers, la présentation d'un broker MQTT cloud en explique les compromis.

Faites tourner openHAB sur un broker ConnectMQ

ConnectMQ fournit un broker MQTT 3.1.1 et 5.0 privé avec TLS, des identifiants générés et un explorateur de topics en direct qui simplifie le débogage des canaux openHAB. Créez gratuitement un broker Serverless sur app.connectmq.com sans carte bancaire, collez les identifiants dans votre bridge, et vos things openHAB sont en ligne.

Questions fréquentes

openHAB inclut-il son propre broker MQTT ?

Non. Les versions actuelles d'openHAB ne fournissent que le binding client ; vous avez donc besoin d'un broker externe, comme une instance Mosquitto locale ou un broker cloud tel que ConnectMQ.

openHAB peut-il utiliser MQTT 5 ?

Le bridge broker dispose d'un paramètre mqttVersion qui peut être réglé sur V5. La version 3.1.1 reste la valeur par défaut et fonctionne avec presque tous les appareils.

Combien de connexions MQTT openHAB utilise-t-il ?

Une par bridge broker, quel que soit le nombre de generic things placés en dessous. Cela le rend efficace sur les offres limitées en connexions.

Pourquoi mes items se mettent-ils à jour alors que les commandes ne sont pas envoyées ?

Le canal n'a probablement pas de commandTopic, ou l'item est lié en lecture seule. Ajoutez un topic de commande et vérifiez avec un abonné que le message est bien publié.

Tutoriel binding MQTT openHAB : bridge broker, generic things et règles