Guide pratique · 8 min
Coordinateur Zigbee non détecté dans Home Assistant : méthode de diagnostic
Retrouver un coordinateur Zigbee absent de Home Assistant : alimentation, câble USB, chemin stable, conteneur Docker, accès concurrent et liaison réseau.
Partir d'un symptôme précis
Un coordinateur absent dans Home Assistant peut avoir plusieurs causes : alimentation insuffisante, câble USB réservé à la charge, port changé après un redémarrage, conteneur sans accès au périphérique ou radio déjà utilisée par un autre service. Commencez par noter ce que voit réellement le système, sans réinitialiser le réseau Zigbee.
Distinguez aussi un coordinateur USB d'un coordinateur Ethernet ou PoE. Le premier doit être visible comme périphérique local par le système qui exécute Home Assistant ; le second doit répondre sur le réseau local et être configuré avec le bon protocole d'accès.
Vérifier le matériel et le chemin stable
Contrôlez l'alimentation, le voyant éventuel et le câble avant de modifier l'intégration. Un autre port ou un câble de données connu permet d'isoler une panne physique sans toucher au réseau Zigbee existant.
Sous Linux, utilisez de préférence le chemin stable fourni dans /dev/serial/by-id plutôt qu'un nom tel que /dev/ttyUSB0. Ce dernier peut changer après un redémarrage ou lorsqu'un second adaptateur est ajouté. Conservez le chemin exact dans votre documentation locale, sans le publier.
Contrôler le passage vers Home Assistant ou Docker
Avec Home Assistant OS, l'assistant de configuration doit proposer le périphérique détecté. Avec Home Assistant Container ou Core, vérifiez que le périphérique hôte est explicitement transmis au conteneur et que l'utilisateur du service dispose des droits nécessaires.
Ne lancez pas ZHA et Zigbee2MQTT sur la même radio. Un seul service peut ouvrir le port série à la fois. Arrêtez proprement le service concurrent, contrôlez les journaux, puis relancez une seule pile Zigbee. Cette étape évite des erreurs de port qui ressemblent à une radio défaillante.
Diagnostiquer une liaison Ethernet ou PoE
Pour un coordinateur réseau, vérifiez d'abord le lien Ethernet, l'alimentation PoE éventuelle, l'adresse locale réservée et l'accès depuis le serveur Home Assistant. Une radio qui répond à son interface d'administration n'est pas encore forcément correctement exposée à ZHA ou Zigbee2MQTT.
Relevez le protocole demandé par l'intégration et testez une connexion locale avant d'ouvrir l'appairage. Évitez de faire passer le flux d'une radio Zigbee par Internet, VPN ou Wi-Fi instable : une liaison Ethernet locale réduit les variables lors du diagnostic.
Valider sans mettre le réseau en danger
Avant une réinitialisation, sauvegardez Home Assistant et les données du coordinateur lorsque l'intégration le permet. Si le réseau existant est critique, remettez temporairement l'ancien adaptateur plutôt que de tenter plusieurs configurations en parallèle.
Une fois le coordinateur reconnu, vérifiez l'état de l'intégration, un appareil alimenté et un appareil sur pile. Testez une commande simple et une remontée d'état, puis observez le réseau avant de modifier le canal, le firmware ou les paramètres radio.
Questions fréquentes
Pourquoi /dev/ttyUSB0 ne suffit-il pas toujours ?
Le numéro peut changer après un redémarrage ou avec un autre adaptateur. Un chemin /dev/serial/by-id identifie plus durablement le périphérique sur un système Linux.
Peut-on lancer ZHA et Zigbee2MQTT sur le même coordinateur ?
Non. Une radio série ne doit être ouverte que par un seul service à la fois. Choisissez une pile, arrêtez l'autre proprement, puis vérifiez les journaux avant tout autre changement.
Faut-il réinitialiser le coordinateur s'il n'est pas détecté ?
Non, pas en premier recours. Vérifiez d'abord alimentation, câble, chemin, droits du conteneur et accès concurrent. Une réinitialisation peut rendre une migration ou une restauration plus complexe.
