Guia de solução de problemas de emparelhamento de dispositivos Home Assistant para ZHA, HomeKit, HACS e LinknLink
Adicionar um dispositivo ao Home Assistant deve parecer simples: descubra-o, emparelhe-o, nomeie-o e use-o em uma automação. Em casas reais, o emparelhamento pode falhar em muitas camadas. Um dispositivo pode ser descoberto, mas não expor nenhuma entidade útil. Um sensor Zigbee pode entrar na rede, mas ficar muito longe do roteador. Um dispositivo HomeKit ainda pode estar bloqueado para outro controlador. Uma integração HACS pode ser instalada corretamente, mas perder credenciais, acesso à rede ou reinicialização.
Este guia é um caminho prático de solução de problemas para emparelhamento de dispositivos Home Assistant em dispositivos ZHA, Zigbee2MQTT, HomeKit Controller, HACS, MQTT e LinknLink. Ele foi escrito para casas inteligentes locais usando HomeClaw, ZG-808Z, eMotion Air, eMotion Pro, eMotion Ultra, eRemote HAe eHome HA.
Comece identificando a camada de emparelhamento
A maioria dos problemas de emparelhamento do Home Assistant não são aleatórios. Eles geralmente pertencem a uma camada: transporte, descoberta, credenciais, mapeamento de entidades ou lógica de automação. Não reconstrua toda a configuração até saber qual camada está falhando.
| Camada | Sintoma típico | O que verificar primeiro | Melhor próxima ação |
|---|---|---|---|
| Transporte | O dispositivo nunca aparece | Potência, distância, segmento LAN, coordenador Zigbee, banda Wi-Fi. | Aproxime o dispositivo, confirme a acessibilidade da rede ou redefina o modo de emparelhamento. |
| Descoberta | O dispositivo aparece, mas não pode ser adicionado | Tipo de integração, modo de emparelhamento, propriedade do dispositivo, código HomeKit. | Remova do controlador antigo, reinicie a integração e tente novamente a partir de um estado de emparelhamento limpo. |
| Credenciais | Login ou token falha | IP local, corretor MQTT, configurações de integração HACS, permissões de usuário. | Insira novamente as credenciais e verifique se o Home Assistant pode alcançar o endpoint local. |
| Mapeamento de entidade | Dispositivo adicionado, mas faltam entidades | Recursos não suportados, entidades de diagnóstico desabilitadas, versão de integração. | Habilite entidades ocultas, atualize a integração ou escolha a plataforma correta. |
| Lógica de automação | A entidade funciona manualmente, mas a automação falha | Estado do gatilho, condição, modo, resfriamento, contexto da sala. | Use o rastreamento de automação e teste cada condição separadamente. |
Solução de problemas de emparelhamento ZHA
ZHA é o caminho Zigbee mais direto em Home Assistant. Funciona bem quando o coordenador está estável, o dispositivo está próximo o suficiente durante o emparelhamento e a malha possui bons roteadores. Se um dispositivo Zigbee emparelhar, mas ficar indisponível, o problema geralmente é a qualidade da malha e não o próprio dispositivo.
Pare perto do coordenador primeiro
Aproxime o dispositivo do coordenador para a primeira junção. Depois que estiver estável, mova-o para a sala final e deixe a malha assentar.
Verifique a sobreposição de canais
Wi-Fi 2,4 GHz e Zigbee podem interferir. Se o emparelhamento não for confiável, mantenha o coordenador longe do roteador e das portas USB 3.0.
Use um dispositivo roteador alimentado
Os sensores da bateria não roteiam. Adicione dispositivos Zigbee alimentados entre o coordenador e salas distantes para melhorar a confiabilidade da malha.
Para um caminho de coordenador dedicado, use ZG-808Z. Se você precisar de um fluxo de diagnóstico mais profundo do Zigbee, leia o Guia de solução de problemas Zigbee2MQTT ZG-808Z.
Solução de problemas de emparelhamento Zigbee2MQTT
Zigbee2MQTT oferece mais visibilidade sobre junções de dispositivos, rotas e suporte a conversores. É útil quando um dispositivo ingressa, mas expõe entidades inesperadas, ou quando você precisa inspecionar a qualidade do link e o status da entrevista.
| Problema | Onde procurar | Razão provável | Correção |
|---|---|---|---|
| Falha na entrevista | Interface Zigbee2MQTT | Sinal fraco, dispositivo não compatível, dispositivo saiu do modo de emparelhamento. | Emparelhe novamente perto do coordenador e mantenha o dispositivo ativo. |
| Nenhuma entidade Home Assistant | Descoberta MQTT | Descoberta desativada ou incompatibilidade de tópico. | Verifique o prefixo de descoberta MQTT e reinicie o Home Assistant após corrigir a configuração. |
| A entidade parece indisponível | Configurações de disponibilidade | Dispositivo de bateria sonolento ou problema de roteamento. | Aguarde o próximo relatório de bateria ou melhore as rotas de malha. |
| Tipo de dispositivo errado | Suporte ao conversor | A impressão digital do dispositivo é mapeada para suporte parcial. | Atualize Zigbee2MQTT e verifique as notas do conversor. |
Solução de problemas de emparelhamento do controlador HomeKit
O HomeKit Controller é poderoso porque muitos dispositivos HomeKit podem ser emparelhados localmente no Home Assistant. A falha mais comum é a propriedade: o dispositivo ainda pertence a outro app Home, ponte, conta ou controlador.
- Remova o dispositivo do controlador HomeKit anterior antes de emparelhá-lo com o Home Assistant.
- Mantenha o Home Assistant e o dispositivo na mesma rede local durante a configuração.
- Use o código de emparelhamento original do HomeKit e mantenha-o visível até que a configuração seja concluída.
- Desligue e ligue o acessório se ele aparecer na descoberta, mas o emparelhamento nunca for concluído.
Depois que o emparelhamento do HomeKit funcionar, conecte a entidade à lógica da sala de o guia do painel da sala do aplicativo LinknLink portanto, o dispositivo é mais fácil de controlar por ambiente.
Solução de problemas de integração HACS
HACS não é uma camada de emparelhamento de dispositivos por si só. Ele instala integrações personalizadas. O emparelhamento ainda depende da integração, credenciais, acesso LAN, token de nuvem ou ponte MQTT por trás dele. Trate primeiro os problemas do HACS como problemas de instalação, compatibilidade e reinicialização.
| Sintoma HACS | O que isso significa | Correção |
|---|---|---|
| Integração instalada, mas não visível | Home Assistant não recarregou o componente personalizado. | Reinicie o Home Assistant e limpe o cache do navegador. |
| O fluxo de configuração falha | As credenciais ou o endpoint da rede estão errados. | Confirme o IP local, token, região da conta e permissões necessárias. |
| Entidades desaparecem após atualização | Quebrando alterações ou entidades renomeadas. | Leia as notas de versão e atualize as automações por ID da entidade. |
| A automação funciona apenas manualmente | A entidade existe, mas as condições ou gatilhos estão errados. | Revise os rastreamentos de automação e teste primeiro com um gatilho simples. |
Verificações de descoberta MQTT para dispositivos LinknLink
Os problemas de emparelhamento do MQTT geralmente são mais fáceis de depurar do que as integrações na nuvem porque cada etapa é local e visível. Se um dispositivo LinknLink não aparecer corretamente, verifique a conexão do intermediário, o tópico de descoberta, as mensagens retidas e a categoria da entidade.
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
Para dispositivos de controle remoto, use o Guia de controle remoto Home Assistant. Para falhas de comando IR após o emparelhamento, use o Guia de solução de problemas do blaster IR.
Emparelhamento do sensor eMotion e verificações de entidades
Os sensores de presença podem criar vários tipos de entidades: ocupação, movimento, distância, iluminância, zonas, bateria, contexto de temperatura ou umidade dependendo do modelo. O emparelhamento só é bem sucedido quando as entidades úteis aparecem e são atualizadas de forma confiável.
| Produto | Foco de emparelhamento | Entidade a verificar | Melhor caso de uso |
|---|---|---|---|
| eMotion Air | Posicionamento alimentado por bateria e relatórios de presença local. | Presença, bateria, estado ambiente. | Salas flexíveis onde a fiação é difícil. |
| eMotion Pro | Presença mmWave mais controle de sala IR integrado. | Presença, iluminância, entidades de comando IR. | Salas que precisam de detecção e controle de aparelhos. |
| eMotion Ultra | Presença 60GHz, IR integrado e contexto de cabo de dados de temperatura/umidade. | Presença, zonas, IR, dados de conforto. | Salas de precisão, cenas de sono e lógica HVAC. |
Se você estiver escolhendo entre os três, leia o Guia de compra eMotion Air vs Pro vs Ultra.
Verificações de emparelhamento de dispositivos remotos e RF
Os dispositivos IR e RF podem ser confusos porque o controle remoto original pode parecer semelhante mesmo quando o protocolo é diferente. Um ventilador pode usar RF. Um TV geralmente usa IR. Uma cortina de rolo pode usar RF, Wi-Fi ou uma ponte proprietária. Emparelhe o caminho de controle com o protocolo antes de escrever automações.
- Usar eRemote HA para cenas IR locais.
- Usar eHome HA quando o controle RF faz parte da sala.
- Usar eMotion Pro ou eMotion Ultra quando a presença e o IR devem morar juntos.
Para comparação do hub RF, leia o Guia eHome HA vs Bond Bridge.
Use HomeClaw como camada de recuperação local
Quando um dispositivo está emparelhado, mas não é confiável, a camada de gateway é importante. HomeClaw pode manter a lógica Home Assistant local, coordenar painéis de sala e ajudar a organizar estados de dispositivos em automações que são mais fáceis de depurar.
Para estrutura de aplicativo e controle de sala, leia o Guia de automação do aplicativo LinknLink e o guia do painel da sala.
Tabela de decisão de solução de problemas de emparelhamento
| Se isso acontecer | Faça isso primeiro | Então use este caminho LinknLink |
|---|---|---|
| O sensor Zigbee entra, mas fica off-line | Aproxime-o, verifique os dispositivos do roteador, inspecione o LQI. | ZG-808Z mais o guia de solução de problemas Zigbee2MQTT. |
| Dispositivo HomeKit recusa emparelhamento | Remova-o do controlador antigo e redefina o emparelhamento. | Fluxo de trabalho Home Assistant local HomeClaw. |
| A entidade de presença existe, mas as automações falham | Verifique o rastreamento de automação e as alterações de estado da entidade. | eMotion Air, Pro ou Ultra com auxiliares de modo ambiente. |
| A entidade de comando IR/RF existe, mas o dispositivo não responde | Verifique o protocolo, posicionamento e comando aprendido. | eRemote HA para IR ou eHome HA para RF/IR. |
| A integração personalizada é instalada, mas não cria entidades | Reinicie o Home Assistant e inspecione os logs de fluxo de configuração. | Solução de problemas locais do HomeClaw mais guias canônicos. |
Guias relacionados e produtos importantes
Use esses links canônicos de produtos e artigos para continuar desde o emparelhamento até a automação local estável.
Produtos quentes
HomeClaw, ZG-808Z, eMotion Air, eMotion Pro, eMotion Ultra, eRemote HA, eHome HA.
Emparelhamento e integrações
Solução de problemas Zigbee2MQTT, Melhores integrações Home Assistant, Guia de gateway Raspberry Pi vs HomeClaw.
Presença e controles remotos
Melhores sensores de presença mmWave, Guia de controle remoto, Guia de solução de problemas do IR.
Corrija a camada de emparelhamento antes de reconstruir a automação
Automações Home Assistant confiáveis começam com entidades confiáveis. Confirme o transporte, a descoberta, as credenciais e o mapeamento de entidades antes de adicionar cenas, painéis de sala ou conversas do Agent+.
Perguntas frequentes
Por que o Home Assistant descobre um dispositivo, mas não cria as entidades corretas?
A descoberta e a criação de entidade são etapas separadas. Verifique o tipo de integração, as permissões do dispositivo, o tópico MQTT, a integridade do coordenador e se a integração expõe o recurso como um sensor, comutador, botão, entidade climática ou entidade de diagnóstico.
Devo emparelhar dispositivos Zigbee por meio de ZHA ou Zigbee2MQTT?
Use ZHA quando desejar uma configuração Home Assistant nativa mais simples. Use Zigbee2MQTT quando precisar de suporte mais amplo ao dispositivo, mais diagnósticos e controle preciso sobre o roteamento Zigbee por meio de um coordenador como o ZG-808Z.
Os dispositivos HomeKit podem ser adicionados ao Home Assistant localmente?
Sim. Muitos dispositivos HomeKit podem ser adicionados por meio da integração do HomeKit Controller. Mantenha o dispositivo na mesma rede local, remova-o do controlador anterior, se necessário, e use o código de emparelhamento durante a configuração.
O que devo verificar quando os dispositivos LinknLink não aparecem no Home Assistant?
Confirme se o dispositivo está on-line, se o acesso à rede local está disponível, se o MQTT ou as credenciais de integração estão corretas e se a instância Home Assistant pode alcançar o mesmo segmento de LAN que o dispositivo LinknLink.
Quais produtos LinknLink ajudam no emparelhamento Home Assistant e no controle local?
Use HomeClaw como gateway Home Assistant local, ZG-808Z para coordenação Zigbee, sensores eMotion para automação de presença, eRemote HA para controle IR local e eHome HA para fluxos de trabalho remotos RF e IR.