API local d'historial energètic per a lectures de kWh

Introducció

Per als usuaris que creen els seus propis quadres de comandament, automatitzacions o eines d'anàlisi fora de línia, les dades energètiques reals són més útils quan estan disponibles en un interval estable. Una sola lectura de potència en temps real pot mostrar què està passant ara, però l'historial de kWh cada mitja hora ajuda els usuaris a entendre com canvien al llarg del temps l'energia importada i l'exportada.

A partir de la versió de firmware i.91.063TS8.bin, publicada el 2 de juny de 2026, IAMMETER admet una nova API local: GET /api/energyhistory. Aquesta API retorna lectures de kWh emmagatzemades a la memòria cau local i mostrejades al voltant de les fronteres de mitja hora UTC, cosa que facilita l'anàlisi del consum energètic recent sense dependre només de l'historial del núvol.

Això és especialment útil per al monitoratge solar, el monitoratge energètic de la llar i fluxos de treball personalitzats de gestió energètica en què els usuaris volen comparar les dades d'energia importada, exportada i per fase. IAMMETER no és només un monitor; l'objectiu de recollir aquestes dades és ajudar els usuaris a optimitzar el consum elèctric, millorar l'autoconsum solar i reduir la factura de la llum.

Què ofereix l'API d'historial energètic

El nou punt final és:

GET /api/energyhistory

Retorna lectures d'energia en kWh, mostrejades al voltant d'aquestes fronteres de mitja hora UTC:

• 00:00
• 00:30
• 01:00
• 01:30
• i així successivament

El firmware conserva fins a 96 registres, equivalents a 48 hores d'historial amb intervals de 30 minuts. Els registres s'emmagatzemen a la RAM del mòdul Wi-Fi, de manera que es perden quan el dispositiu es reinicia.

Una resposta típica inclou:

• utc: la marca de temps UTC actual del mòdul
• timeSynced: si el mòdul té una hora UTC vàlida
• interval: l'interval de mostreig, actualment 1800 segons
• count: el nombre de registres d'historial disponibles
• order: actualment newest_first
• unit: actualment kWh
• channels: els noms dels canals corresponents a cada valor
• Datas: els registres d'historial de mitja hora

Cada element de Datas inclou una marca de temps UTC i una matriu de valors de kWh. Els valors segueixen el mateix ordre que la matriu channels.

Per què és important l'historial de kWh cada mitja hora

Les dades energètiques de mitja hora són pràctiques perquè ofereixen als usuaris una visió compacta però significativa del comportament energètic. En lloc d'emmagatzemar cada punt en temps real, els usuaris poden analitzar els valors acumulats d'importació i exportació en franges horàries fixes.

Per exemple, un usuari pot utilitzar les dades locals per:

• Revisar l'energia importada i exportada recent sense esperar els informes del núvol.
• Exportar les darreres 48 hores de lectures de kWh a una base de dades local o a un fitxer CSV.
• Comparar els patrons d'exportació solar amb el consum de la llar.
• Comprovar si una estratègia d'automatització canvia el consum elèctric en períodes concrets.
• Construir un quadre de comandament local per a l'historial energètic recent.

Per a escenaris més amplis de monitoratge solar, consulteu la solució de monitoratge d'energia solar d'IAMMETER. Per al monitoratge elèctric residencial, consulteu la solució de monitoratge energètic de la llar d'IAMMETER.

Disposicions de canals compatibles

El camp channels indica al client com interpretar els valors de cada registre d'historial. Les diferents configuracions del mesurador retornen disposicions de canals diferents.

Monofàsic

["imp", "exp"]

Fase dividida

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

Trifàsic

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

Trifàsic amb mesura neta activada

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

Com que els noms dels canals es retornen a la resposta, el programari personalitzat hauria de llegir primer la matriu channels i després assignar cada valor de Datas[].values en conseqüència.

Exemples originals de resposta de l'API

Els dos exemples següents mostren els valors originals retornats per l'API per a una resposta buida i per a una resposta amb dades.

Exemple de resposta buida

Després d'iniciar el dispositiu, la matriu d'historial pot estar buida fins que hi hagi una hora UTC vàlida i trames del mesurador vàlides. En aquest cas, l'API pot retornar count: 0 i una matriu Datas buida.

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

Aquesta resposta és normal després de l'inici. Un quadre de comandament o un script locals haurien de gestionar aquest estat i esperar noves mostres de mitja hora.

Exemple de resposta amb dades

L'exemple següent mostra dos registres de mitja hora d'un mesurador trifàsic. La resposta està ordenada del més recent al més antic.

{
  "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 registre més recent, a_imp és 11.337 kWh, a_exp és 11.201 kWh, i així successivament. El significat de cada valor el defineix la matriu channels.

Ús dels valors retornats al programari

Els exemples originals de resposta anteriors són suficients per construir una lògica d'anàlisi local senzilla. La clau és llegir primer channels i després aplicar aquest ordre a cada element de Datas.

Assignar channels a values

Quan desenvolupeu programari al voltant d'aquesta API, eviteu codificar posicions fixes tret que la configuració del mesurador sigui fixa. Una manera més segura és convertir la llista de canals i la matriu de valors en un objecte amb noms.

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);

Per a la resposta trifàsica d'exemple anterior, latestByChannel contindria:

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

Això fa que les dades siguin més fàcils d'emmagatzemar, mostrar o exportar a una eina d'anàlisi local.

Calcular la variació de kWh en mitja hora

Si utilitzeu els valors de kWh retornats com a lectures d'energia acumulada, la variació entre dos registres adjacents es pot calcular restant el valor més antic del valor més recent per al mateix canal.

Utilitzant l'exemple trifàsic 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

Aquest tipus de càlcul pot ajudar els usuaris a crear un informe recent d'importació/exportació, comparar les variacions d'energia per fase o comprovar quanta energia es va importar o exportar durant una franja de mitja hora concreta.

Comportament important del mostreig

L'historial energètic el genera localment el mòdul Wi-Fi. El comportament del mostreig és important a l'hora de crear integracions o eines d'anàlisi:

• El mostreig es basa en trames vàlides del mesurador per UART.
• El mòdul emmagatzema la mostra més propera a cada frontera de mitja hora UTC.
• L'hora UTC ha de ser vàlida abans que s'emmagatzemin registres d'historial.
• Si timeSynced és 0, no es registra cap mostra nova d'historial.
• Després de l'inici, Datas pot estar buit fins que s'hagin capturat prou mostres vàlides.
• Actualment l'emmagatzematge es fa a la RAM, de manera que l'API està pensada per a l'historial local recent, no per a l'emmagatzematge a llarg termini.

Això fa que l'API sigui adequada per a la consulta periòdica local, l'anàlisi a curt termini i les proves d'integració. Per als informes energètics a llarg termini, els usuaris haurien de mantenir igualment una font de dades persistent, com les dades del núvol d'IAMMETER o la seva pròpia base de dades.

Idees d'integració d'exemple

Els desenvolupadors i els usuaris avançats poden utilitzar /api/energyhistory com a font de dades local senzilla per a l'historial recent de kWh.

Un enfocament habitual és consultar el punt final periòdicament, llegir la llista channels i desar els registres nous de Datas en una base de dades local. Això pot donar suport a quadres de comandament locals, informes personalitzats o scripts d'anàlisi fora de línia.

Un altre escenari útil és l'anàlisi de l'autoconsum solar. Comparant els valors de kWh importats i exportats en franges de mitja hora, els usuaris poden entendre millor quan les càrregues de la llar consumeixen localment la generació solar i quan s'exporta l'energia excedentària. Això pot ajudar a prendre millors decisions d'automatització, com desplaçar les càrregues flexibles a períodes amb més producció solar.

Si esteu creant integracions locals, consulteu també API local, Modbus/TCP i MQTT i l'explorador d'API local d'IAMMETER.

Com encaixa això en la gestió energètica

El valor d'una API d'historial energètic no rau només en el fet que exposi més dades. El punt clau és què poden fer els usuaris amb aquestes dades.

Amb l'historial de kWh cada mitja hora, els usuaris poden analitzar la importació i l'exportació elèctrica recents, identificar patrons de consum i avaluar si les estratègies solars o de control de càrregues realment ajuden. Això dona suport a l'objectiu més ampli d'IAMMETER: convertir les dades de monitoratge energètic en decisions pràctiques que millorin l'eficiència energètica i redueixin la factura de la llum.

Per als usuaris que combinen IAMMETER amb plataformes d'automatització, l'historial energètic local també pot proporcionar una capa de dades convenient per provar i validar la lògica de control. Per exemple, els usuaris de Home Assistant que optimitzen l'ús de l'excedent solar poden revisar les variacions recents de kWh juntament amb el comportament de les automatitzacions. Consulteu Automatització solar amb Home Assistant i IAMMETER per a un cas d'ús relacionat.

Preguntes freqüents

Aquesta API pot substituir l'historial energètic a llarg termini?

No. L'API emmagatzema fins a 96 registres, o 48 hores de dades de mitja hora, a la RAM. Està pensada per a l'historial local recent. Les dades es perden després de reiniciar.

Per què Datas està buit després de l'inici?

Després de l'inici, el mòdul necessita una hora UTC vàlida i trames vàlides del mesurador abans que es puguin registrar mostres d'historial. Fins que no es capturin prou mostres vàlides, l'API pot retornar una matriu Datas buida.

Les marques de temps es basen en l'hora local?

No. Les franges de mostreig estan alineades amb les fronteres de mitja hora UTC.

Com ha d'interpretar el programari la matriu de valors?

Llegiu sempre primer el camp channels. Els valors de cada matriu Datas[].values segueixen el mateix ordre que els noms dels canals.