API local de historial de energía para lecturas de kWh

Introducción

Para los usuarios que crean sus propios paneles, automatizaciones o herramientas de análisis sin conexión, los datos de energía reales son más útiles cuando están disponibles en un intervalo estable. Una única lectura de potencia en tiempo real puede mostrar lo que ocurre ahora, pero el historial de kWh de media hora ayuda a los usuarios a entender cómo cambian la importación y la exportación de electricidad a lo largo del tiempo.

A partir de la versión de firmware i.91.063TS8.bin, publicada el 2 de junio de 2026, IAMMETER admite una nueva API local: GET /api/energyhistory. Esta API devuelve lecturas de kWh almacenadas en caché local y muestreadas en torno a los límites de media hora UTC, lo que facilita el análisis del consumo de energía reciente sin depender únicamente del historial del lado de la nube.

Esto resulta especialmente útil para la monitorización solar, la monitorización de la energía del hogar y los flujos de trabajo personalizados de gestión de energía, en los que los usuarios quieren comparar los datos de energía de importación, exportación y por fase. IAMMETER no es solo un monitor; el propósito de recopilar estos datos es ayudar a los usuarios a optimizar el uso de la energía, mejorar el autoconsumo solar y reducir las facturas de electricidad.

Qué ofrece la API de historial de energía

El nuevo endpoint es:

GET /api/energyhistory

Devuelve lecturas de energía en kWh, muestreadas en torno a estos límites de media hora UTC:

• 00:00
• 00:30
• 01:00
• 01:30
• y así sucesivamente

El firmware conserva hasta 96 registros, equivalentes a 48 horas de historial con intervalos de 30 minutos. Los registros se almacenan en la RAM del módulo Wi-Fi, por lo que se pierden cuando el dispositivo se reinicia.

Una respuesta típica incluye:

• utc: la marca de tiempo UTC actual del módulo
• timeSynced: si el módulo tiene una hora UTC válida
• interval: el intervalo de muestreo, actualmente 1800 segundos
• count: el número de registros de historial disponibles
• order: actualmente newest_first
• unit: actualmente kWh
• channels: los nombres de los canales que corresponden a cada valor
• Datas: los registros de historial de media hora

Cada elemento de Datas incluye una marca de tiempo UTC y un array de valores en kWh. Los valores siguen el mismo orden que el array channels.

Por qué importa el historial de kWh de media hora

Los datos de energía de media hora son prácticos porque ofrecen a los usuarios una visión compacta pero significativa del comportamiento energético. En lugar de almacenar cada punto en tiempo real, los usuarios pueden analizar los valores acumulados de importación y exportación en franjas horarias fijas.

Por ejemplo, un usuario puede utilizar los datos locales para:

• Revisar la energía importada y exportada reciente sin esperar los informes de la nube.
• Exportar las últimas 48 horas de lecturas de kWh a una base de datos local o a un archivo CSV.
• Comparar los patrones de exportación solar con el consumo del hogar.
• Comprobar si una estrategia de automatización modifica el consumo de electricidad durante periodos concretos.
• Crear un panel local para el historial de energía reciente.

Para escenarios más amplios de monitorización solar, consulte la solución de monitorización de energía solar de IAMMETER. Para la monitorización de electricidad residencial, consulte la solución de monitorización de energía del hogar de IAMMETER.

Diseños de canales compatibles

El campo channels indica al cliente cómo interpretar los valores de cada registro de historial. Las distintas configuraciones del medidor devuelven diseños de canales diferentes.

Monofásico

["imp", "exp"]

Bifásico (split phase)

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

Trifásico

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

Trifásico con medición neta activada

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

Como los nombres de los canales se devuelven en la respuesta, el software personalizado debe leer primero el array channels y, después, asignar cada valor de Datas[].values en consecuencia.

Ejemplos originales de respuesta de la API

Los dos ejemplos siguientes muestran los valores de respuesta originales de la API para una respuesta vacía y una respuesta con datos.

Ejemplo de respuesta vacía

Después de que el dispositivo arranque, el array de historial puede estar vacío hasta que haya una hora UTC válida y tramas válidas del medidor. En este caso, la API puede devolver count: 0 y un array Datas vacío.

{
  "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": []
}

Esta respuesta es normal después del arranque. Un panel local o un script deben gestionar este estado y esperar nuevas muestras de media hora.

Ejemplo de respuesta con datos

El ejemplo siguiente muestra dos registros de media hora de un medidor trifásico. La respuesta está ordenada de más reciente a más antiguo.

{
  "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]
    }
  ]
}

En el registro más reciente, a_imp es 11.337 kWh, a_exp es 11.201 kWh, y así sucesivamente. El significado de cada valor lo define el array channels.

Uso de los valores de retorno en el software

Los ejemplos de respuesta originales anteriores son suficientes para crear una lógica de análisis local sencilla. La clave es leer primero channels y, después, aplicar ese orden a cada elemento de Datas.

Asignación de channels a values

Al crear software en torno a esta API, evite fijar las posiciones en el código salvo que la configuración del medidor sea fija. Un enfoque más seguro es convertir la lista de canales y el array de valores en un objeto con nombres.

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 la respuesta trifásica de ejemplo anterior, latestByChannel contendría:

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

Así los datos son más fáciles de almacenar, mostrar o exportar a una herramienta de análisis local.

Cálculo del cambio de kWh en media hora

Si utiliza los valores de kWh devueltos como lecturas de energía acumulada, el cambio entre dos registros adyacentes puede calcularse restando el valor más antiguo al valor más reciente del mismo canal.

Usando el ejemplo trifásico anterior:

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

Este tipo de cálculo puede ayudar a los usuarios a crear un informe reciente de importación/exportación, comparar los cambios de energía por fase o comprobar cuánta energía se importó o se exportó durante una franja concreta de media hora.

Comportamiento de muestreo importante

El historial de energía lo genera localmente el módulo Wi-Fi. El comportamiento de muestreo es importante a la hora de crear integraciones o herramientas de análisis:

• El muestreo se basa en tramas UART válidas del medidor.
• El módulo almacena la muestra más cercana a cada límite de media hora UTC.
• La hora UTC debe ser válida antes de que se almacenen los registros de historial.
• Si timeSynced es 0, no se registran nuevas muestras de historial.
• Después del arranque, Datas puede estar vacío hasta que se hayan capturado suficientes muestras válidas.
• Actualmente el almacenamiento está en RAM, por lo que la API está pensada para el historial local reciente, no para el almacenamiento a largo plazo.

Esto hace que la API sea adecuada para el sondeo local, el análisis a corto plazo y las pruebas de integración. Para los informes de energía a largo plazo, los usuarios deben seguir manteniendo una fuente de datos persistente, como los datos en la nube de IAMMETER o su propia base de datos.

Ideas de integración de ejemplo

Los desarrolladores y usuarios avanzados pueden usar /api/energyhistory como una fuente de datos local sencilla para el historial reciente de kWh.

Un enfoque habitual es sondear el endpoint periódicamente, leer la lista channels y guardar los nuevos registros de Datas en una base de datos local. Esto puede dar soporte a paneles locales, informes personalizados o scripts de análisis sin conexión.

Otro escenario útil es el análisis del autoconsumo solar. Al comparar los valores de kWh importados y exportados en franjas de media hora, los usuarios pueden entender mejor cuándo las cargas del hogar consumen localmente la generación solar y cuándo se exporta el excedente de energía. Esto puede favorecer mejores decisiones de automatización, como desplazar cargas flexibles a periodos con mayor producción solar.

Si está creando integraciones locales, consulte también API local, Modbus/TCP y MQTT y el Explorador de API local de IAMMETER.

Cómo encaja esto en la gestión de energía

El valor de una API de historial de energía no reside solo en que exponga más datos. El punto clave es lo que los usuarios pueden hacer con esos datos.

Con el historial de kWh de media hora, los usuarios pueden analizar la importación y la exportación reciente de electricidad, identificar patrones de uso y evaluar si las estrategias solares o de control de cargas realmente ayudan. Esto respalda el objetivo más amplio de IAMMETER: convertir los datos de monitorización de energía en decisiones prácticas que mejoren la eficiencia energética y reduzcan las facturas de electricidad.

Para los usuarios que combinan IAMMETER con plataformas de automatización, el historial de energía local también puede proporcionar una cómoda capa de datos para probar y validar la lógica de control. Por ejemplo, los usuarios de Home Assistant que optimizan el aprovechamiento del excedente solar pueden revisar los cambios recientes de kWh junto con el comportamiento de la automatización. Consulte Automatización de energía solar con Home Assistant e IAMMETER para un caso de uso relacionado.

Preguntas frecuentes

¿Puede esta API sustituir el historial de energía a largo plazo?

No. La API almacena hasta 96 registros, o 48 horas de datos de media hora, en RAM. Está diseñada para el historial local reciente. Los datos se pierden al reiniciar.

¿Por qué Datas está vacío después del arranque?

Después del arranque, el módulo necesita una hora UTC válida y tramas válidas del medidor antes de poder registrar muestras de historial. Hasta que se capturen suficientes muestras válidas, la API puede devolver un array Datas vacío.

¿Las marcas de tiempo se basan en la hora local?

No. Las franjas de muestreo están alineadas con los límites de media hora UTC.

¿Cómo debe interpretar el software el array de valores?

Lea siempre primero el campo channels. Los valores de cada array Datas[].values siguen el mismo orden que los nombres de los canales.