Lokalt API for energihistorikk for kWh-avlesninger

title: Lokalt API for energihistorikk for kWh-avlesninger

abstract: Les halvtimesvis kWh-historikk lokalt for offline analyse.

language: no

author: Jessica

Innledning

For brukere som bygger sine egne dashboards, automatiseringer eller verktøy for offline analyse, er reelle energidata mer nyttige når de er tilgjengelige med et stabilt intervall. En enkelt effektavlesning i sanntid kan vise hva som skjer akkurat nå, men kWh-historikk per halvtime hjelper brukere med å forstå hvordan import og eksport av strøm endrer seg over tid.

Fra og med fastvareversjonen i.91.063TS8.bin, utgitt 2. juni 2026, støtter IAMMETER et nytt lokalt API: GET /api/energyhistory. Dette API-et returnerer lokalt bufrede kWh-avlesninger samplet rundt UTC-halvtimer, noe som gjør det enklere å analysere nylig energibruk uten å være avhengig av historikk kun i skyen.

Dette er spesielt nyttig for solcelleovervåking, overvåking av hjemmets energibruk og tilpassede arbeidsflyter for energistyring, der brukere ønsker å sammenligne import, eksport og fasebaserte energidata. IAMMETER er ikke bare en måler; formålet med å samle inn disse dataene er å hjelpe brukere med å optimalisere energibruken, øke egenforbruket av solenergi og redusere strømregningen.

Hva API-et for energihistorikk tilbyr

Det nye endepunktet er:

GET /api/energyhistory

Det returnerer energimålinger i kWh, samplet rundt disse UTC-halvtimene:

00:00
00:30
01:00
01:30
og så videre

Fastvaren lagrer opptil 96 poster, tilsvarende 48 timer med historikk i intervaller på 30 minutter. Postene lagres i RAM-minnet til Wi-Fi-modulen, så de går tapt når enheten starter på nytt.

Et typisk svar inneholder:

utc: modulens gjeldende UTC-tidsstempel
timeSynced: om modulen har gyldig UTC-tid
interval: samplingsintervallet, for tiden 1800 sekunder
count: antall tilgjengelige historikkposter
order: for tiden newest_first
unit: for tiden kWh
channels: kanalnavnene som svarer til hver verdi
Datas: historikkpostene for hver halvtime

Hvert element i Datas inneholder et UTC-tidsstempel og en matrise med kWh-verdier. Verdiene følger samme rekkefølge som matrisen channels.

Hvorfor kWh-historikk per halvtime er viktig

Energidata per halvtime er praktiske fordi de gir brukerne et kompakt, men meningsfullt bilde av energiatferden. I stedet for å lagre hvert eneste sanntidspunkt kan brukerne analysere akkumulerte import- og eksportverdier over faste tidsintervaller.

En bruker kan for eksempel bruke de lokale dataene til å:

gjennomgå nylig importert og eksportert energi uten å vente på rapporter fra skyen.
eksportere de siste 48 timenes kWh-avlesninger til en lokal database eller CSV-fil.
sammenligne eksportmønstre fra solceller med husstandens forbruk.
kontrollere om en automatiseringsstrategi endrer strømforbruket i bestemte perioder.
bygge et lokalt dashboard for nylig energihistorikk.

For bredere scenarier for solcelleovervåking, se IAMMETER Solar Energy Monitoring Solution. For overvåking av strømforbruk i boliger, se IAMMETER Home Energy Monitoring Solution.

Støttede kanaloppsett

Feltet channels forteller klienten hvordan verdiene i hver historikkpost skal tolkes. Ulike målerkonfigurasjoner returnerer ulike kanaloppsett.

Enfase

["imp", "exp"]

Splittfase

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

Trefase

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

Trefase med nettmåling aktivert

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

Siden kanalnavnene returneres i svaret, bør tilpasset programvare først lese matrisen channels og deretter tilordne hver verdi i Datas[].values i samsvar med denne rekkefølgen.

Eksempler på originale API-svar

De følgende to eksemplene viser de originale API-returverdiene for et tomt svar og for et svar med data.

Eksempel på tomt svar

Etter at enheten har startet, kan historikkmatrisen være tom inntil det finnes gyldig UTC-tid og gyldige målerrammer. I så fall kan API-et returnere count: 0 og en tom Datas-matrise.

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

Dette svaret er normalt etter oppstart. Et lokalt dashboard eller skript bør håndtere denne tilstanden og vente på nye halvtimessamples.

Eksempel på svar med data

Følgende eksempel viser to halvtimesposter fra en trefasemåler. Svaret er sortert fra nyeste til eldste.

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

I den nyeste posten er a_imp lik 11.337 kWh, a_exp er 11.201 kWh, og så videre. Betydningen av hver verdi defineres av matrisen channels.

Bruk av returverdiene i programvare

Eksemplene over er nok til å bygge enkel lokal analyselogikk. Nøkkelen er å lese channels først og deretter bruke denne rekkefølgen på hvert element i Datas.

Tilordning av `channels` til `values`

Når du bygger programvare rundt dette API-et, bør du unngå å hardkode posisjoner med mindre målerkonfigurasjonen er fast. En tryggere tilnærming er å konvertere kanallisten og verdimatrisen til et navngitt objekt.

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

For eksempelet med trefasesvaret over vil latestByChannel inneholde:

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

Dette gjør dataene enklere å lagre, vise eller eksportere til et lokalt analyseverktøy.

Beregning av en kWh-endring per halvtime

Hvis du bruker de returnerte kWh-verdiene som akkumulerte energimålinger, kan endringen mellom to tilstøtende poster beregnes ved å trekke den eldre verdien fra den nyere verdien for samme kanal.

Med trefaseeksempelet over:

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

Denne typen beregning kan hjelpe brukere med å bygge en rapport over nylig import/eksport, sammenligne fasebaserte energiendringer eller kontrollere hvor mye energi som ble importert eller eksportert i et bestemt halvtimesintervall.

Viktig samplingsatferd

Energihistorikken genereres lokalt av Wi-Fi-modulen. Samplingsatferden er viktig når du bygger integrasjoner eller analyseverktøy:

Sampling drives av gyldige UART-målerrammer.
Modulen lagrer samplen som ligger nærmest hver halvtimes-UTC-grense.
UTC-tiden må være gyldig før historikkposter lagres.
Hvis timeSynced er 0, registreres ingen nye historikksamples.
Etter oppstart kan Datas være tom inntil nok gyldige samples er samlet inn.
Lagringen er for tiden RAM-basert, så API-et er ment for nylig lokal historikk, ikke for langtidslagring.

Dette gjør API-et egnet for lokal polling, kortsiktig analyse og integrasjonstesting. For langsiktige energirapporter bør brukere fortsatt ha en vedvarende datakilde, for eksempel IAMMETER-data i skyen eller sin egen database.

Idéer til eksempelintegrasjoner

Utviklere og avanserte brukere kan bruke /api/energyhistory som en enkel lokal datakilde for nylig kWh-historikk.

En vanlig tilnærming er å polle endepunktet med jevne mellomrom, lese listen channels og lagre nye Datas-poster i en lokal database. Dette kan støtte lokale dashboards, tilpassede rapporter eller skript for offline analyse.

Et annet nyttig scenario er analyse av egenforbruk av solenergi. Ved å sammenligne importerte og eksporterte kWh-verdier over halvtimesslots kan brukere bedre forstå når husstandens laster forbruker solcelleproduksjonen lokalt, og når overskuddsenergi eksporteres. Dette kan støtte bedre automatiseringsbeslutninger, for eksempel å flytte fleksible laster til perioder med høyere solproduksjon.

Hvis du bygger lokale integrasjoner, se også Local API, Modbus/TCP and MQTT og IAMMETER Local API Explorer.

Hvordan dette passer inn i energistyringen

Verdien av et API for energihistorikk ligger ikke bare i at det eksponerer flere data. Det sentrale er hva brukerne kan gjøre med disse dataene.

Med kWh-historikk per halvtime kan brukere analysere nylig import og eksport av strøm, identifisere bruksmønstre og vurdere om strategier for solceller eller laststyring faktisk hjelper. Dette støtter IAMMETERs overordnede mål: å gjøre data fra energiovervåking om til praktiske beslutninger som forbedrer energieffektiviteten og reduserer strømregningen.

For brukere som kombinerer IAMMETER med automatiseringsplattformer, kan lokal energihistorikk også gi et praktisk datalag for testing og validering av styrelogikk. Home Assistant-brukere som optimaliserer utnyttelsen av solcelleoverskudd, kan for eksempel gjennomgå nylige kWh-endringer sammen med automatiseringens atferd. Se Home Assistant Solar Energy Automation with IAMMETER for et beslektet brukstilfelle.

FAQ

Kan dette API-et erstatte langsiktig energihistorikk?

Nei. API-et lagrer opptil 96 poster, eller 48 timer med halvtimedata, i RAM. Det er utviklet for nylig lokal historikk. Dataene går tapt etter omstart.

Hvorfor er `Datas` tom etter oppstart?

Etter oppstart trenger modulen gyldig UTC-tid og gyldige målerrammer før historikksamples kan registreres. Inntil nok gyldige samples er samlet inn, kan API-et returnere en tom Datas-matrise.

Er tidsstemplene basert på lokal tid?

Nei. Samplingsslottene er justert mot UTC-halvtimer.

Hvordan bør programvare tolke verdimatrisen?

Les alltid feltet channels først. Verdiene i hver Datas[].values-matrise følger samme rekkefølge som kanalnavnene.