Il existe deux façons de faire parler du Zigbee à Home Assistant : ZHA, l’intégration maison, et Zigbee2MQTT, un projet externe qui passe par un broker MQTT. ZHA s’installe en trois clics. Zigbee2MQTT en demande vingt de plus.

Alors pourquoi s’embêter ? Pour une raison qui ne se voit pas le premier jour et qui compte énormément le trois-centième : la compatibilité matérielle. Zigbee2MQTT maintient une base de plusieurs milliers d’appareils, avec des correctifs spécifiques par modèle. Quand vous achetez un capteur chinois obscur, la probabilité qu’il soit correctement exposé est nettement plus élevée. Et le jour où il ne l’est pas, il existe un mécanisme de convertisseur externe qui vous permet de le décrire vous-même sans attendre une nouvelle version.

C’est le prix d’une brique de plus dans l’architecture. Voici comment la poser proprement.

Ce qu’il faut avoir avant de commencer

Un coordinateur Zigbee, évidemment — et c’est là que se joue l’essentiel de la fiabilité future. Si ce n’est pas encore fait, lisez d’abord le choix du coordinateur Zigbee : un dongle collé contre un boîtier métallique à côté d’un port USB 3.0 vous fera passer les six mois suivants à croire que Zigbee2MQTT est instable, alors que le problème est purement physique.

Une instance Home Assistant qui tourne, par exemple sur un mini-PC d’occasion.

Et un broker MQTT. C’est la différence de fond avec ZHA : Zigbee2MQTT ne parle pas directement à Home Assistant, il publie sur MQTT et Home Assistant écoute. Cette indirection est ce qui rend le système découplé — vous pouvez redémarrer Home Assistant sans perdre le réseau Zigbee, et brancher d’autres consommateurs (Node-RED, un script, un tableau de bord tiers) sur le même flux.

Étape 1 : le broker MQTT

Dans Home Assistant OS, le plus simple est le module complémentaire Mosquitto broker (Paramètres → Modules complémentaires → Boutique). Installez-le, démarrez-le, activez « Démarrer au démarrage » et « Watchdog ».

Créez ensuite un utilisateur dédié à Zigbee2MQTT. Beaucoup de tutoriels vous font réutiliser votre compte Home Assistant : évitez. Un utilisateur par service signifie qu’une rotation de mot de passe ne casse pas trois choses à la fois.

Paramètres → Personnes → Utilisateurs → Ajouter, par exemple mqtt-z2m, avec un mot de passe généré. Mosquitto, dans sa configuration par défaut, authentifie contre les comptes Home Assistant.

Home Assistant doit ensuite détecter le broker et vous proposer l’intégration MQTT. Acceptez-la.

Étape 2 : identifier le coordinateur de façon stable

C’est l’étape que tout le monde bâcle, et celle qui casse une installation trois mois plus tard.

Un coordinateur USB apparaît sous un nom du type /dev/ttyUSB0 ou /dev/ttyACM0. Ce nom dépend de l’ordre d’énumération USB au démarrage. Ajoutez un onduleur, un disque externe, une carte réseau — et ttyUSB0 devient ttyUSB1. Zigbee2MQTT ne démarre plus, sans message clair.

La parade est d’utiliser le chemin persistant, dérivé du numéro de série du périphérique. Dans un terminal :

ls -l /dev/serial/by-id/

Vous obtenez quelque chose comme :

usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0

C’est ce chemin complet qu’il faut utiliser dans la configuration, jamais /dev/ttyUSB0. Il reste identique quoi que vous branchiez d’autre.

Si vous utilisez un coordinateur Ethernet, le problème ne se pose pas : vous le désignez par son adresse IP — pensez alors à lui réserver un bail DHCP fixe sur votre routeur, ce qui est le même raisonnement transposé au réseau.

Étape 3 : installer et configurer Zigbee2MQTT

Ajoutez le dépôt de modules complémentaires de Zigbee2MQTT, puis installez le module Zigbee2MQTT.

Avant de le démarrer, ouvrez sa configuration. Les points qui comptent :

serial:
  port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0
mqtt:
  server: mqtt://core-mosquitto:1883
  user: mqtt-z2m
  password: votre-mot-de-passe
permit_join: false
advanced:
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE
homeassistant: true

Trois choix méritent une explication.

permit_join: false. L’appairage doit être ouvert ponctuellement, jamais en permanence. Un réseau Zigbee laissé ouvert accepte n’importe quel appareil à portée. Vous ouvrirez la fenêtre d’appairage depuis l’interface web, pour quelques minutes, au moment d’ajouter un appareil.

channel: 25. Zigbee et le Wi-Fi 2,4 GHz se partagent la même bande et se marchent dessus. Les canaux Zigbee 15, 20 et 25 sont ceux qui tombent dans les creux laissés par les canaux Wi-Fi 1, 6 et 11. Choisissez-en un maintenant : changer de canal après coup oblige à réappairer les appareils qui ne suivent pas, ce qui est exactement la corvée qu’on veut éviter. Si votre Wi-Fi est sur le canal 11, le 15 est souvent plus tranquille que le 25.

network_key: GENERATE. Génère une clé aléatoire au premier démarrage plutôt que d’utiliser une clé par défaut connue. Nous y revenons plus bas, c’est important.

Démarrez le module, puis ouvrez son interface web.

Étape 4 : le premier appairage

Dans l’interface Zigbee2MQTT, cliquez sur Permit join, en choisissant une durée courte. Mettez ensuite votre appareil en mode appairage — la manipulation varie : maintien du bouton cinq secondes, retrait puis remise de la pile, appui rapide cinq fois de suite. Le manuel du fabricant est votre ami.

L’appareil apparaît dans la liste, puis dans Home Assistant automatiquement grâce à homeassistant: true (découverte MQTT).

Renommez-le immédiatement. Par défaut il s’appelle 0x00158d0001a2b3c4, ce qui ne veut rien dire. Dans l’interface, donnez-lui un nom explicite du type salon_temperature. Ce nom devient le sujet MQTT et l’identifiant de l’entité : le changer plus tard casse vos automatisations. Prenez trente secondes maintenant, ou trente minutes dans six mois.

Un conseil d’ordre : appairez d’abord les appareils sur secteur (prises, ampoules, micro-modules). Ce sont eux qui font routeurs et étendent le maillage. Si vous commencez par les capteurs sur pile en bout de maison, ils tenteront de joindre directement le coordinateur, échoueront ou se rattacheront médiocrement, et il faudra les réappairer une fois le maillage en place.

Étape 5 : sauvegarder la clé réseau

Voilà la chose que personne ne fait et que tout le monde regrette.

Le réseau Zigbee est défini par une clé réseau et un PAN ID, stockés dans la configuration de Zigbee2MQTT et dans sa sauvegarde de coordinateur. Perdez ces informations et vous ne perdez pas « un réglage » : vous perdez le réseau. Chaque appareil devra être remis en appairage, un par un, y compris celui qui est vissé au plafond.

Récupérez la valeur de network_key et de pan_id une fois générés, et mettez-les à l’abri. Plus largement, la sauvegarde du dossier de configuration de Zigbee2MQTT doit faire partie de votre routine — c’est exactement le sujet de la règle 3-2-1 appliquée à Home Assistant.

Le corollaire réjouissant : avec cette sauvegarde, changer de coordinateur (matériel en panne, montée en gamme) devient une opération de quelques minutes. On restaure la clé sur le nouveau coordinateur, et les appareils ne voient pas la différence.

Les erreurs qui reviennent le plus souvent

« Le dongle n’est pas détecté. » Neuf fois sur dix, c’est un problème de chemin (ttyUSB0 au lieu du by-id) ou un port USB 3.0. Utilisez une rallonge USB 2.0 d’un mètre pour éloigner le dongle du boîtier : c’est le meilleur rapport efficacité/prix de tout le domaine.

« Les capteurs éloignés décrochent au bout de quelques heures. » Maillage insuffisant. Ajoutez un appareil sur secteur à mi-chemin. Le Zigbee n’a pas besoin de puissance, il a besoin de relais.

« Ça marchait, et depuis que j’ai bougé la box, plus rien. » Interférence Wi-Fi. Vérifiez le canal Wi-Fi de votre box et le canal Zigbee, et faites en sorte qu’ils ne se recouvrent pas.

Doublons d’entités après réappairage. Si vous supprimez un appareil, supprimez-le aussi côté Zigbee2MQTT, pas seulement côté Home Assistant.

Faut-il migrer si vous êtes déjà sous ZHA ?

Si tout fonctionne et que vos appareils sont correctement exposés, non. La migration implique de réappairer, ce qui n’est pas gratuit en temps.

Le déclencheur légitime, c’est un appareil mal ou pas supporté par ZHA — ou l’envie d’exploiter le flux MQTT ailleurs que dans Home Assistant. Dans ce cas, faites-la d’un coup plutôt que d’entretenir deux réseaux Zigbee en parallèle sur deux coordinateurs : deux réseaux qui se partagent la même bande de fréquence, c’est la garantie d’un débogage pénible.

Pour aller plus loin