Homebridge MQTT : intégrer vos appareils MQTT dans Apple Maison

L'intégration MQTT de Homebridge vous permet de piloter des capteurs, relais et lampes faits maison depuis l'app Maison d'Apple et avec Siri, alors même que HomeKit ne connaît rien à MQTT. Dans ce tutoriel, vous allez installer le plugin mqttthing, associer des topics aux caractéristiques HomeKit pour un capteur de température, un interrupteur, une lampe à variateur et un capteur de contact, gérer des payloads JSON, puis migrer la configuration vers un broker TLS privé.

Comment Homebridge communique avec MQTT

Homebridge est un serveur Node.js qui émule des accessoires HomeKit. Les plugins fournissent la logique propre à chaque appareil. Le plugin MQTT le plus utilisé, homebridge-mqttthing, vous permet de déclarer un accessoire en JSON et d'associer chaque caractéristique HomeKit à un topic MQTT : un topic get auquel Homebridge s'abonne pour connaître la valeur actuelle, et un topic set sur lequel il publie lorsque vous touchez une vignette ou que vous sollicitez Siri.

 Apple Home / Siri
        |
   (HomeKit, LAN)
        |
    Homebridge  --  homebridge-mqttthing
        |
   (MQTT over TLS)
        |
   MQTT broker  <-->  ESP32, Tasmota, Zigbee2MQTT, scripts

Comme les appareils ne dialoguent qu'avec le broker, ils peuvent se trouver sur un autre réseau, voire sur un autre site. Homebridge n'a besoin que d'un accès sortant vers le broker. Si vous souhaitez d'abord comprendre ce modèle, l'article sur ce que fait un broker MQTT explique simplement la publication et l'abonnement.

Installer le plugin mqttthing

Si vous utilisez l'interface Homebridge UI (par défaut dans les images officielles), ouvrez Plugins, recherchez mqttthing et installez Homebridge Mqttthing. En ligne de commande, sur un hôte Homebridge :

sudo npm install -g homebridge-mqttthing
sudo hb-service restart

Les accessoires se définissent dans le tableau accessories de config.json. L'interface propose un éditeur sous forme de formulaire pour le plugin, mais le JSON brut est plus clair pour apprendre ; les exemples ci-dessous l'utilisent donc. Vous pouvez les coller dans Config > JSON Config.

Un premier accessoire Homebridge MQTT : le capteur de température

Commencez avec le serveur MQTT public gratuit, réservé aux tests, pour observer tout ce qui se passe. Choisissez une chaîne aléatoire (ici h3m8x2) pour isoler vos topics dans l'espace public partagé.

{
  "accessory": "mqttthing",
  "type": "temperatureSensor",
  "name": "Greenhouse Temperature",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-gh-temp-h3m8x2" },
  "topics": {
    "getCurrentTemperature": "connectmq/demo/h3m8x2/greenhouse/temperature"
  },
  "logMqtt": true
}

Enregistrez, redémarrez Homebridge, puis publiez une mesure :

mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-h3m8x2 \
  -t 'connectmq/demo/h3m8x2/greenhouse/temperature' -m '23.5' -r

La vignette se met à jour dans l'app Maison en moins d'une seconde. L'option -r rend le message retenu : après un redémarrage de Homebridge, la dernière valeur est donc livrée immédiatement, au lieu que la vignette affiche « Pas de réponse » jusqu'à la mesure suivante.

Interrupteurs et lampes avec commandes

Les accessoires pilotables ont besoin d'un topic get et d'un topic set. Utiliser des topics distincts pour les commandes et pour l'état confirmé est une bonne pratique : Homebridge publie la demande, l'appareil l'exécute, puis publie en retour son état réel.

{
  "accessory": "mqttthing",
  "type": "switch",
  "name": "Vent Fan",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-fan-h3m8x2" },
  "topics": {
    "getOn": "connectmq/demo/h3m8x2/greenhouse/fan/state",
    "setOn": "connectmq/demo/h3m8x2/greenhouse/fan/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Une lampe à variateur ajoute une caractéristique de luminosité :

{
  "accessory": "mqttthing",
  "type": "lightbulb",
  "name": "Grow Light",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-light-h3m8x2" },
  "topics": {
    "getOn": "connectmq/demo/h3m8x2/greenhouse/light/state",
    "setOn": "connectmq/demo/h3m8x2/greenhouse/light/set",
    "getBrightness": "connectmq/demo/h3m8x2/greenhouse/light/brightness",
    "setBrightness": "connectmq/demo/h3m8x2/greenhouse/light/brightness/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Observez ce qu'envoie Homebridge pendant que vous touchez les vignettes :

mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-h3m8x2 \
  -t 'connectmq/demo/h3m8x2/greenhouse/#' -v

Gérer les payloads JSON

De nombreux appareils publient un seul document JSON contenant plusieurs valeurs plutôt qu'un topic par valeur. mqttthing accepte un objet topic doté d'une fonction apply, un court corps JavaScript qui reçoit message et renvoie la valeur à utiliser.

{
  "accessory": "mqttthing",
  "type": "contactSensor",
  "name": "Greenhouse Door",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-door-h3m8x2" },
  "topics": {
    "getContactSensorState": {
      "topic": "connectmq/demo/h3m8x2/greenhouse/telemetry",
      "apply": "return JSON.parse(message).door === 'open' ? 1 : 0;"
    }
  }
}

Le capteur de contact HomeKit utilise 0 pour « détecté » (fermé) et 1 pour « non détecté » (ouvert), c'est pourquoi la fonction associe open à 1. La même technique s'applique aux topics set pour encapsuler une commande dans du JSON, par exemple "apply": "return JSON.stringify({state: message});".

Correspondance des types d'appareils courants

Le plugin prend en charge bien d'autres types, notamment les portes de garage, les thermostats, les ventilateurs et les stores. Chacun possède ses propres noms de caractéristiques ; le README du plugin les répertorie tous.

Nombre de connexions et client ID

Chaque accessoire mqttthing ouvre sa propre connexion MQTT. Dix accessoires représentent donc dix clients sur le broker, chacun nécessitant un client ID unique. Deux conséquences en découlent :

1. Donnez à chaque accessoire son propre clientId dans mqttOptions. Des ID en double poussent le broker à déconnecter la session précédente, et les accessoires alternent entre « répond » et « ne répond pas ».
2. Comptez les connexions par rapport à votre offre. L'offre gratuite Serverless de ConnectMQ autorise jusqu'à 25 connexions simultanées, ce qui couvre Homebridge et un nombre raisonnable d'appareils. Les installations plus importantes trouvent leur place dans l'offre Serverless payante, avec jusqu'à 1 000 connexions.

Si vous avez besoin de nombreux accessoires sur une seule connexion, envisagez de confier la connexion au broker à Home Assistant ou à Node-RED et d'exposer HomeKit via leurs propres ponts HomeKit. Jeedom et Domoticz savent aussi communiquer en MQTT.

Production : TLS et identifiants

Tout ce qui se trouve sur le serveur MQTT public gratuit peut être lu par quiconque devine le topic, et quelqu'un pourrait aussi publier sur vos topics set. Avant de piloter de vrais équipements, créez un broker privé et passez chaque accessoire en TLS :

{
  "accessory": "mqttthing",
  "type": "switch",
  "name": "Vent Fan",
  "url": "mqtts://broker.connectmq.com:8883",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "mqttOptions": { "clientId": "YOUR_CLIENT_ID" },
  "topics": {
    "getOn": "site1/greenhouse/fan/state",
    "setOn": "site1/greenhouse/fan/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Node.js fait confiance d'emblée à la chaîne Let's Encrypt utilisée par ConnectMQ ; aucun fichier CA n'est donc nécessaire. Sur ConnectMQ, les client ID sont liés aux identifiants émis dans le portail : lorsque vous avez besoin de plusieurs connexions, générez un jeu d'identifiants par groupe d'accessoires et notez quel ID est utilisé où.

Exécuter mqttthing en pont enfant

Homebridge peut exécuter un plugin en tant que pont enfant (child bridge) : un processus séparé, avec son propre appairage HomeKit. L'activer pour mqttthing (dans les paramètres du plugin, Bridge Settings) présente deux avantages concrets. Un plantage ou une définition d'accessoire défaillante n'entraîne plus la chute de tous les autres plugins, et redémarrer le pont enfant après avoir modifié des topics est plus rapide que de redémarrer tout Homebridge. Vous appairez le pont enfant une seule fois dans l'app Maison, et les accessoires ajoutés ensuite apparaissent automatiquement.

Il est également judicieux de publier depuis chaque appareil un topic de disponibilité retenu avec un last will offline. mqttthing peut l'exploiter via le topic getOnline associé à onlineValue et offlineValue, de sorte qu'Apple Maison affiche l'appareil comme ne répondant pas lorsqu'il est réellement hors ligne, au lieu d'afficher une valeur périmée.

Dépannage de Homebridge MQTT

• L'accessoire affiche « Pas de réponse ». Aucune valeur n'est arrivée sur le topic get depuis le démarrage de Homebridge. Publiez un état retenu depuis les appareils, ou vérifiez les fautes de frappe dans le topic avec logMqtt: true.
• La vignette revient d'elle-même à son état précédent. L'appareil ne publie pas son nouvel état sur le topic get, ou publie une valeur qui ne correspond pas à onValue.
• Messages de reconnexion permanents dans le journal. Client ID en double ou identifiants erronés. Cherchez Connection refused et le motif associé dans le journal de Homebridge.
• Siri indique que l'appareil ne répond pas, mais l'app fonctionne. C'est généralement un problème de concentrateur HomeKit (Apple TV ou HomePod) plutôt que de MQTT ; vérifiez que le concentrateur peut joindre Homebridge sur le réseau local.

Pour aller plus loin

Homebridge s'occupe du côté Apple ; les appareils doivent toujours publier des topics cohérents. Le guide ESPHome MQTT montre comment construire des capteurs qui publient leur état et acceptent des commandes, et l'article sur la structure des topics MQTT pour la maison connectée vous aide à concevoir des topics qui restent faciles à gérer. Si Home Assistant tourne aux côtés de Homebridge, consultez Home Assistant avec un broker MQTT externe. Pour une vision plus large de la combinaison entre appareils et logique, lisez le guide d'automatisation IoT ; et pour comprendre pourquoi un broker MQTT managé est préférable à un broker sur le Raspberry Pi de Homebridge pour l'accès à distance, comparez-y les options.

Connectez Homebridge à ConnectMQ

ConnectMQ offre à Homebridge un broker privé sécurisé par TLS, accessible depuis n'importe quel réseau, avec un explorateur de topics en direct pour déboguer vos accessoires au fil de leur configuration. Créez gratuitement un broker Serverless sur app.connectmq.com, sans carte bancaire, et collez les identifiants générés dans vos accessoires mqttthing.

Questions fréquentes

HomeKit prend-il en charge MQTT nativement ?

Non. HomeKit utilise son propre protocole d'accessoires ; il vous faut donc un pont comme Homebridge avec un plugin MQTT pour assurer la traduction entre les deux.

Puis-je piloter mes appareils Homebridge MQTT lorsque je ne suis pas chez moi ?

Oui, via un concentrateur domestique HomeKit, comme d'habitude. Comme les appareils dialoguent avec un broker cloud, ils peuvent même se trouver sur un autre site que Homebridge.

Pourquoi mes capteurs affichent-ils « Pas de réponse » après un redémarrage ?

Homebridge n'a pas encore reçu de valeur. Publiez les messages d'état avec l'indicateur retain pour que le broker transmette la dernière valeur dès que Homebridge s'abonne.

mqttthing est-il le seul plugin MQTT pour Homebridge ?

Non, mais c'est le plus polyvalent. D'autres plugins ciblent des écosystèmes précis comme Zigbee2MQTT ou Tasmota et peuvent être plus simples si vous n'utilisez que ces appareils.