Guide de dépannage du couplage des appareils Home Assistant pour ZHA, HomeKit, HACS et LinknLink
Ajouter un appareil au Home Assistant devrait être simple : découvrez-le, associez-le, nommez-le et utilisez-le dans une automatisation. Dans les vraies maisons, le couplage peut échouer à plusieurs niveaux. Un périphérique peut être découvert mais n'exposer aucune entité utile. Un capteur Zigbee peut rejoindre le réseau mais être trop éloigné du routeur. Un appareil HomeKit peut toujours être verrouillé sur un autre contrôleur. Une intégration HACS peut s'installer correctement mais manquer d'informations d'identification, d'accès au réseau ou de redémarrage.
Ce guide est un chemin de dépannage pratique pour le couplage des appareils Home Assistant entre les appareils ZHA, Zigbee2MQTT, HomeKit Controller, HACS, MQTT et LinknLink. Il est écrit pour les maisons intelligentes locales utilisant HomeClaw, ZG-808Z, eMotion Air, eMotion Pro, eMotion Ultra, eRemote HA, et eHome HA.
Commencez par identifier la couche d'appariement
La plupart des problèmes de couplage du Home Assistant ne sont pas aléatoires. Ils appartiennent généralement à une seule couche : transport, découverte, informations d'identification, mappage d'entités ou logique d'automatisation. Ne reconstruisez pas l'intégralité de la configuration tant que vous ne savez pas quelle couche est défaillante.
| Calque | Symptôme typique | Que vérifier en premier | Meilleure prochaine action |
|---|---|---|---|
| Transports | L'appareil n'apparaît jamais | Puissance, distance, segment LAN, coordinateur Zigbee, bande Wi-Fi. | Rapprochez l'appareil, confirmez l'accessibilité du réseau ou réinitialisez le mode de couplage. |
| Découverte | L'appareil apparaît mais ne peut pas être ajouté | Type d'intégration, mode d'appairage, propriété de l'appareil, code HomeKit. | Supprimez de l'ancien contrôleur, redémarrez l'intégration et réessayez à partir d'un état d'appairage propre. |
| Informations d'identification | La connexion ou le jeton échoue | IP locale, courtier MQTT, paramètres d'intégration HACS, autorisations utilisateur. | Saisissez à nouveau les informations d'identification et vérifiez que Home Assistant peut atteindre le point de terminaison local. |
| Mappage d'entité | L'appareil s'ajoute mais les entités sont manquantes | Fonctionnalités non prises en charge, entités de diagnostic désactivées, version d'intégration. | Activez les entités masquées, mettez à jour l'intégration ou choisissez la bonne plateforme. |
| Logique d'automatisation | L'entité fonctionne manuellement mais l'automatisation échoue | État de déclenchement, condition, mode, temps de recharge, contexte de la pièce. | Utilisez la trace d’automatisation et testez chaque condition séparément. |
Dépannage du couplage ZHA
ZHA est le chemin Zigbee le plus direct dans Home Assistant. Cela fonctionne bien lorsque le coordinateur est stable, que l'appareil est suffisamment proche lors de l'appairage et que le maillage dispose de bons routeurs. Si un appareil Zigbee s'associe mais devient indisponible, le problème est souvent la qualité du maillage plutôt que l'appareil lui-même.
Associez-vous d'abord près du coordinateur
Apportez l'appareil près du coordinateur pour la première connexion. Une fois qu'il est stable, déplacez-le vers la pièce finale et laissez le treillis se déposer.
Vérifier le chevauchement des canaux
Wi-Fi 2,4 GHz et Zigbee peuvent interférer. Si le couplage n'est pas fiable, éloignez le coordinateur du routeur et des ports USB 3.0.
Utilisez un routeur alimenté
Les capteurs de batterie ne fonctionnent pas. Ajoutez des appareils Zigbee alimentés entre le coordinateur et les pièces distantes pour améliorer la fiabilité du maillage.
Pour un chemin de coordinateur dédié, utilisez ZG-808Z. Si vous avez besoin d'un flux de diagnostic Zigbee plus approfondi, lisez le Guide de dépannage du Zigbee2MQTT ZG-808Z.
Dépannage du couplage Zigbee2MQTT
Zigbee2MQTT offre plus de visibilité sur les jointures de périphériques, les itinéraires et la prise en charge des convertisseurs. C'est utile lorsqu'un appareil rejoint mais expose des entités inattendues, ou lorsque vous devez inspecter la qualité du lien et l'état de l'interview.
| Problème | Où chercher | Raison probable | Corriger |
|---|---|---|---|
| L'entretien a échoué | Interface Zigbee2MQTT | Signal faible, appareil non pris en charge, appareil quitté le mode d'appairage. | Reconnectez-vous à proximité du coordinateur et gardez l'appareil éveillé. |
| Aucune entité Home Assistant | Découverte du MQTT | Découverte désactivée ou non-concordance de sujet. | Vérifiez le préfixe de découverte MQTT et redémarrez Home Assistant après avoir corrigé la configuration. |
| L'entité semble indisponible | Paramètres de disponibilité | Batterie en veille ou problème de routage. | Attendez le prochain rapport de batterie ou améliorez les itinéraires de maillage. |
| Mauvais type d'appareil | Prise en charge du convertisseur | L’empreinte digitale de l’appareil correspond à une prise en charge partielle. | Mettez à jour Zigbee2MQTT et vérifiez les notes du convertisseur. |
Dépannage du couplage du contrôleur HomeKit
Le contrôleur HomeKit est puissant car de nombreux appareils HomeKit peuvent être couplés localement au Home Assistant. L'échec le plus courant est celui de la propriété : l'appareil appartient toujours à une autre application Home, un autre pont, un compte ou un contrôleur.
- Retirez l'appareil du contrôleur HomeKit précédent avant de le coupler au Home Assistant.
- Gardez le Home Assistant et l'appareil sur le même réseau local pendant la configuration.
- Utilisez le code de couplage HomeKit d'origine et gardez-le visible jusqu'à ce que la configuration soit terminée.
- Redémarrez l'accessoire s'il apparaît dans la découverte mais que l'appairage ne se termine jamais.
Une fois le couplage HomeKit fonctionnel, connectez l'entité à la logique de la pièce à partir de le guide du tableau de bord de la salle d'application LinknLink l'appareil est donc plus facile à contrôler par pièce.
Dépannage de l'intégration HACS
Le HACS n'est pas une couche de couplage d'appareils en soi. Il installe des intégrations personnalisées. Le couplage dépend toujours de l'intégration, des informations d'identification, de l'accès au réseau local, du jeton cloud ou du pont MQTT derrière celui-ci. Traitez d'abord les problèmes du HACS comme des problèmes d'installation, de compatibilité et de redémarrage.
| Symptôme HACS | Ce que cela signifie | Corriger |
|---|---|---|
| Intégration installée mais non visible | Home Assistant n'a pas rechargé le composant personnalisé. | Redémarrez Home Assistant et videz le cache du navigateur. |
| Le flux de configuration échoue | Les informations d'identification ou le point de terminaison du réseau sont erronés. | Confirmez l'adresse IP locale, le jeton, la région du compte et les autorisations requises. |
| Les entités disparaissent après la mise à jour | Changement cassant ou entités renommées. | Lisez les notes de version et mettez à jour les automatisations par ID d'entité. |
| L'automatisation fonctionne uniquement manuellement | L'entité existe, mais les conditions ou les déclencheurs sont erronés. | Examinez les traces d’automatisation et testez d’abord avec un simple déclencheur. |
Vérifications de découverte MQTT pour les appareils LinknLink
Les problèmes de couplage MQTT sont généralement plus faciles à déboguer que les intégrations cloud, car chaque étape est locale et visible. Si un appareil LinknLink n'apparaît pas correctement, vérifiez la connexion du courtier, le sujet de découverte, les messages conservés et la catégorie d'entité.
MQTT checklist: - Confirm the LinknLink device is online - Confirm Home Assistant can reach the MQTT broker - Confirm username, password and port - Confirm discovery is enabled - Confirm the topic prefix matches Home Assistant - Restart Home Assistant only after fixing broker settings - Test one simple entity before rebuilding scenes
Pour les appareils télécommandés, utilisez le Guide de la télécommande Home Assistant. Pour les échecs de commande IR après l'appairage, utilisez le Guide de dépannage du blaster IR.
Couplage du capteur de mouvement et vérifications d'entité
Les capteurs de présence peuvent créer plusieurs types d'entités : présence, mouvement, distance, éclairement, zones, batterie, contexte de température ou d'humidité selon le modèle. Le couplage ne réussit que lorsque les entités utiles apparaissent et se mettent à jour de manière fiable.
| Produit | Focus sur le jumelage | Entité à vérifier | Meilleur cas d'utilisation |
|---|---|---|---|
| eMotion Air | Placement alimenté par batterie et rapports de présence locale. | Présence, batterie, état de la pièce. | Pièces flexibles où le câblage est difficile. |
| eMotion Pro | Présence mmWave et contrôle de pièce IR intégré. | Présence, éclairement, entités de commande IR. | Pièces nécessitant à la fois une détection et un contrôle des appareils. |
| eMotion Ultra | Présence du 60GHz, IR intégré et contexte du câble de données température/humidité. | Présence, zones, IR, données de confort. | Salles de précision, scènes de sommeil et logique HVAC. |
Si vous choisissez parmi les trois, lisez le Guide d'achat eMotion Air vs Pro vs Ultra.
Vérifications du couplage des appareils à distance et RF
Les appareils IR et RF peuvent prêter à confusion car la télécommande d'origine peut se ressembler même lorsque le protocole est différent. Un ventilateur peut utiliser RF. Un TV utilise généralement le IR. Un store à rouleau peut utiliser RF, Wi-Fi ou un pont exclusif. Associez le chemin de contrôle au protocole avant d’écrire des automatisations.
- Utiliser eRemote HA pour les scènes IR locales.
- Utiliser eHome HA lorsque la commande RF fait partie de la pièce.
- Utiliser eMotion Pro ou eMotion Ultra quand présence et IR doivent vivre ensemble.
Pour la comparaison du hub RF, lisez le Guide eHome HA contre Bond Bridge.
Utilisez HomeClaw comme couche de récupération locale
Lorsqu'un appareil est couplé mais peu fiable, la couche passerelle est importante. HomeClaw peut conserver la logique Home Assistant locale, coordonner les tableaux de bord des salles et aider à organiser les états des appareils en automatisations plus faciles à déboguer.
Pour la structure de contrôle de l'application et de la salle, lisez le Guide d'automatisation de l'application LinknLink et le guide du tableau de bord de la pièce.
Tableau de décision de dépannage de couplage
| Si cela arrive | Fais ça d'abord | Utilisez ensuite ce chemin LinknLink |
|---|---|---|
| Le capteur Zigbee rejoint mais se déconnecte | Rapprochez-le, vérifiez les périphériques du routeur, inspectez LQI. | ZG-808Z plus le guide de dépannage Zigbee2MQTT. |
| L'appareil HomeKit refuse le couplage | Retirez-le de l'ancien contrôleur et réinitialisez l'appairage. | Flux de travail HomeClaw local Home Assistant. |
| L'entité de présence existe mais les automatisations échouent | Vérifiez la trace d’automatisation et les changements d’état de l’entité. | eMotion Air, Pro ou Ultra avec assistants en mode salle. |
| L'entité de commande IR/RF existe mais l'appliance ne répond pas | Vérifiez le protocole, le placement et la commande apprise. | eRemote HA pour IR ou eHome HA pour RF/IR. |
| L'intégration personnalisée s'installe mais ne crée pas d'entités | Redémarrez Home Assistant et inspectez les journaux de flux de configuration. | Dépannage local HomeClaw et guides canoniques. |
Guides connexes et produits phares
Utilisez ces liens canoniques vers des produits et des articles pour passer du couplage à une automatisation locale stable.
Produits chauds
HomeClaw, ZG-808Z, eMotion Air, eMotion Pro, eMotion Ultra, eRemote HA, eHome HA.
Couplage et intégrations
Dépannage du Zigbee2MQTT, Meilleures intégrations Home Assistant, Guide de la passerelle Raspberry Pi vs HomeClaw.
Présence et télécommandes
Meilleurs capteurs de présence mmWave, Guide de la télécommande, Guide de dépannage du IR.
Corrigez la couche d'appariement avant de reconstruire l'automatisation
Des automatisations Home Assistant fiables commencent par des entités fiables. Confirmez le transport, la découverte, les informations d'identification et le mappage des entités avant d'ajouter des scènes, des tableaux de bord de salle ou des conversations Agent+.
FAQ
Pourquoi Home Assistant découvre-t-il un appareil mais ne crée-t-il pas les bonnes entités ?
La découverte et la création d'entités sont des étapes distinctes. Vérifiez le type d'intégration, les autorisations de l'appareil, la rubrique MQTT, l'état du coordinateur et si l'intégration expose la fonctionnalité en tant que capteur, commutateur, bouton, entité climatique ou entité de diagnostic.
Dois-je coupler des appareils Zigbee via ZHA ou Zigbee2MQTT ?
Utilisez ZHA lorsque vous souhaitez une configuration Home Assistant native plus simple. Utilisez le Zigbee2MQTT lorsque vous avez besoin d'une prise en charge plus large des appareils, de davantage de diagnostics et d'un contrôle précis du routage Zigbee via un coordinateur tel que le ZG-808Z.
Les appareils HomeKit peuvent-ils être ajoutés localement au Home Assistant ?
Oui. De nombreux appareils HomeKit peuvent être ajoutés via l’intégration du contrôleur HomeKit. Conservez l'appareil sur le même réseau local, supprimez-le du contrôleur précédent si nécessaire et utilisez le code d'appairage lors de la configuration.
Que dois-je vérifier lorsque les appareils LinknLink n'apparaissent pas dans Home Assistant ?
Vérifiez que l'appareil est en ligne, que l'accès au réseau local est disponible, que les informations d'identification MQTT ou d'intégration sont correctes et que l'instance Home Assistant peut atteindre le même segment LAN que l'appareil LinknLink.
Quels produits LinknLink facilitent le couplage et le contrôle local du Home Assistant ?
Utilisez le HomeClaw comme passerelle Home Assistant locale, le ZG-808Z pour la coordination Zigbee, les capteurs eMotion pour l'automatisation de présence, le eRemote HA pour le contrôle local IR et le eHome HA pour les flux de travail à distance RF et IR.