API de Histórico de Energia Local para Leituras em kWh

Introdução

Para usuários que criam seus próprios dashboards, automações ou ferramentas de análise offline, os dados reais de energia são mais úteis quando estão disponíveis em um intervalo estável. Uma única leitura de potência em tempo real pode mostrar o que está acontecendo agora, mas o histórico de kWh de meia em meia hora ajuda os usuários a entender como a importação e a exportação de eletricidade mudam ao longo do tempo.

A partir da versão de firmware i.91.063TS8.bin, lançada em 2 de junho de 2026, o IAMMETER oferece suporte a uma nova API local: GET /api/energyhistory. Essa API retorna leituras de kWh armazenadas em cache localmente e amostradas em torno dos limites de meia hora em UTC, o que facilita a análise do consumo recente de energia sem depender apenas do histórico do lado da nuvem.

Isso é especialmente útil para monitoramento solar, monitoramento de energia residencial e fluxos de trabalho personalizados de gerenciamento de energia, nos quais os usuários desejam comparar dados de energia de importação, exportação e por fase. O IAMMETER não é apenas um monitor; o objetivo de coletar esses dados é ajudar os usuários a otimizar o uso de energia, aumentar o autoconsumo solar e reduzir as contas de eletricidade.

O que a API de Histórico de Energia oferece

O novo endpoint é:

GET /api/energyhistory

Ele retorna leituras de energia em kWh, amostradas em torno destes limites de meia hora em UTC:

• 00:00
• 00:30
• 01:00
• 01:30
• e assim por diante

O firmware mantém até 96 registros, o equivalente a 48 horas de histórico em intervalos de 30 minutos. Os registros são armazenados na RAM do módulo Wi-Fi, portanto são perdidos depois que o dispositivo é reiniciado.

Uma resposta típica inclui:

• utc: o carimbo de data/hora UTC atual do módulo
• timeSynced: se o módulo tem um horário UTC válido
• interval: o intervalo de amostragem, atualmente 1800 segundos
• count: o número de registros de histórico disponíveis
• order: atualmente newest_first
• unit: atualmente kWh
• channels: os nomes dos canais correspondentes a cada valor
• Datas: os registros de histórico de meia em meia hora

Cada item em Datas inclui um carimbo de data/hora UTC e um array de valores em kWh. Os valores seguem a mesma ordem do array channels.

Por que o histórico de kWh de meia em meia hora é importante

Os dados de energia de meia em meia hora são práticos porque oferecem aos usuários uma visão compacta, mas significativa, do comportamento do consumo de energia. Em vez de armazenar cada ponto em tempo real, os usuários podem analisar os valores acumulados de importação e exportação em intervalos de tempo fixos.

Por exemplo, um usuário pode usar os dados locais para:

• Revisar a energia importada e exportada recentemente sem esperar pelos relatórios da nuvem.
• Exportar as leituras de kWh das últimas 48 horas para um banco de dados local ou arquivo CSV.
• Comparar os padrões de exportação solar com o consumo da residência.
• Verificar se uma estratégia de automação altera o consumo de eletricidade em períodos específicos.
• Criar um dashboard local para o histórico de energia recente.

Para cenários mais amplos de monitoramento solar, consulte a Solução de Monitoramento de Energia Solar da IAMMETER. Para monitoramento de eletricidade residencial, consulte a Solução de Monitoramento de Energia Residencial da IAMMETER.

Layouts de canais compatíveis

O campo channels informa ao cliente como interpretar os valores em cada registro de histórico. Diferentes configurações de medidor retornam layouts de canais diferentes.

Monofásico

["imp", "exp"]

Split Phase (fase dividida)

["a_imp", "a_exp", "b_imp", "b_exp"]

Trifásico

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"]

Trifásico com medição líquida (net metering) habilitada

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp", "nem_imp", "nem_exp"]

Como os nomes dos canais são retornados na resposta, softwares personalizados devem ler primeiro o array channels e depois mapear cada valor em Datas[].values de acordo.

Exemplos de retorno originais da API

Os dois exemplos a seguir mostram os valores de retorno originais da API para uma resposta vazia e para uma resposta com dados.

Exemplo de resposta vazia

Depois que o dispositivo é inicializado, o array de histórico pode ficar vazio até que um horário UTC válido e frames válidos do medidor estejam disponíveis. Nesse caso, a API pode retornar count: 0 e um array Datas vazio.

{
  "utc": 1780023600,
  "timeSynced": 1,
  "interval": 1800,
  "count": 0,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": []
}

Essa resposta é normal após a inicialização. Um dashboard ou script local deve tratar esse estado e aguardar novas amostras de meia em meia hora.

Exemplo de resposta com dados

O exemplo a seguir mostra dois registros de meia em meia hora de um medidor trifásico. A resposta está ordenada do mais recente para o mais antigo.

{
  "utc": 1780023700,
  "timeSynced": 1,
  "interval": 1800,
  "count": 2,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": [
    {
      "utc": 1780023600,
      "values": [11.337, 11.201, 11.039, 10.908, 10.975, 10.846]
    },
    {
      "utc": 1780021800,
      "values": [11.330, 11.198, 11.030, 10.900, 10.970, 10.840]
    }
  ]
}

No registro mais recente, a_imp é 11.337 kWh, a_exp é 11.201 kWh, e assim por diante. O significado de cada valor é definido pelo array channels.

Usando os valores de retorno em software

Os exemplos de retorno originais acima já bastam para criar uma lógica simples de análise local. O ponto principal é ler channels primeiro e depois aplicar essa ordem a cada item em Datas.

Mapeando channels para values

Ao desenvolver software em torno dessa API, evite fixar posições no código, a menos que a configuração do medidor seja fixa. Uma abordagem mais segura é converter a lista de canais e o array de valores em um objeto nomeado.

const response = await fetch("http://<meter-ip>/api/energyhistory").then((res) => res.json());
const latest = response.Datas[0];

const latestByChannel = Object.fromEntries(
  response.channels.map((name, index) => [name, latest.values[index]])
);

console.log(latest.utc, latestByChannel);

Para a resposta trifásica de exemplo acima, latestByChannel conteria:

{
  "a_imp": 11.337,
  "a_exp": 11.201,
  "b_imp": 11.039,
  "b_exp": 10.908,
  "c_imp": 10.975,
  "c_exp": 10.846
}

Isso torna os dados mais fáceis de armazenar, exibir ou exportar para uma ferramenta de análise local.

Calculando a variação de kWh em meia hora

Se você usar os valores de kWh retornados como leituras acumuladas de energia, a variação entre dois registros adjacentes pode ser calculada subtraindo o valor mais antigo do valor mais recente para o mesmo canal.

Usando o exemplo trifásico acima:

a_imp change = 11.337 - 11.330 = 0.007 kWh
a_exp change = 11.201 - 11.198 = 0.003 kWh
b_imp change = 11.039 - 11.030 = 0.009 kWh
b_exp change = 10.908 - 10.900 = 0.008 kWh

Esse tipo de cálculo pode ajudar os usuários a montar um relatório recente de importação/exportação, comparar variações de energia por fase ou verificar quanta energia foi importada ou exportada em um intervalo específico de meia hora.

Comportamento importante da amostragem

O histórico de energia é gerado localmente pelo módulo Wi-Fi. O comportamento de amostragem é importante ao criar integrações ou ferramentas de análise:

• A amostragem é conduzida por frames válidos do medidor recebidos via UART.
• O módulo armazena a amostra mais próxima de cada limite de meia hora em UTC.
• O horário UTC precisa ser válido antes que os registros de histórico sejam armazenados.
• Se timeSynced for 0, nenhuma nova amostra de histórico é registrada.
• Após a inicialização, Datas pode ficar vazio até que amostras válidas suficientes tenham sido capturadas.
• O armazenamento atual é baseado em RAM, portanto a API se destina ao histórico local recente, e não ao armazenamento de longo prazo.

Isso torna a API adequada para consultas locais periódicas (polling), análise de curto prazo e testes de integração. Para relatórios de energia de longo prazo, os usuários ainda devem manter uma fonte de dados persistente, como os dados na nuvem da IAMMETER ou o próprio banco de dados.

Exemplos de ideias de integração

Desenvolvedores e usuários avançados podem usar /api/energyhistory como uma fonte de dados local simples para o histórico recente de kWh.

Uma abordagem comum é consultar o endpoint periodicamente, ler a lista channels e salvar quaisquer novos registros de Datas em um banco de dados local. Isso pode dar suporte a dashboards locais, relatórios personalizados ou scripts de análise offline.

Outro cenário útil é a análise do autoconsumo solar. Ao comparar os valores de kWh importados e exportados nos intervalos de meia hora, os usuários conseguem entender melhor quando as cargas da residência consomem localmente a geração solar e quando o excedente de energia é exportado. Isso pode apoiar decisões de automação melhores, como deslocar cargas flexíveis para períodos com maior geração solar.

Se você está criando integrações locais, consulte também API Local, Modbus/TCP e MQTT e o IAMMETER Local API Explorer.

Como isso se encaixa no gerenciamento de energia

O valor de uma API de histórico de energia não está apenas em expor mais dados. O ponto principal é o que os usuários podem fazer com esses dados.

Com o histórico de kWh de meia em meia hora, os usuários podem analisar a importação e a exportação recentes de eletricidade, identificar padrões de uso e avaliar se as estratégias de energia solar ou de controle de carga realmente estão ajudando. Isso apoia o objetivo mais amplo da IAMMETER: transformar dados de monitoramento de energia em decisões práticas que melhorem a eficiência energética e reduzam as contas de eletricidade.

Para usuários que combinam o IAMMETER com plataformas de automação, o histórico de energia local também pode oferecer uma camada de dados conveniente para testar e validar a lógica de controle. Por exemplo, usuários do Home Assistant que otimizam o aproveitamento do excedente solar podem revisar as variações recentes de kWh junto com o comportamento da automação. Consulte Automação de Energia Solar com Home Assistant e IAMMETER para um caso de uso relacionado.

Perguntas frequentes

Esta API pode substituir o histórico de energia de longo prazo?

Não. A API armazena até 96 registros, ou 48 horas de dados de meia em meia hora, na RAM. Ela foi projetada para o histórico local recente. Os dados são perdidos após a reinicialização.

Por que Datas fica vazio após a inicialização?

Após a inicialização, o módulo precisa de um horário UTC válido e de frames válidos do medidor antes que as amostras de histórico possam ser registradas. Até que amostras válidas suficientes sejam capturadas, a API pode retornar um array Datas vazio.

Os carimbos de data/hora são baseados no horário local?

Não. Os intervalos de amostragem são alinhados aos limites de meia hora em UTC.

Como o software deve interpretar o array de valores?

Leia sempre o campo channels primeiro. Os valores em cada array Datas[].values seguem a mesma ordem dos nomes dos canais.