Medidor de Energia MQTT para Home Assistant: Configuração Manual YAML

Configurar Manualmente um Medidor de Energia MQTT no Home Assistant

Um medidor de energia MQTT pode publicar tensão, corrente, potência ativa e energia importada/exportada para um broker na sua rede local. O Home Assistant subscreve esses dados e converte os valores JSON em entidades de sensor que podem ser usadas em painéis, automações e no Painel de Energia.

Este guia explica o método Manual MQTT para medidores de energia IAMMETER:

1. configurar o broker MQTT na interface web do medidor;
2. conectar o Home Assistant ao mesmo broker;
3. definir os sensores MQTT necessários em YAML;
4. adicionar energia importada e exportada ao Painel de Energia.

O Manual MQTT oferece controle total sobre nomes de entidades, tópicos, modelos e metadados. Se preferir que o Home Assistant crie o dispositivo e as entidades automaticamente, use MQTT Discovery.

Manual MQTT e MQTT Discovery são métodos diferentes

Ambos os métodos usam um broker MQTT, mas a configuração no Home Assistant é diferente.

Para este guia, mantenha o HA MQTT Discovery desativado na interface web do medidor. Essa opção só é necessária quando deseja a descoberta automática do Home Assistant.

O que você precisa

• um medidor de energia IAMMETER com firmware atual;
• um broker MQTT acessível tanto pelo medidor quanto pelo Home Assistant;
• o endereço, porta, nome de usuário e senha do broker;
• o número de série do medidor;
• acesso à configuração YAML do Home Assistant.

O broker pode ser executado na mesma máquina do Home Assistant, no add-on do broker Mosquitto, em outro servidor da LAN ou em um host remoto. Use um broker local quando quiser que todo o caminho de dados permaneça dentro da LAN.

Todos os medidores IAMMETER atuais suportam o Manual MQTT. Modelos monofásicos, de canal duplo e trifásicos publicam diferentes estruturas de array JSON, portanto os modelos de valor devem corresponder ao payload real.

Passo 1: Configurar o broker MQTT na interface web do medidor

Abra a interface web local do medidor e vá para Settings. Configure:

Salve as configurações e aguarde o medidor reconectar.

A interface web do firmware atual suporta estas configurações de broker diretamente. Não é necessário configurar o nome de usuário e senha através do procedimento histórico da API local.

Para instruções completas de configuração do medidor e firmware antigo, veja publicar dados do IAMMETER em um broker MQTT.

Modo MQTT e IAMMETER Cloud

Quando o Modo de Execução do medidor é alterado para MQTT, ele publica as medições no seu broker em vez de enviá-las para a IAMMETER Cloud. Portanto, o Manual MQTT e a IAMMETER Cloud não funcionam simultaneamente no mesmo medidor.

Se precisar do Home Assistant e da IAMMETER Cloud ao mesmo tempo, use uma integração HTTP local ou Modbus TCP. Compare os métodos disponíveis no guia de integração de medidor de energia Home Assistant.

Passo 2: Verificar o tópico MQTT e o payload

O IAMMETER publica medições em tempo real em:

device/{SN}/realtime

Substitua {SN} pelo número de série do medidor. Por exemplo:

device/80123456/realtime

Antes de configurar os sensores do Home Assistant, subscreva o tópico com um cliente MQTT e confirme que as mensagens estão chegando. Isso evita que a resolução de problemas YAML seja misturada com problemas de broker, credenciais, firewall ou tópico.

JSON monofásico

Um medidor monofásico usa um array Data. Os cinco primeiros valores são:

Exemplo:

{
  "method": "uploadsn",
  "SN": "12345678",
  "Data": [228.91, 1.61, 225, 15066.47, 0]
}

JSON multicanal e trifásico

Medidores multicanal e trifásicos usam um array Datas. Cada array aninhado representa uma fase ou canal de medição:

Datas[0] → fase/canal A
Datas[1] → fase/canal B
Datas[2] → fase/canal C, quando presente

Dentro de cada array de fase/canal, as posições comuns são:

Sempre inspecione a mensagem MQTT real do seu modelo e firmware antes de copiar os modelos. Veja a definição completa de dados JSON do IAMMETER.

Passo 3: Conectar o Home Assistant ao broker

No Home Assistant:

1. Vá para Settings → Devices & services.
2. Selecione Add integration.
3. Pesquise por MQTT.
4. Insira o mesmo endereço, porta, nome de usuário e senha do broker usados pelo medidor.
5. Confirme que a Integração MQTT conecta com sucesso.

Se o Home Assistant já usa este broker, não adicione uma Integração MQTT duplicada. Os sensores definidos manualmente usarão a conexão existente do broker.

Passo 4: Adicionar sensores Manual MQTT em YAML

Os exemplos abaixo usam a estrutura de configuração atual do mqtt: sensor: do Home Assistant. Substitua o número de série em cada state_topic.

YAML do medidor de energia monofásico

mqtt:
  sensor:
    - name: "IAMMETER Voltage"
      unique_id: "iammeter_12345678_voltage"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[0] | float(0) }}"
      unit_of_measurement: "V"
      device_class: voltage
      state_class: measurement

    - name: "IAMMETER Current"
      unique_id: "iammeter_12345678_current"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[1] | float(0) }}"
      unit_of_measurement: "A"
      device_class: current
      state_class: measurement

    - name: "IAMMETER Active Power"
      unique_id: "iammeter_12345678_active_power"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[2] | float(0) }}"
      unit_of_measurement: "W"
      device_class: power
      state_class: measurement

    - name: "IAMMETER Imported Energy"
      unique_id: "iammeter_12345678_import_energy"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[3] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

    - name: "IAMMETER Exported Energy"
      unique_id: "iammeter_12345678_export_energy"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[4] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

O unique_id permite que o Home Assistant gerencie as configurações da entidade na interface. Mantenha cada ID único e estável. Não o altere apenas para renomear a entidade exibida.

YAML do medidor de energia trifásico

O exemplo a seguir cria as entidades da fase A. Duplique o bloco para as fases B e C, alterando Datas[0] para Datas[1] e Datas[2], e use nomes e IDs únicos distintos.

mqtt:
  sensor:
    - name: "IAMMETER Voltage A"
      unique_id: "iammeter_80123456_voltage_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][0] | float(0) }}"
      unit_of_measurement: "V"
      device_class: voltage
      state_class: measurement

    - name: "IAMMETER Current A"
      unique_id: "iammeter_80123456_current_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][1] | float(0) }}"
      unit_of_measurement: "A"
      device_class: current
      state_class: measurement

    - name: "IAMMETER Active Power A"
      unique_id: "iammeter_80123456_active_power_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][2] | float(0) }}"
      unit_of_measurement: "W"
      device_class: power
      state_class: measurement

    - name: "IAMMETER Imported Energy A"
      unique_id: "iammeter_80123456_import_energy_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][3] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

    - name: "IAMMETER Exported Energy A"
      unique_id: "iammeter_80123456_export_energy_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][4] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

Para WEM2067 e outros modelos multicanal, crie apenas o número de blocos de canal presentes no payload Datas real.

Evite dois blocos mqtt: de nível superior

Se o configuration.yaml já contém uma seção mqtt:, adicione os sensores dentro da seção existente. O YAML não pode conter com segurança duas chaves independentes de nível superior com o mesmo nome.

Para uma configuração grande, você pode manter os sensores MQTT em um arquivo incluído, mas siga a estrutura de inclusão e as regras de indentação do Home Assistant.

Passo 5: Verificar a configuração e carregar os sensores

Após salvar o YAML:

1. execute a verificação de configuração do Home Assistant;
2. corrija quaisquer erros de YAML, indentação ou modelo;
3. reinicie o Home Assistant se necessário;
4. abra Developer tools → States;
5. confirme que cada entidade MQTT tem um valor, unidade, classe de dispositivo e classe de estado plausíveis.

O valor da entidade deve mudar após a chegada de uma nova mensagem em device/{SN}/realtime.

Passo 6: Adicionar energia importada e exportada ao Painel de Energia

O Painel de Energia do Home Assistant requer entidades de energia cumulativas. Os exemplos YAML usam:

unit_of_measurement: "kWh"
device_class: energy
state_class: total_increasing

Vá para Settings → Dashboards → Energy e selecione:

• IAMMETER Imported Energy para consumo da rede;
• IAMMETER Exported Energy para retorno à rede.

Para um medidor trifásico, escolha a estrutura de entidade que corresponde à instalação e ao design do painel do Home Assistant. Você pode expor a energia das fases individualmente ou criar uma entidade total apropriada, mas não some valores sem confirmar como o medidor relata a energia por fase e líquida para o modo de fiação selecionado.

Não selecione a entidade de potência ativa medida em watts em um campo de energia do Painel de Energia. Potência é uma taxa instantânea; o painel requer kWh cumulativos.

Escolher um intervalo de publicação MQTT

O firmware atual do IAMMETER suporta um intervalo de publicação MQTT de até 2 segundos. O intervalo mais curto nem sempre é a melhor configuração.

Pontos de partida sugeridos:

Considere a capacidade do broker, o crescimento do gravador do Home Assistant, a confiabilidade da rede e o número de entidades. Uma mensagem contendo muitos valores de fase pode atualizar vários sensores do Home Assistant de uma só vez.

Modelos IAMMETER suportados

Todos os medidores de energia IAMMETER atuais suportam o Manual MQTT. A principal diferença no Home Assistant é a estrutura do payload e o número de canais de medição.

WEM3046T e WEM3046TE medem a saída secundária de 5 A de TCs externos. Aplique a relação de TC correta para obter os valores do lado primário. Esta é uma característica do sistema de medição, não uma limitação do MQTT ou do Home Assistant.

Resolução de problemas

Nenhuma mensagem MQTT chega

• Verifique o endereço e a porta do broker na interface web do medidor.
• Confirme o nome de usuário e a senha.
• Verifique os logs do broker para erros de autenticação ou conexão.
• Confirme que o medidor pode alcançar o broker através de quaisquer regras de firewall ou VLAN.
• Subscreva device/{SN}/realtime com um cliente MQTT independente.

As mensagens chegam, mas as entidades do Home Assistant não estão disponíveis

• Confirme que o Home Assistant está conectado ao mesmo broker.
• Verifique o tópico exato e o número de série.
• Compare Data versus Datas com o payload real.
• Valide a indentação YAML e os modelos.
• Verifique os logs do Home Assistant após recarregar ou reiniciar.

Algumas entidades mostram zero ou a medição errada

• Não copie um modelo Data monofásico para um payload Datas.
• Verifique a posição do array em relação à definição JSON.
• Confirme o índice da fase/canal.
• Para WEM3046T/WEM3046TE, confirme a relação do TC externo.

As entidades de energia estão ausentes do Painel de Energia

Confirme todos os três campos:

unit_of_measurement: "kWh"
device_class: energy
state_class: total_increasing

Confirme também que a entidade recebeu dados numéricos válidos e aparece em Developer tools → States.

Dispositivos ou sensores duplicados aparecem

O Manual MQTT e o MQTT Discovery podem criar entidades separadas a partir do mesmo medidor. Se estiver usando o método YAML, mantenha o HA MQTT Discovery desativado, a menos que deseje deliberadamente ambos os conjuntos e tenha planejado nomes de entidade únicos.

Guias relacionados

• Publicar dados do IAMMETER no seu broker MQTT
• Usar MQTT Discovery em vez de YAML
• Comparar todos os métodos de integração IAMMETER–Home Assistant
• Definição de dados JSON do IAMMETER
• Atualizar firmware do IAMMETER

Atualizado: 19 de julho de 2026.