Medidor de Energia Wi-Fi IAMMETER: APIs Locais e Interfaces Abertas

Medidor de Energia Wi-Fi IAMMETER: APIs Locais e Interfaces Abertas

Os medidores de energia Wi-Fi IAMMETER suportam a IAMMETER-Cloud, bem como integrações locais e de terceiros.

As interfaces disponíveis incluem:

• API HTTP Local via LAN
• Publicação MQTT e MQTTS
• Modbus TCP
• Upload TCP/TLS
• Upload HTTP/HTTPS
• Operação local autônoma

Estas interfaces permitem que os medidores IAMMETER atuem como fontes de dados abertas para:

• Home Assistant e outras plataformas de casa inteligente
• Automação Node-RED
• Painéis auto-hospedados
• Sistemas CLP e SCADA
• Sistemas Personalizados de Gerenciamento de Energia (EMS)
• Sistemas Personalizados de Gerenciamento de Edifícios (BMS)
• Servidores de dados de terceiros

Este guia descreve primeiro o firmware atual e a WebUI. Capturas de tela e métodos de configuração para firmwares mais antigos são mantidos na seção Legado final.

Para uma aplicação pronta para uso construída sobre estas capacidades, consulte Monitoramento de Energia Residencial, Monitoramento de Energia Solar ou monitoramento local sem acesso à Internet.

1) Atualize para o Firmware Mais Recente

O firmware IAMMETER é atualizado continuamente. Antes de configurar uma integração, verifique a versão atual e a compatibilidade do modelo:

• Página de Lançamento do Firmware IAMMETER

A WebUI do firmware mais recente expõe as opções de configuração comumente usadas diretamente. As chamadas de API de configuração manual mantidas posteriormente neste artigo são úteis principalmente ao manter instalações mais antigas.

2) Escolha o Modo de Execução na WebUI Atual

Selecione um modo de execução de acordo com para onde o medidor deve enviar dados ou como deve operar localmente.

O modo de execução controla o comportamento de upload de dados. A disponibilidade da API local e do Modbus TCP deve ser verificada para o modelo do medidor, firmware e integração selecionada.

3) Por Que as Interfaces Abertas São Importantes

Interfaces abertas permitem que os usuários decidam onde os dados de eletricidade são processados e armazenados.

As razões típicas incluem:

• Manter as medições dentro da rede local
• Enviar telemetria para um servidor existente
• Conectar dados de energia com Home Assistant ou Node-RED
• Construir painéis e alarmes personalizados
• Combinar dados de eletricidade com tarifas, lógica de controle solar ou de carga
• Operar em um local com acesso limitado ou instável à Internet

O acesso à nuvem e local não são necessariamente mutuamente exclusivos. A arquitetura adequada depende se o projeto precisa de relatórios da IAMMETER-Cloud, uma plataforma local, um servidor de terceiros ou uma combinação.

4) Enviar Dados para um Servidor de Terceiros

4.1 TCP e TLS

O IAMMETER pode enviar dados do medidor para um endpoint TCP ou TLS.

Na WebUI atual:

1. Selecione o modo de execução TCP.
2. Insira o endereço de destino.
3. Configure o intervalo de upload.
4. Salve as configurações e verifique os dados no servidor receptor.

Para um servidor TCP, use:

{domínio-ou-ip}:{porta}

Exemplo:

abc.com:12345

Para um servidor TLS, use:

tls://{domínio-ou-ip}:{porta}

Exemplo:

tls://abc.com:12345

A visão geral do firmware atual documenta um intervalo mínimo de upload de 2 segundos. Confirme o firmware atual e a capacidade do servidor receptor antes de selecionar um intervalo curto.

4.2 MQTT e MQTTS

O IAMMETER pode publicar telemetria diretamente para um broker MQTT comum ou usar MQTTS para transporte criptografado em firmware suportado.

Na WebUI atual:

1. Selecione o modo de execução MQTT.
2. Insira o endereço IP ou domínio do broker e a porta usando o formato MQTT ou MQTTS apropriado.
3. Insira o nome de usuário e senha do broker quando a autenticação for necessária.
4. Configure o intervalo de upload.
5. Salve e verifique se as mensagens chegam ao broker.

Para MQTT comum, insira o endereço e a porta do broker sem o prefixo mqtt://:

192.168.11.163:1883

Para MQTTS, inclua o prefixo mqtts://:

mqtts://{endereço-do-broker-mqtt}:{porta}

Exemplo:

mqtts://broker.example.com:8883

O suporte a MQTTS documentado na atualização de firmware de novembro de 2025 tem as seguintes limitações atuais:

• Suporta TLS 1.2 e versões anteriores.
• O upload de um certificado CA personalizado não é suportado.
• A verificação de nome de host não é suportada.
• Certificados do lado do cliente para autenticação TLS mútua não são suportados.

Estas limitações são importantes ao selecionar um broker e avaliar os requisitos de segurança da implantação.

A visão geral do firmware atual documenta um intervalo mínimo de upload de 2 segundos.

A Descoberta MQTT do Home Assistant é uma função adicional de descoberta do Home Assistant; não é necessária para toda integração MQTT. Consulte:

• Guia de Integração MQTT IAMMETER
• Descoberta MQTT no Home Assistant

Alterar uploadInterval Remotamente via MQTT/MQTTS

Com o firmware descrito na atualização de novembro de 2025, um medidor executando em modo MQTT se inscreve automaticamente em:

device/{sn}/config

Publique o seguinte JSON de outro cliente MQTT para alterar o intervalo de upload remotamente:

{"uploadInterval": 10}

Substitua 10 pelo intervalo necessário em segundos e {sn} pelo número de série do medidor no tópico.

Esta configuração remota via MQTT é diferente do método local mais antigo /api/uploadinterval mantido na seção Legado.

4.3 HTTP e HTTPS

O IAMMETER pode enviar dados para um servidor HTTP/HTTPS personalizado.

Na WebUI atual:

1. Selecione o modo de execução HTTP.
2. Insira o endereço e a porta do servidor.
3. Configure o intervalo de upload.
4. Salve e verifique as requisições no servidor.

O firmware atual suporta tanto a porta HTTPS padrão quanto uma porta HTTPS personalizada.

Use um destes formatos:

• HTTP comum sem porta explícita: {endereço} — usa a porta 80 por padrão.
• HTTP comum com porta personalizada: {endereço}:{porta}.
• HTTPS sem porta explícita: https://{endereço} — usa a porta 443 por padrão.
• HTTPS com porta personalizada: https://{endereço}:{porta} — usa a porta especificada.

O prefixo https:// seleciona HTTPS. A porta 443 não é mais a única porta disponível para HTTPS.

Exemplos:

api.example.com
api.example.com:8080
https://api.example.com
https://api.example.com:8443

Consulte Novo Firmware Adiciona MQTTS, Configuração Remota e Porta HTTPS Personalizada para a nota de lançamento do firmware.

Para manipulação de payload no lado do servidor, veja também Integrar IAMMETER com um Servidor de Terceiros.

5) Ler Dados Localmente via HTTP

Conecte o medidor à LAN e solicite dados do seu endereço IP local. Estas requisições não exigem a IAMMETER-Cloud.

Teste as APIs interativamente: Abra o Explorador de API Local IAMMETER, insira o endereço IP local do medidor e selecione a página de teste da API WEM. O explorador estilo Swagger lista as APIs locais disponíveis e permite enviar requisições de teste diretamente do navegador. Seu navegador e o medidor IAMMETER devem estar na mesma LAN.

5.1 GET /api/monitorjson

Retorna medições elétricas em tempo real.

Os dados padrão incluem valores como:

• Tensão (Voltage)
• Corrente (Current)
• Potência ativa (Active power)
• kWh direto/importado (Forward/import kWh)
• kWh reverso/exportado (Reverse/export kWh)
• Frequência (Frequency)
• Fator de potência (Power factor)

Exemplo de resposta:

{
  "method": "uploadsn",
  "mac": "B0F8933C4F94",
  "version": "i.75.97.9",
  "server": "em",
  "SN": "3E0BAF87",
  "Datas": [
    [220.0, 9.99, 2198, 11.337, 11.201, 49.99, 1.00],
    [222.5, 9.99, 1100, 11.039, 10.908, 49.99, 0.50],
    [263.5, 9.99, 1213, 10.975, 10.846, 49.99, 0.55]
  ]
}

O número de matrizes de medição depende do modelo do medidor e da quantidade de canais.

Se a medição de potência reativa estiver ativada em um modelo/firmware suportado, o formato da resposta pode conter campos adicionais. Consulte Formato de Dados de Medição de Potência Reativa.

5.2 GET /api/monitor

Retorna uma resposta estendida em tempo real que também inclui informações de Wi-Fi, como:

• ssid — nome do ponto de acesso conectado
• sig — intensidade do sinal Wi-Fi

Use este endpoint quando uma integração precisar tanto de medições elétricas quanto do status básico do Wi-Fi.

5.3 GET /api/wifidata

Retorna informações de configuração do firmware, dispositivo e rede.

Exemplo:

{
  "version": "i.75.97.9",
  "SN": "3E0BAF87",
  "mac": "B0F8933C4F94",
  "type": "PM",
  "ssid": "example-wifi",
  "ip": "192.168.11.62",
  "netmask": "255.255.255.0",
  "gw": "192.168.11.1",
  "dns": "192.168.11.1",
  "dhcp": 1,
  "runMode": "tcp",
  "uploadinterval": 60
}

Não publique respostas contendo números de série do dispositivo, endereços MAC, endereçamento interno ou informações de Wi-Fi, a menos que os valores tenham sido sanitizados.

6) Formato JSON Entre Modos de Upload

O IAMMETER usa uma estrutura JSON de medição central consistente em HTTP, TCP, MQTT e na API local. Isso reduz o trabalho necessário quando um sistema receptor suporta múltiplos métodos de transporte.

O método de transporte e o envelope ainda podem afetar como um receptor se conecta, autentica ou estrutura uma mensagem. Implemente o sistema receptor de acordo com o formato documentado para o modo selecionado.

• Definição de Dados JSON do Medidor de Energia IAMMETER

7) Modbus TCP

Os medidores IAMMETER suportam Modbus TCP para integração direta via LAN com clientes compatíveis.

Clientes típicos incluem:

• Home Assistant
• CLPs
• Sistemas SCADA
• Gateways industriais
• Aplicações Modbus personalizadas

Referências:

• Visão Geral do Modbus TCP IAMMETER
• Visão Geral da Integração com Home Assistant

Confirme o modelo do medidor, firmware, definição de registros, intervalo de polling e comportamento do cliente antes da implantação.

8) Cenários de Integração

9) Resumo da Interface Atual e Recursos

Recursos adicionais:

• Firmware Mais Recente
• Nota do Firmware sobre MQTTS e Porta HTTPS Personalizada
• Tutoriais em Vídeo
• Definição de Dados JSON
• Visão Geral do Modbus TCP
• Desenvolva Seu Próprio Sistema
• Monitorar sem Acesso à Internet

As APIs locais e protocolos abertos do IAMMETER tornam possível começar com monitoramento em tempo real e depois adicionar um EMS personalizado, um painel auto-hospedado ou um fluxo de automação.

10) Páginas de Firmware Legado e Métodos de Configuração

O material a seguir é mantido apenas para medidores que ainda executam firmware mais antigo ou para usuários mantendo uma integração existente. Para uma nova instalação, atualize para o firmware mais recente e use a WebUI atual sempre que a opção necessária estiver disponível.

10.1 Página de Modo de Execução Legado

Firmware mais antigo usava a seguinte página de seleção de modo de execução:

O layout e os nomes das opções podem não corresponder à WebUI atual mostrada anteriormente neste guia.

10.2 Página TCP/TLS Legado

Integrações de firmware mais antigo podem referir-se a esta página de configuração TCP/TLS e ao guia relacionado:

• Guia de Integração com Servidor de Terceiros Legado
• Vídeo de Upload para Servidor Legado

10.3 Página MQTT Legado

A documentação MQTT mais antiga usava esta interface de configuração:

Para o fluxo de trabalho atual, use as instruções da WebUI atual no início deste artigo e o Guia de Integração MQTT atualizado.

10.4 Página HTTP/HTTPS Legado

Firmware mais antigo usava a seguinte página de destino HTTP/HTTPS:

O guia de integração legado é mantido em Upload via HTTP/HTTPS.

Neste fluxo de trabalho mais antigo, o HTTPS estava associado à porta padrão 443 e não exigia o prefixo https://. O firmware atual, em vez disso, usa o prefixo https:// para selecionar HTTPS e suporta tanto a porta padrão 443 quanto uma porta personalizada especificada explicitamente.

10.5 APIs de Configuração Legado

As seguintes chamadas de API local apareciam em fluxos de trabalho de configuração anteriores. No firmware atual, as configurações correspondentes devem normalmente ser configuradas através da WebUI quando a opção estiver disponível.

/api/uploadinterval?x=<segundos>

Método legado para definir o intervalo de upload não-Cloud.

/api/mqtt

Método legado para configurar credenciais MQTT.

/api/netmetring

Método legado para ativar ou desativar o modo Net Energy Metering.

• Referência do Net Energy Metering

/api/ctcratio

Método legado para aplicar o multiplicador documentado da Fase-C em cenários específicos de split-phase ou balanceados.

• Referência da Relação CTC

/api/reactive

Método legado para ativar ou desativar a medição de potência reativa e energia reativa em firmwares/modelos suportados.

• Referência de Potência Reativa

/api/ratio — Apenas WEM3046T

O WEM3046T usa TCs externos com saídas secundárias de 5 A. Instruções de configuração mais antigas definem a relação do TC com:

/api/ratio?x={relação_do_tc}

Exemplo:

/api/ratio?x=400

Este endpoint é específico para o WEM3046T e é inválido para outros modelos IAMMETER. Para firmware atual, use a configuração da WebUI atual do modelo quando disponível.

Material legado mantido para referência retroativa; instalações atuais devem seguir a WebUI do firmware mais recente.