Integração e API
MQTT Discovery
MQTT Discovery pertence à família de convenções de autodiscovery sobre broker e resolve o cadastro manual de entidades. No Home Assistant, um componente publica configuração em tópicos como homeassistant/sensor/<object_id>/config, normalmente com payload JSON e mensagem retida; estados seguem em tópicos separados. Zigbee2MQTT e dispositivos compatíveis usam o mecanismo. A limitação é que não faz parte do padrão MQTT: formato, campos, disponibilidade e ciclo de vida pertencem à plataforma consumidora e podem mudar por versão.
🔀 Tipos de Comunicação
Config
Tópico de configuração
A entidade é anunciada num tópico com prefixo, componente, identificador e sufixo config. Um exemplo é homeassistant/sensor/estacao/temperatura/config. O prefixo pode ser alterado no Home Assistant, então produtor e consumidor precisam coincidir. O payload descreve name, unique_id, state_topic, device_class, unit_of_measurement, value_template, availability e metadados do device. A mensagem costuma ser retained para que o broker a entregue após reinício. O tópico precisa ser estável. Alterar object_id pode criar entidade nova e deixar antiga. unique_id é a identidade persistente e não deve depender de IP ou nome amigável. O produtor precisa publicar tombstone — payload vazio retido — para remover configuração. Não basta parar de publicar estado.
State/Command
Estado e comando em tópicos separados
Discovery descreve onde a entidade lê e escreve. Um sensor usa state_topic. Um switch usa state_topic e command_topic. A separação permite que a configuração seja rara e o estado frequente. O payload pode ser texto simples, JSON ou binário, mas templates precisam extrair. Para luz, campos de brilho, cor e efeitos usam tópicos ou JSON conforme configuração. O dispositivo deve publicar estado confirmado depois do comando. Não assumir que enviar ON significa que o relé mudou. Em bridges, o state pode vir do protocolo físico. Retained state ajuda restauração, mas pode representar dado antigo; availability e timestamp mitigam. Comandos não devem ser retained sem análise, pois um dispositivo que reconecta pode executar um comando antigo.
Availability
Disponibilidade e Last Will
availability_topic informa online/offline. Um cliente MQTT pode configurar Last Will como offline e publicar online ao conectar. O discovery pode declarar um ou vários tópicos e modos all, any ou latest, conforme o componente e a versão. A disponibilidade precisa representar o caminho real. Se Zigbee2MQTT está online, um sensor a bateria ainda pode estar indisponível. Há disponibilidade da bridge e do dispositivo. Heartbeat e timeout são necessários. Não marque offline um botão que só transmite quando pressionado. O Home Assistant apresenta unavailable e bloqueia comandos. O LWT pode atrasar conforme keepalive. Sessões e broker influenciam. A automação deve tratar unknown, não convertê-lo em off.
Device
Dispositivo e agrupamento de entidades
O bloco device associa várias entidades ao mesmo equipamento e inclui identifiers, connections, manufacturer, model, serial_number, sw_version, hw_version e via_device. Isso organiza UI e relações. Identifiers precisam ser globais dentro da integração, como MAC normalizado ou ID do protocolo, sem expor segredo. Uma bridge pode ser via_device. O mesmo device anunciado por dois clientes com identificadores diferentes aparece duplicado. A configuração deve ser consistente. Nomes amigáveis podem mudar sem alterar unique_id. Em dispositivos compostos, cada canal possui entidade, mas todos compartilham device. O agrupamento não cria segurança; é metadado. A remoção precisa limpar todas as configs.
Optimization
Abbreviations, shared device config e origem
Para reduzir payload, Home Assistant aceita abreviações de chaves em vários campos e mecanismos recentes para dados compartilhados. Isso é útil em microcontroladores e grandes bridges, mas reduz legibilidade. O produtor precisa seguir a documentação da versão. origin identifica software e versão que criou a configuração, melhorando diagnóstico. Payloads retidos de milhares de entidades ocupam memória do broker, embora geralmente sejam pequenos. O projeto pode usar retain e compressão de rede não é parte do MQTT básico. Não invente abreviações. Em atualizações, publique a configuração completa quando necessário. O consumidor não mescla arbitrariamente payloads antigos.
✅ Vantagens Arquiteturais
⚡
Elimina cadastro manual de dezenas ou milhares de entidades
Uma bridge como Zigbee2MQTT pode anunciar automaticamente sensores, luzes, baterias, diagnósticos e controles. O usuário não escreve YAML. Isso reduz erro de tópico e template. A entidade aparece com device_class e unidade corretas. O benefício depende da qualidade do anúncio. unique_id instável cria duplicatas. Nomes traduzidos podem mudar, mas IDs não. O produtor precisa ter testes de componentes suportados. O discovery não substitui um registro de dispositivos completo; apenas instrui o consumidor. A automação deve usar entity_id estável, mas este pode ser renomeado pelo usuário. Integrações internas podem usar unique_id.
⚡
Preserva metadados e experiência nativa da plataforma
Device class define semântica de temperatura, umidade, energia, porta e bateria. State class permite estatísticas de measurement, total ou total_increasing. Units e icon melhoram. Entidades podem declarar entity_category diagnostic ou config. Isso faz a integração parecer nativa. Configurar errado causa consequências: energy em W em vez de kWh quebra dashboard; total_increasing com reset não tratado gera estatísticas. O produtor precisa seguir regras. O discovery permite exposição rica, mas a plataforma ainda valida. Metadados não corrigem sensor sem calibração.
⚡
Desacopla o fabricante da API interna do controlador
O dispositivo só precisa falar MQTT e convenção de discovery, sem implementar API Python do Home Assistant. Isso é adequado a firmware, gateways e scripts. O broker fornece transporte. Em comparação com integração customizada, o custo de desenvolvimento é menor. A limitação é menor capacidade para fluxos complexos, config flows, reparos e serviços específicos. Tudo precisa caber em entidades e tópicos. Para câmera, atualização ou pairing, uma integração nativa pode ser melhor. O critério é a semântica. Discovery é ótimo para estados e comandos comuns.
⚡
Facilita operação offline e reconstrução após reinício
Configurações retidas são reapresentadas quando Home Assistant reconecta. O controlador recria entidades sem consultar cada dispositivo. Isso ajuda after restart. O broker se torna infraestrutura crítica. Retained messages precisam de persistência no disco. Backup do broker e da configuração é necessário. Se o produtor publica configuração errada e retida, o erro persiste. Tombstones removem. Um broker restaurado de backup pode ressuscitar entidades antigas. A manutenção deve listar retained topics e permitir limpeza seletiva. Não apagar todos sem plano.
⚡
Permite evolução incremental de firmware e bridges
O produtor pode adicionar entidades e campos novos. O Home Assistant atualiza. Compatibilidade depende da versão mínima. Campos desconhecidos podem ser ignorados ou gerar erro. A bridge deve declarar versão e manter fallback. Atualizar todos os payloads retidos pode gerar carga, mas ocorre raramente. A migração de tópico requer anunciar novo e remover antigo. Um esquema interno de versão ajuda. O discovery não possui negociação formal entre produtor e consumidor. A documentação e testes com versões suportadas são necessários. Para instalações que atualizam lentamente, preserve recursos antigos.