Lokalt energi-historik-API til kWh-aflæsninger

title: Lokalt energi-historik-API til kWh-aflæsninger

abstract: Læs halvtimes-kWh-historik lokalt til offline-analyse.

language: da

author: Jessica

Introduktion

For brugere, der bygger deres egne dashboards, automatiseringer eller offline-analyseværktøjer, er rigtige energidata mere nyttige, når de er tilgængelige med et stabilt interval. En enkelt effektaflæsning i realtid kan vise, hvad der sker lige nu, men halvtimes-kWh-historik hjælper brugere med at forstå, hvordan el-import og -eksport ændrer sig over tid.

Fra firmwareversion i.91.063TS8.bin, udgivet den 2. juni 2026, understøtter IAMMETER et nyt lokalt API: GET /api/energyhistory. Dette API returnerer lokalt cachede kWh-aflæsninger samplet omkring UTC-halvtimer, hvilket gør det nemmere at analysere det seneste energiforbrug uden kun at være afhængig af historikken i skyen.

Det er især nyttigt til overvågning af solceller, overvågning af husstandens energiforbrug og tilpassede arbejdsgange for energistyring, hvor brugere ønsker at sammenligne import, eksport og fasebaserede energidata. IAMMETER er ikke kun en måler; formålet med at indsamle disse data er at hjælpe brugere med at optimere energiforbruget, forbedre egenforbruget af solenergi og reducere elregningen.

Hvad energi-historik-API'et tilbyder

Det nye endpoint er:

GET /api/energyhistory

Det returnerer energilæsninger i kWh, samplet omkring disse UTC-halvtimer:

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

Firmwaren gemmer op til 96 poster, svarende til 48 timers historik med 30-minutters intervaller. Poster gemmes i Wi-Fi-modulets RAM, så de går tabt, når enheden genstarter.

Et typisk svar indeholder:

utc: modulets aktuelle UTC-tidsstempel
timeSynced: om modulet har et gyldigt UTC-tidspunkt
interval: samplingsintervallet, i øjeblikket 1800 sekunder
count: antallet af tilgængelige historikposter
order: i øjeblikket newest_first
unit: i øjeblikket kWh
channels: kanalnavnene, der svarer til hver værdi
Datas: halvtimers-historikposterne

Hvert element i Datas indeholder et UTC-tidsstempel og et array af kWh-værdier. Værdierne følger samme rækkefølge som arrayet channels.

Hvorfor halvtimes-kWh-historik er vigtig

Halvtimes-energidata er praktiske, fordi de giver brugerne et kompakt, men meningsfuldt billede af energiadfærden. I stedet for at gemme hvert realtidspunkt kan brugerne analysere akkumulerede import- og eksportværdier over faste tidsrum.

En bruger kan for eksempel bruge de lokale data til at:

gennemgå den seneste importerede og eksporterede energi uden at vente på rapporter fra skyen.
eksportere de seneste 48 timers kWh-aflæsninger til en lokal database eller CSV-fil.
sammenligne solcelleeksportmønstre med husstandens forbrug.
kontrollere, om en automatiseringsstrategi ændrer elforbruget i bestemte perioder.
bygge et lokalt dashboard til den seneste energihistorik.

For bredere scenarier med overvågning af solceller, se IAMMETER Solar Energy Monitoring Solution. For overvågning af elforbrug i boliger, se IAMMETER Home Energy Monitoring Solution.

Understøttede kanalopsætninger

Feltet channels fortæller klienten, hvordan værdierne i hver historikpost skal fortolkes. Forskellige målerkonfigurationer returnerer forskellige kanalopsætninger.

Enkeltfaset

["imp", "exp"]

Splitfaset

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

Trefaset

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

Trefaset med nettomåling aktiveret

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

Da kanalnavnene returneres i svaret, bør tilpasset software først læse arrayet channels og derefter tilknytte hver værdi i Datas[].values i overensstemmelse hermed.

Eksempler på originale API-svar

De følgende to eksempler viser de originale API-returværdier for et tomt svar og for et svar med data.

Eksempel på tomt svar

Efter at enheden er startet, kan historik-arrayet være tomt, indtil der er et gyldigt UTC-tidspunkt og gyldige målerrammer. I det tilfælde kan API'et returnere count: 0 og et tomt array Datas.

{
  "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 svar er normalt efter opstart. Et lokalt dashboard eller script bør håndtere denne tilstand og vente på nye halvtimessamples.

Eksempel på svar med data

Følgende eksempel viser to halvtimersposter fra en trefaset måler. Svaret er ordnet fra nyeste til ældste.

{
  "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 post er a_imp lig med 11.337 kWh, a_exp er 11.201 kWh og så videre. Betydningen af hver værdi defineres af arrayet channels.

Brug af returværdierne i software

Eksemplerne ovenfor er nok til at bygge simpel lokal analyselogik. Nøglen er først at læse channels og derefter anvende denne rækkefølge på hvert element i Datas.

Kortlægning af `channels` til `values`

Når du bygger software omkring dette API, bør du undgå at hardcode positioner, medmindre målerkonfigurationen er fast. En sikrere tilgang er at konvertere kanallisten og værdiarrayet til et navngivet 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 det viste eksempel på et trefaset svar vil latestByChannel indeholde:

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

Det gør dataene nemmere at gemme, vise eller eksportere til et lokalt analyseværktøj.

Beregning af en halvtimes kWh-ændring

Hvis du bruger de returnerede kWh-værdier som akkumulerede energilæsninger, kan ændringen mellem to tilstødende poster beregnes ved at trække den ældre værdi fra den nyere værdi for samme kanal.

Med trefaseeksemplet ovenfor:

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 form for beregning kan hjælpe brugere med at bygge en rapport over den seneste import/eksport, sammenligne fasebaserede energiændringer eller kontrollere, hvor meget energi der blev importeret eller eksporteret i et bestemt halvtimesinterval.

Vigtig sampling-adfærd

Energihistorikken genereres lokalt af Wi-Fi-modulet. Sampling-adfærden er vigtig, når du bygger integrationer eller analyseværktøjer:

Sampling drives af gyldige UART-målerrammer.
Modulet gemmer den sample, der ligger tættest på hver halvtimes-UTC-grænse.
UTC-tiden skal være gyldig, før historikposter gemmes.
Hvis timeSynced er 0, registreres der ingen nye historiksamples.
Efter opstart kan Datas være tom, indtil der er opsamlet nok gyldige samples.
Den nuværende lagring er RAM-baseret, så API'et er beregnet til nylig lokal historik, ikke til langtidslagring.

Det gør API'et velegnet til lokal polling, korttidsanalyse og integrationstest. Til langsigtede energi-rapporter bør brugere stadig have en vedvarende datakilde, f.eks. IAMMETER-clouddata eller deres egen database.

Idéer til eksempelintegrationer

Udviklere og avancerede brugere kan bruge /api/energyhistory som en simpel lokal datakilde til nylig kWh-historik.

En almindelig tilgang er at polle endpointet med jævne mellemrum, læse listen channels og gemme nye Datas-poster i en lokal database. Det kan understøtte lokale dashboards, tilpassede rapporter eller offline-analysescripts.

Et andet nyttigt scenarie er analyse af egenforbruget af solenergi. Ved at sammenligne importerede og eksporterede kWh-værdier over halvtimesslots kan brugere bedre forstå, hvornår husstandens belastninger forbruger solcelleproduktionen lokalt, og hvornår overskudsenergi eksporteres. Det kan understøtte bedre automatiseringsbeslutninger, f.eks. at flytte fleksible belastninger til perioder med højere solproduktion.

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

Hvordan dette passer ind i energistyringen

Værdien af et energi-historik-API er ikke kun, at det eksponerer flere data. Det centrale er, hvad brugerne kan gøre med disse data.

Med halvtimes-kWh-historik kan brugere analysere den seneste el-import og -eksport, identificere forbrugsmønstre og vurdere, om strategier for solceller eller laststyring faktisk hjælper. Det understøtter IAMMETERs overordnede mål: at omsætte data fra energiovervågning til praktiske beslutninger, der forbedrer energieffektiviteten og reducerer elregningen.

For brugere, der kombinerer IAMMETER med automatiseringsplatforme, kan lokal energihistorik også give et bekvemt datalag til test og validering af styrelogik. Home Assistant-brugere, der optimerer udnyttelsen af solcelleoverskud, kan for eksempel gennemgå de seneste kWh-ændringer sammen med automatiseringens adfærd. Se Home Assistant Solar Energy Automation with IAMMETER for et beslægtet anvendelseseksempel.

FAQ

Kan dette API erstatte langsigtet energihistorik?

Nej. API'et gemmer op til 96 poster, eller 48 timers halvtimedata, i RAM. Det er designet til nylig lokal historik. Dataene går tabt efter en genstart.

Hvorfor er `Datas` tom efter opstart?

Efter opstart har modulet brug for et gyldigt UTC-tidspunkt og gyldige målerrammer, før historiksamples kan registreres. Indtil der er opsamlet nok gyldige samples, kan API'et returnere et tomt array Datas.

Er tidsstemplerne baseret på lokal tid?

Nej. Samplingsslots er justeret efter UTC-halvtimer.

Hvordan bør software fortolke værdiarrayet?

Læs altid feltet channels først. Værdierne i hvert array Datas[].values følger samme rækkefølge som kanalnavnene.