Descoberta MQTT do Home Assistant para um Medidor de Energia
Descoberta MQTT do Home Assistant para um Medidor de Energia
A Descoberta MQTT do Home Assistant permite que um medidor de energia crie seus dispositivos e entidades de sensor automaticamente. Após o medidor e o Home Assistant se conectarem ao mesmo broker MQTT, o Home Assistant pode descobrir o medidor sem a necessidade de YAML manual para sensores MQTT.
A IAMMETER suporta a Descoberta MQTT em todos os medidores de energia atuais. Dependendo do modelo, o Home Assistant cria entidades para tensão, corrente, potência ativa, energia importada, energia exportada e outras medições disponíveis de fase ou canal.
Use este método quando você desejar:
- monitoramento local de energia via MQTT;
- criação automática de dispositivos e entidades;
- atualizações mais rápidas que as integrações HTTP;
- entidades de energia importada/exportada compatíveis com o Painel de Energia;
- configuração mínima do Home Assistant.
Se você precisar de controle total sobre tópicos, modelos, nomes de entidades e metadados, use o guia de medidor de energia MQTT Manual em vez deste.
Descoberta MQTT versus MQTT Manual
Ambos os métodos exigem um broker MQTT, mas apenas a Descoberta cria automaticamente entidades no Home Assistant.
| Feature | MQTT Discovery | Manual MQTT |
|---|---|---|
| Configurar broker na WebUI do medidor | Sim | Sim |
| Ativar integração MQTT no HA | Sim | Sim |
| Escrever YAML de sensor | Não | Sim |
| Dispositivo/entidades criados automaticamente | Sim | Não |
| Modelos de valor personalizados | Não | Sim |
| Utilizador controla cada definição de entidade | Limitado | Sim |
| Metadados do Painel de Energia | Enviados automaticamente | Adicionados pelo utilizador no YAML |
Não ative a Descoberta e defina manualmente as mesmas medições, a menos que você queira deliberadamente dois conjuntos separados de entidades.
Requisitos
Você precisa de:
- um medidor de energia IAMMETER com firmware
i.76.058.8ou superior; - um broker MQTT acessível pelo medidor e pelo Home Assistant;
- o endereço, porta, nome de utilizador e senha do broker;
- Home Assistant com a Integração MQTT ativada.
O firmware i.76.058.8 é a versão estável de base para a Descoberta MQTT. A versão anterior i.76.02 era um firmware de teste e não deve mais ser instalada ou referenciada como a versão recomendada.
Para correções atuais e as opções MQTT mais recentes, atualize para o firmware IAMMETER mais recente.
Passo 1: Conectar o Home Assistant ao broker MQTT
Se o Home Assistant ainda não estiver conectado ao broker:
- Abra Settings → Devices & services.
- Selecione Add integration.
- Pesquise por MQTT.
- Insira o endereço, porta, nome de utilizador e senha do broker.
- Confirme que a Integração MQTT conecta com sucesso.
Se o Home Assistant já utiliza o broker pretendido, mantenha a Integração MQTT existente. Não crie uma segunda conexão de broker para o dispositivo IAMMETER.
A Descoberta MQTT está ativada por padrão numa configuração MQTT normal do Home Assistant. Se a descoberta foi desativada ou um prefixo de descoberta não padrão for usado, certifique-se de que o medidor e o Home Assistant utilizam configurações compatíveis.
Passo 2: Configurar a Descoberta MQTT na WebUI do medidor
Abra a WebUI local do medidor e vá para Settings. Configure:
| Setting | Value |
|---|---|
| Run Mode | MQTT |
| Address | Nome do host/endereço IP e porta do broker MQTT |
| Username | Nome de utilizador do broker, se necessário |
| Password | Senha do broker, se necessário |
| HA MQTT Discovery | Enabled |
Salve as configurações e permita que o medidor reinicie ou reconecte.
O firmware mais recente expõe as configurações necessárias na WebUI. Não é necessário chamar o endpoint histórico /api/mqttha?x=1.
A opção HA MQTT Discovery é especificamente para a descoberta automática do Home Assistant. Para um broker genérico, sistema personalizado, fluxo Node-RED ou configuração MQTT Manual, deixe-a desativada e utilize o formato de publicação MQTT padrão do medidor.
Passo 3: Confirmar que o Home Assistant descobre o medidor
Após o medidor conectar-se ao broker:
- Abra Settings → Devices & services → MQTT.
- Procure por um dispositivo IAMMETER recém-descoberto.
- Abra o dispositivo e revise as entidades.
- Confirme que os valores de tensão, corrente, potência e energia são plausíveis.
- Verifique se o número esperado de fases ou canais de medição está presente.
A configuração de descoberta e o estado das medições são enviados através de diferentes tópicos MQTT. O Home Assistant utiliza a configuração de descoberta para criar as entidades e, em seguida, atualiza seus valores quando as mensagens de estado chegam.
Se o dispositivo não aparecer, reinicie apenas após verificar a conexão e os tópicos do broker. Uma reinicialização do Home Assistant não pode corrigir um endereço de broker incorreto ou credenciais MQTT rejeitadas.
Suporte ao Painel de Energia
Os payloads atuais de Descoberta MQTT da IAMMETER incluem os metadados necessários para as entidades de energia importada e exportada:
unit_of_measurement: kWh
device_class: energy
state_class: total_increasing
A IAMMETER utiliza as chaves compactas de Descoberta MQTT correspondentes a estes campos, incluindo:
{
"unit_of_meas": "kWh",
"dev_cla": "energy",
"stat_cla": "total_increasing"
}
Após as entidades receberem dados válidos:
- vá para Settings → Dashboards → Energy;
- selecione a entidade de energia importada para o consumo da rede;
- selecione a entidade de energia exportada para o retorno à rede;
- salve a configuração do Painel de Energia.
Não selecione uma entidade de potência ativa instantânea em watts para um campo de energia. O Painel de Energia exige kWh acumulados.
Modelos monofásicos e trifásicos criam diferentes entidades de energia. Escolha as entidades que correspondem à fiação do medidor e à forma como a instalação mede a importação/exportação da rede.
Escolher um intervalo de atualização MQTT
O firmware IAMMETER mais recente suporta atualizações MQTT a partir de 2 segundos. Um intervalo mais curto fornece leituras de potência mais recentes ao Home Assistant, mas também gera mais tráfego no broker, atualizações de entidades e dados no gravador.
Pontos de partida sugeridos:
| Application | Suggested interval |
|---|---|
| Automação local rápida | 2–5 segundos |
| Painel de potência ao vivo | 5–12 segundos |
| Monitoramento geral de energia | 10–60 segundos |
Utilize o intervalo mais curto apenas quando a automação se beneficiar dele. Os totais do Painel de Energia geralmente não exigem atualizações de dois segundos.
Compatibilidade com a IAMMETER Cloud
A Descoberta MQTT altera o Modo de Execução do medidor para MQTT. O medidor envia suas medições para o broker configurado e não as envia simultaneamente para a IAMMETER Cloud.
Se você precisar tanto do Home Assistant quanto da IAMMETER Cloud a partir do mesmo medidor, escolha uma integração HTTP local ou Modbus TCP. Esses métodos leem o medidor localmente enquanto o envio normal para a Cloud continua.
Compare as opções na visão geral de integração de medidor de energia com Home Assistant.
Modelos IAMMETER suportados
Todos os medidores de energia IAMMETER atuais suportam a Descoberta MQTT. A principal diferença é o número de fases/canais e, portanto, o número de entidades criadas.
| Model | Typical entity structure | Product information |
|---|---|---|
| WEM3080 | Entidades monofásicas | Medidor de energia monofásico |
| WEM2067 | Dois canais de medição | Medidor de dois canais para energia solar residencial |
| WEM3080T | Entidades trifásicas | Medidor de energia trifásico |
| WEM3050T | Três canais de medição | Medidor trifásico/bifásico residencial |
| WEM3080TD | Entidades interpretadas conforme modo de fiação | WEM3080TD |
| WEM3046T / WEM3046TE | Entidades trifásicas com medição externa de TC 5 A | Medidor trifásico com TC 5 A |
O WEM3046T e o WEM3046TE medem a saída secundária de 5 A de transformadores de corrente externos. A relação de TC correta deve ser aplicada para obter corrente, potência e energia do lado primário. Este é um requisito do sistema de medição, não uma limitação do Home Assistant ou da Descoberta MQTT.
O descontinuado WEM3162 não está incluído no escopo de compatibilidade atual.
Resolução de problemas da Descoberta MQTT
O Home Assistant não descobre o medidor
- Confirme que o medidor e o Home Assistant utilizam o mesmo broker.
- Verifique o endereço, porta, nome de utilizador e senha do broker.
- Confirme que a opção HA MQTT Discovery está ativada na WebUI do medidor.
- Verifique os logs do broker para conexões rejeitadas ou erros de autorização.
- Verifique se a Integração MQTT do Home Assistant está conectada.
- Inscreva-se no prefixo de descoberta do Home Assistant no broker com um cliente MQTT e verifique se as mensagens de configuração estão presentes.
O dispositivo aparece, mas as entidades estão indisponíveis
- Confirme que o medidor continua publicando mensagens de estado após a configuração de descoberta.
- Verifique se um firewall, VLAN ou ACL do broker permite tanto os tópicos de descoberta quanto os de estado.
- Verifique se o medidor não mudou para um broker diferente.
- Atualize para o firmware mais recente e reconecte.
A energia importada/exportada não pode ser selecionada no Painel de Energia
- Confirme que a entidade recebeu um valor numérico válido em kWh.
- Abra Developer tools → States e inspecione sua unidade, classe de dispositivo e classe de estado.
- Remova entidades obsoletas criadas por firmwares de teste anteriores antes de avaliar o payload de descoberta atual.
- Confirme que você está selecionando uma entidade de energia, não uma entidade de potência ativa.
Entidades MQTT duplicadas aparecem
Duplicatas normalmente ocorrem quando:
- o YAML MQTT Manual e a Descoberta MQTT estão ambos ativos;
- o número de série do medidor ou o ID único de descoberta mudou;
- um firmware anterior publicou uma configuração de descoberta diferente;
- tópicos de descoberta retidos de uma configuração antiga permanecem no broker.
Escolha entre MQTT Manual ou Descoberta MQTT para as mesmas medições e, em seguida, remova a configuração obsoleta.
Remover entidades de descoberta retidas antigas
As mensagens de configuração da Descoberta MQTT são comumente retidas pelo broker para que o Home Assistant possa recriar entidades após uma reinicialização. Se um tópico de configuração antigo permanecer, excluir o dispositivo apenas na interface do Home Assistant pode não ser suficiente — a entidade pode retornar quando a configuração retida for recebida novamente.
Procedimento seguro de limpeza:
- Desative a opção HA MQTT Discovery no medidor ou desconecte-o temporariamente para que ele não republica imediatamente a configuração antiga.
- Utilize um cliente MQTT para inspecionar o prefixo de descoberta do Home Assistant, normalmente
homeassistant/#. - Identifique apenas os tópicos de configuração pertencentes ao número de série/dispositivo IAMMETER afetado.
- Publique um payload retido vazio para cada tópico de configuração obsoleto.
- Remova o dispositivo/entidades obsoletos do Home Assistant se eles permanecerem.
- Ative novamente a Descoberta no firmware atual.
- Confirme que um dispositivo e as entidades atuais esperadas foram criados.
Não exclua toda a árvore de tópicos retidos homeassistant/# num broker compartilhado. Isso pode remover a configuração de descoberta de dispositivos não relacionados.
Quando o MQTT Manual é a melhor escolha
Utilize o MQTT Manual quando você precisar de:
- nomes de entidades personalizados e IDs únicos;
- modelos JSON personalizados ou cálculos;
- apenas um subconjunto selecionado de medições;
- uma estrutura de tópicos compartilhada com aplicações não-Home Assistant;
- controle explícito sobre classe de dispositivo e classe de estado;
- compatibilidade com um sistema onde a Descoberta do Home Assistant está intencionalmente desativada.
Guias relacionados
- Configuração MQTT Manual de medidor de energia para Home Assistant
- Publicar dados IAMMETER num broker MQTT
- Comparar todos os métodos de integração IAMMETER–Home Assistant
- Atualizar para o firmware IAMMETER mais recente
- Documentação MQTT do Home Assistant
Atualizado: 19 de julho de 2026.
