Lokale energiegeschiedenis-API voor kWh-uitlezingen

Inleiding

Voor gebruikers die hun eigen dashboards, automatiseringen of offline analysetools bouwen, zijn echte energiedata nuttiger wanneer ze met een vast interval beschikbaar zijn. Een enkele realtime vermogensmeting laat zien wat er nu gebeurt, maar een kWh-geschiedenis per half uur helpt gebruikers begrijpen hoe import en export van elektriciteit in de loop van de tijd veranderen.

Vanaf firmwareversie i.91.063TS8.bin, uitgebracht op 2 juni 2026, ondersteunt IAMMETER een nieuwe lokale API: GET /api/energyhistory. Deze API retourneert lokaal gecachte kWh-waarden die rond de UTC-halfuurgrenzen worden bemonsterd, waardoor recent energieverbruik eenvoudiger te analyseren is zonder alleen op cloudgeschiedenis te vertrouwen.

Dit is vooral nuttig voor zonnemonitoring, monitoring van huisenergie en aangepaste workflows voor energiebeheer waarbij gebruikers import-, export- en fase-energiedata willen vergelijken. IAMMETER is niet alleen een monitor; het doel van het verzamelen van deze data is gebruikers helpen hun energieverbruik te optimaliseren, het zelfverbruik van zonne-energie te verbeteren en de elektriciteitsrekening te verlagen.

Wat de energiegeschiedenis-API biedt

Het nieuwe endpoint is:

GET /api/energyhistory

Het retourneert energiewaarden in kWh, bemonsterd rond deze UTC-halfuurgrenzen:

• 00:00
• 00:30
• 01:00
• 01:30
• enzovoort

De firmware bewaart maximaal 96 records, gelijk aan 48 uur geschiedenis met intervallen van 30 minuten. De records worden opgeslagen in het RAM van de Wi-Fi-module, dus ze gaan verloren nadat het apparaat opnieuw is opgestart.

Een typische respons bevat:

• utc: de huidige UTC-tijdstempel van de module
• timeSynced: of de module een geldige UTC-tijd heeft
• interval: het bemonsteringsinterval, momenteel 1800 seconden
• count: het aantal beschikbare geschiedenisrecords
• order: momenteel newest_first
• unit: momenteel kWh
• channels: de kanaalnamen die bij elke waarde horen
• Datas: de geschiedenisrecords per half uur

Elk item in Datas bevat een UTC-tijdstempel en een array met kWh-waarden. De waarden volgen dezelfde volgorde als de array channels.

Waarom kWh-geschiedenis per half uur belangrijk is

Energiedata per half uur is praktisch omdat het gebruikers een compact maar betekenisvol beeld van energiegedrag geeft. In plaats van elk realtime punt op te slaan, kunnen gebruikers de geaccumuleerde import- en exportwaarden over vaste tijdsloten analyseren.

Een gebruiker kan de lokale data bijvoorbeeld gebruiken om:

• recent geïmporteerde en geëxporteerde energie te bekijken zonder te wachten op cloudrapporten.
• de laatste 48 uur aan kWh-waarden te exporteren naar een lokale database of een CSV-bestand.
• exportpatronen van zonne-energie te vergelijken met het verbruik in huis.
• te controleren of een automatiseringsstrategie het elektriciteitsverbruik in bepaalde perioden verandert.
• een lokaal dashboard voor recente energiegeschiedenis te bouwen.

Voor bredere scenario's voor zonnemonitoring zie de IAMMETER-oplossing voor zonne-energiemonitoring. Voor monitoring van elektriciteit in woningen zie de IAMMETER-oplossing voor huisenergiemonitoring.

Ondersteunde kanaalindelingen

Het veld channels vertelt de client hoe de waarden in elk geschiedenisrecord moeten worden geïnterpreteerd. Verschillende meterconfiguraties retourneren verschillende kanaalindelingen.

Eenfasig

["imp", "exp"]

Split-phase (twee fasen)

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

Driefasig

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

Driefasig met netmetering ingeschakeld

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

Omdat de kanaalnamen in de respons worden geretourneerd, moet aangepaste software eerst de array channels lezen en daarna elke waarde in Datas[].values daaraan koppelen.

Originele voorbeelden van API-responses

De volgende twee voorbeelden tonen de originele API-retourwaarden voor een lege respons en een respons met data.

Voorbeeld van een lege respons

Nadat het apparaat is opgestart, kan de geschiedenisarray leeg zijn totdat een geldige UTC-tijd en geldige meterframes beschikbaar zijn. In dat geval kan de API count: 0 en een lege array Datas retourneren.

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

Deze respons is normaal na het opstarten. Een lokaal dashboard of script moet deze toestand afhandelen en wachten op nieuwe monsters per half uur.

Voorbeeld van een respons met data

Het volgende voorbeeld toont twee records per half uur van een driefasige meter. De respons is geordend van nieuw naar oud.

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

In het nieuwste record is a_imp 11.337 kWh, is a_exp 11.201 kWh, enzovoort. De betekenis van elke waarde wordt bepaald door de array channels.

De retourwaarden in software gebruiken

De originele voorbeelden hierboven zijn voldoende om eenvoudige lokale analyselogica te bouwen. Het belangrijkste is om eerst channels te lezen en die volgorde vervolgens toe te passen op elk item in Datas.

channels aan values koppelen

Vermijd bij het bouwen van software rond deze API het hardcoderen van posities, tenzij de meterconfiguratie vastligt. Een veiliger aanpak is de kanalenlijst en de waardearray om te zetten in een object met namen.

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

Voor de voorbeeldrespons van de driefasige meter hierboven zou latestByChannel het volgende bevatten:

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

Zo is de data eenvoudiger op te slaan, weer te geven of te exporteren naar een lokale analysetool.

Een kWh-verandering per half uur berekenen

Als u de geretourneerde kWh-waarden gebruikt als geaccumuleerde energiewaarden, kan de verandering tussen twee aangrenzende records worden berekend door voor hetzelfde kanaal de oudere waarde van de nieuwere waarde af te trekken.

Met het driefasige voorbeeld hierboven:

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

Dit soort berekening kan gebruikers helpen een recent import-/exportrapport te maken, fase-energieveranderingen te vergelijken of te controleren hoeveel energie in een bepaald halfuurslot is geïmporteerd of geëxporteerd.

Belangrijk bemonsteringsgedrag

De energiegeschiedenis wordt lokaal gegenereerd door de Wi-Fi-module. Het bemonsteringsgedrag is belangrijk bij het bouwen van integraties of analysetools:

• De bemonstering wordt gestuurd door geldige UART-meterframes.
• De module slaat het monster op dat het dichtst bij elke UTC-halfuurgrens ligt.
• De UTC-tijd moet geldig zijn voordat geschiedenisrecords worden opgeslagen.
• Als timeSynced 0 is, worden geen nieuwe geschiedenisgegevens vastgelegd.
• Na het opstarten kan Datas leeg zijn totdat voldoende geldige monsters zijn vastgelegd.
• De opslag is momenteel gebaseerd op RAM, dus de API is bedoeld voor recente lokale geschiedenis, niet voor langdurige opslag.

Daardoor is de API geschikt voor lokaal pollen, analyse op korte termijn en integratietests. Voor energierapporten op lange termijn moeten gebruikers nog steeds een persistente databron aanhouden, zoals IAMMETER-clouddata of hun eigen database.

Voorbeelden van integratie-ideeën

Ontwikkelaars en gevorderde gebruikers kunnen /api/energyhistory gebruiken als eenvoudige lokale databron voor recente kWh-geschiedenis.

Een veelvoorkomende aanpak is het endpoint periodiek pollen, de lijst channels lezen en nieuwe Datas-records opslaan in een lokale database. Dit kan lokale dashboards, aangepaste rapporten of offline analysescripts ondersteunen.

Een ander nuttig scenario is de analyse van het zelfverbruik van zonne-energie. Door geïmporteerde en geëxporteerde kWh-waarden over halfuursloten te vergelijken, kunnen gebruikers beter begrijpen wanneer huishoudelijke verbruikers de zonne-opwek lokaal gebruiken en wanneer overtollige energie wordt geëxporteerd. Dit kan betere automatiseringsbeslissingen ondersteunen, zoals het verschuiven van flexibele verbruikers naar perioden met een hogere zonne-opbrengst.

Als u lokale integraties bouwt, zie ook Lokale API, Modbus/TCP en MQTT en de IAMMETER Local API Explorer.

Hoe dit past in energiebeheer

De waarde van een energiegeschiedenis-API is niet alleen dat er meer data beschikbaar komt. Het belangrijkste is wat gebruikers met die data kunnen doen.

Met een kWh-geschiedenis per half uur kunnen gebruikers recente import en export van elektriciteit analyseren, gebruikspatronen identificeren en beoordelen of strategieën voor zonne-energie of lastregeling daadwerkelijk helpen. Dit ondersteunt het bredere doel van IAMMETER: energiemonitoringsdata omzetten in praktische beslissingen die de energie-efficiëntie verbeteren en de elektriciteitsrekening verlagen.

Voor gebruikers die IAMMETER combineren met automatiseringsplatforms kan lokale energiegeschiedenis ook een handige datalaag vormen voor het testen en valideren van regellogica. Home Assistant-gebruikers die het overschot aan zonne-energie optimaliseren, kunnen bijvoorbeeld recente kWh-veranderingen naast het automatiseringsgedrag bekijken. Zie Home Assistant-automatisering voor zonne-energie met IAMMETER voor een gerelateerde use case.

Veelgestelde vragen

Kan deze API de energiegeschiedenis op lange termijn vervangen?

Nee. De API slaat maximaal 96 records op, oftewel 48 uur aan data per half uur, in RAM. De API is ontworpen voor recente lokale geschiedenis. De data gaat verloren na een herstart.

Waarom is Datas leeg na het opstarten?

Na het opstarten heeft de module een geldige UTC-tijd en geldige meterframes nodig voordat geschiedenisgegevens kunnen worden vastgelegd. Totdat voldoende geldige monsters zijn vastgelegd, kan de API een lege array Datas retourneren.

Zijn de tijdstempels gebaseerd op de lokale tijd?

Nee. De bemonsteringsslots zijn uitgelijnd op UTC-halfuurgrenzen.

Hoe moet software de waardearray interpreteren?

Lees altijd eerst het veld channels. De waarden in elke array Datas[].values volgen dezelfde volgorde als de kanaalnamen.