Faire apparaître les appareils Zigbee dans Home Assistant

Contexte

À ce stade, les briques sont en place mais fonctionnent encore en parallèle :

• Mosquitto tourne et accepte des publications (chapitres 7-8) ;
• zigbee2mqtt appaire les appareils Zigbee et publie leurs événements sur le broker (chapitre 10) — zigbee2mqtt/temperature_salon, zigbee2mqtt/prise_bureau, etc. ;
• Home Assistant est installé et abonné au broker (chapitre précédent).

Pourtant, dans l’interface HA, aucun de ces appareils n’apparaît. HA reçoit bien les messages — on peut le vérifier avec l’outil « Écouter un topic » — mais il ne sait pas quoi en faire. Pour HA, zigbee2mqtt/temperature_salon qui publie {"temperature":21.3,"humidity":54} n’est qu’une suite d’octets sans signification.

Il faut indiquer à HA quels capteurs existent, quel est leur type, où trouver leur valeur dans le JSON. Deux façons de faire :

1. À la main, en YAML, comme on l’a vu pour la téléinfo (chapitre 25) — déclarer chaque capteur avec son state_topic, son value_template, son device_class.
2. Automatiquement, via le mécanisme de MQTT Discovery.

Avec une vingtaine d’appareils Zigbee qui changent au gré des courses, la première option devient pénible. La seconde, c’est ce qu’on va activer.

Le mécanisme MQTT Discovery

L’idée est simple. Home Assistant écoute en permanence un préfixe de topic dédié — par défaut homeassistant/.... Tout périphérique qui veut s’annoncer publie sur ce préfixe un message décrivant son type, son nom, où trouver ses valeurs et toutes ses caractéristiques. HA reçoit ce message, crée automatiquement l’entité correspondante dans son interface, et s’abonne au topic de données indiqué.

Côté zigbee2mqtt, il suffit d’activer une option. Pour chaque appareil appairé, zigbee2mqtt génère et publie les messages de découverte correspondants. Tous les capteurs apparaissent dans HA en quelques secondes, avec les bonnes unités, les bonnes icônes, les bonnes classes.

Concrètement, voici le flux pour un capteur de température :

zigbee2mqtt → publie sur homeassistant/sensor/0x001788010..../temperature/config
              {
                "name": "Salon Température",
                "state_topic": "zigbee2mqtt/temperature_salon",
                "value_template": "{{ value_json.temperature }}",
                "unit_of_measurement": "°C",
                "device_class": "temperature",
                ...
              }

HA → reçoit le message, comprend "c'est un capteur de température"
   → crée l'entité sensor.salon_temperature
   → s'abonne à zigbee2mqtt/temperature_salon
   → met à jour la valeur à chaque publication

Tout cela se passe sans intervention humaine. On appaire un nouvel appareil dans zigbee2mqtt, on lui donne un nom amical, il apparaît dans HA dans la foulée.

Activer Discovery côté zigbee2mqtt

Éditer le fichier de configuration de zigbee2mqtt :

sudo nano /opt/zigbee2mqtt/data/configuration.yaml

Ajouter (ou vérifier) le bloc :

homeassistant: true

C’est tout. La valeur true active la publication des messages de découverte sur le préfixe par défaut homeassistant/. Si l’on a personnalisé ce préfixe côté HA (rare), on peut spécifier :

homeassistant:
  discovery_topic: homeassistant

Redémarrer zigbee2mqtt pour appliquer :

sudo systemctl restart zigbee2mqtt

Suivre le journal pour voir les messages de découverte partir :

sudo journalctl -u zigbee2mqtt -f

On y voit défiler des lignes du type « MQTT publish: topic 'homeassistant/sensor/.../config' » — une par capacité de chaque appareil.

Vérifier côté Home Assistant

L’intégration MQTT côté HA doit avoir la découverte activée — c’est le comportement par défaut, mais on peut vérifier :

Paramètres → Appareils & services → MQTT → Configurer → la case « Activer la découverte » doit être cochée.

Une fois zigbee2mqtt redémarré, retourner dans Appareils & services → MQTT → Appareils. Les appareils Zigbee doivent y apparaître, regroupés par périphérique avec toutes leurs entités. Pour un capteur multi-fonctions (ex. Aqara, qui combine température, humidité et pression), on voit trois entités sous un même appareil.

Cliquer sur un appareil donne accès à :

• ses entités (capteurs, switches, boutons) ;
• ses diagnostics (LQI, batterie pour les appareils sur pile, dernière mise à jour) ;
• ses automatisations déclenchables.

Personnaliser les noms

Par défaut, le nom d’un appareil dans HA est celui que zigbee2mqtt lui donne. Si l’on a appairé un capteur sans le renommer, on tombe sur 0x00158d0001b2c3d4 — pas très parlant.

Deux endroits où renommer :

Côté zigbee2mqtt (recommandé) : via le frontend web (http://<ip-zigbee2mqtt>:8080), cliquer sur l’appareil, modifier son Friendly name. Ce nom devient le topic sur lequel zigbee2mqtt publie, et HA suit automatiquement.

Côté HA : Paramètres → Appareils & services → MQTT → Appareils → cliquer sur l’appareil → renommer. Le nom dans HA change mais le topic Zigbee, lui, reste inchangé. C’est pratique si l’on veut un nom différent dans HA sans casser des automatisations qui dépendraient du topic Zigbee.

L’usage est de renommer dans zigbee2mqtt avec un slug technique (temperature_salon, prise_bureau, bouton_chambre) et de mettre dans HA un nom convivial (« Température du salon », « Prise du bureau »).

Le même mécanisme pour la téléinfo

Le chapitre sur l’envoi de la téléinfo via MQTT (chapitre 25) déclare les capteurs en YAML manuel, dans configuration.yaml. C’était une bonne façon d’introduire la mécanique MQTT côté HA, et ça marche.

Mais maintenant qu’on connaît MQTT Discovery, on peut faire mieux : côté relais MQTT téléinfo, publier aussi les messages de découverte sur homeassistant/.... Une fois, à la première exécution du relais. Les capteurs apparaissent automatiquement dans HA sans toucher à configuration.yaml.

Exemple côté relais Python (à publier au démarrage, avant de relayer les trames) :

DISCOVERY_PREFIX = "homeassistant"
DEVICE_ID = "compteur_linky"
STATE_TOPIC = "maison/energie/compteur/tic"

discovery_config = {
    "PAPP": {
        "name": "Compteur Linky Puissance apparente",
        "unique_id": f"{DEVICE_ID}_papp",
        "state_topic": STATE_TOPIC,
        "value_template": "{{ value_json.PAPP }}",
        "unit_of_measurement": "VA",
        "device_class": "apparent_power",
        "device": {"identifiers": [DEVICE_ID], "name": "Compteur Linky"},
    },
    "HCHC": {
        "name": "Compteur Linky Index heures creuses",
        "unique_id": f"{DEVICE_ID}_hchc",
        "state_topic": STATE_TOPIC,
        "value_template": "{{ value_json.HCHC }}",
        "unit_of_measurement": "Wh",
        "device_class": "energy",
        "state_class": "total_increasing",
        "device": {"identifiers": [DEVICE_ID], "name": "Compteur Linky"},
    },
    # ... idem pour IINST, HCHP, etc.
}

for key, conf in discovery_config.items():
    topic = f"{DISCOVERY_PREFIX}/sensor/{DEVICE_ID}/{key}/config"
    client.publish(topic, json.dumps(conf), retain=True, qos=1)

Le retain=True est important : il dit au broker de conserver le message. Si HA redémarre, à sa reconnexion il recevra immédiatement les messages de découverte au lieu d’attendre une nouvelle publication du relais.

C’est plus de code dans le relais, mais zéro YAML côté HA. À choisir selon les goûts.

Dépannage

Suite

L’écosystème domotique est désormais fonctionnel de bout en bout : appareils Zigbee → zigbee2mqtt → Mosquitto → Home Assistant, avec tous les appareils visibles dans l’interface sans configuration manuelle.

Les chapitres suivants traitent des sujets pratiques qui surviennent ensuite : retours sur la version 2025.4 de HA, incidents rencontrés sur ma propre installation, et autres pièges qu’on découvre une fois la base en place.