Lokalt API för energihistorik för kWh-värden

title: Lokalt API för energihistorik för kWh-värden

abstract: Läs halvtimmesvis kWh-historik lokalt för offlineanalys.

language: sv

author: Jessica

Inledning

För användare som bygger egna dashboards, automatiseringar eller verktyg för offlineanalys är verkliga energidata mer användbara när de finns tillgängliga med ett stabilt intervall. En enskild effektavläsning i realtid kan visa vad som händer just nu, men en halvtimmesvis kWh-historik hjälper användare att förstå hur import och export av el förändras över tid.

Från och med firmwareversionen i.91.063TS8.bin, som släpptes den 2 juni 2026, stöder IAMMETER ett nytt lokalt API: GET /api/energyhistory. Detta API returnerar lokalt cachelagrade kWh-avläsningar som samplas kring halvtimmesgränser i UTC, vilket gör det enklare att analysera den senaste tidens energianvändning utan att enbart förlita sig på historiken i molnet.

Detta är särskilt användbart för solcellsövervakning, övervakning av hushållens energianvändning och anpassade arbetsflöden för energihantering, där användare vill jämföra import, export och energidata per fas. IAMMETER är inte bara en mätare; syftet med att samla in dessa data är att hjälpa användare att optimera sin energianvändning, öka egenanvändningen av solenergi och sänka elräkningarna.

Vad API:t för energihistorik tillhandahåller

Den nya slutpunkten är:

GET /api/energyhistory

Den returnerar energivärden i kWh, samplade kring följande halvtimmesgränser i UTC:

00:00
00:30
01:00
01:30
och så vidare

Firmwaren behåller upp till 96 poster, vilket motsvarar 48 timmars historik med 30-minutersintervall. Posterna lagras i RAM-minnet i Wi-Fi-modulen, så de försvinner när enheten startas om.

Ett typiskt svar innehåller:

utc: modulens aktuella UTC-tidsstämpel
timeSynced: om modulen har en giltig UTC-tid
interval: samplingsintervallet, för närvarande 1800 sekunder
count: antalet tillgängliga historikposter
order: för närvarande newest_first
unit: för närvarande kWh
channels: kanalnamnen som motsvarar varje värde
Datas: historikposterna per halvtimme

Varje post i Datas innehåller en UTC-tidsstämpel och en array med kWh-värden. Värdena följer samma ordning som arrayen channels.

Varför halvtimmesvis kWh-historik är viktig

Halvtimmesvisa energidata är praktiska eftersom de ger användarna en kompakt men meningsfull bild av energianvändningen. I stället för att lagra varje realtidspunkt kan användarna analysera ackumulerade import- och exportvärden över fasta tidsperioder.

En användare kan till exempel använda de lokala data för att:

Granska nyligen importerad och exporterad energi utan att vänta på rapporter från molnet.
Exportera de senaste 48 timmarnas kWh-avläsningar till en lokal databas eller CSV-fil.
Jämföra mönster för export av solel med hushållets förbrukning.
Kontrollera om en automatiseringsstrategi förändrar elanvändningen under vissa perioder.
Bygga en lokal dashboard för den senaste tidens energihistorik.

För bredare scenarier inom solcellsövervakning, se IAMMETERs lösning för övervakning av solenergi. För övervakning av el i bostäder, se IAMMETERs lösning för övervakning av hushållsenergi.

Kanalformat som stöds

Fältet channels talar om för klienten hur värdena i varje historikpost ska tolkas. Olika mätarkonfigurationer returnerar olika kanalformat.

Enfas

["imp", "exp"]

Delad fas

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

Trefas

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

Trefas med nettomätning aktiverad

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

Eftersom kanalnamnen returneras i svaret bör egen programvara först läsa arrayen channels och sedan mappa varje värde i Datas[].values i enlighet med den.

Exempel på API-svar i original

Följande två exempel visar de ursprungliga API-svarsvärdena för ett tomt svar och ett svar med data.

Exempel på tomt svar

Efter att enheten har startat kan historikarrayen vara tom tills en giltig UTC-tid och giltiga mätarramar finns tillgängliga. I så fall kan API:t returnera count: 0 och en tom 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": []
}

Detta svar är normalt efter en omstart. En lokal dashboard eller ett skript bör hantera detta tillstånd och vänta på nya halvtimmesprover.

Exempel på svar med data

Följande exempel visar två halvtimmesposter från en trefasmätare. Svaret är sorterat från nyast till äldst.

{
  "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 nyaste posten är a_imp 11.337 kWh, a_exp 11.201 kWh och så vidare. Betydelsen av varje värde definieras av arrayen channels.

Använda returvärdena i programvara

Exemplen på returvärden ovan räcker för att bygga enkel lokal analyslogik. Det viktiga är att först läsa channels och sedan tillämpa den ordningen på varje post i Datas.

Mappa `channels` till `values`

När du bygger programvara kring detta API bör du undvika att hårdkoda positioner, om inte mätarkonfigurationen är fast. Ett säkrare tillvägagångssätt är att omvandla kanallistan och värdearrayen till ett namngivet 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);

För exemplet med trefassvaret ovan skulle latestByChannel innehålla:

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

Detta gör data enklare att lagra, visa eller exportera till ett lokalt analysverktyg.

Beräkna förändringen i kWh över en halvtimme

Om du använder de returnerade kWh-värdena som ackumulerade energivärden kan förändringen mellan två intilliggande poster beräknas genom att subtrahera det äldre värdet från det nyare värdet för samma kanal.

Med trefasexemplet ovan:

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

Den här typen av beräkning kan hjälpa användare att skapa en rapport över den senaste tidens import och export, jämföra energiförändringar per fas eller kontrollera hur mycket energi som importerades eller exporterades under en viss halvtimme.

Viktigt om samplingsbeteendet

Energihistoriken genereras lokalt av Wi-Fi-modulen. Samplingsbeteendet är viktigt när du bygger integrationer eller analysverktyg:

Samplingen styrs av giltiga mätarramar över UART.
Modulen lagrar det prov som ligger närmast varje halvtimmesgräns i UTC.
UTC-tiden måste vara giltig innan historikposter lagras.
Om timeSynced är 0 registreras inga nya historikprover.
Efter en omstart kan Datas vara tom tills tillräckligt många giltiga prover har samlats in.
Lagringen sker för närvarande i RAM, så API:t är avsett för den senaste lokala historiken, inte för långtidslagring.

Detta gör API:t lämpligt för lokal avfrågning, kortsiktig analys och integrationstestning. För långsiktiga energirapporter bör användarna fortfarande ha en beständig datakälla, till exempel IAMMETERs molndata eller en egen databas.

Exempel på integrationsidéer

Utvecklare och avancerade användare kan använda /api/energyhistory som en enkel lokal datakälla för den senaste kWh-historiken.

Ett vanligt tillvägagångssätt är att regelbundet anropa slutpunkten, läsa listan channels och spara nya poster i Datas till en lokal databas. Detta kan stödja lokala dashboards, anpassade rapporter eller skript för offlineanalys.

Ett annat användbart scenario är analys av egenanvändning av solenergi. Genom att jämföra importerade och exporterade kWh-värden över halvtimmesintervall kan användare bättre förstå när hushållets laster förbrukar solenergin lokalt och när överskottsenergi exporteras. Detta kan ge bättre automatiseringsbeslut, till exempel att flytta flexibla laster till perioder med högre solproduktion.

Om du bygger lokala integrationer, se även Lokalt API, Modbus/TCP och MQTT och IAMMETER Local API Explorer.

Hur detta passar in i energihanteringen

Värdet av ett API för energihistorik ligger inte bara i att det exponerar mer data. Det viktiga är vad användarna kan göra med dessa data.

Med halvtimmesvis kWh-historik kan användare analysera den senaste tidens import och export av el, identifiera användningsmönster och utvärdera om strategier för solenergi eller laststyrning faktiskt hjälper. Detta stöder IAMMETERs övergripande mål: att omvandla data från energimätning till praktiska beslut som förbättrar energieffektiviteten och sänker elräkningarna.

För användare som kombinerar IAMMETER med automatiseringsplattformar kan lokal energihistorik också utgöra ett bekvämt datalager för att testa och validera styrlogik. Home Assistant-användare som optimerar användningen av solelöverskott kan till exempel granska de senaste kWh-förändringarna tillsammans med automatiseringens beteende. Se Automatisering av solenergi i Home Assistant med IAMMETER för ett närliggande användningsfall.

Vanliga frågor

Kan detta API ersätta långsiktig energihistorik?

Nej. API:t lagrar upp till 96 poster, eller 48 timmars halvtimmesdata, i RAM. Det är utformat för den senaste lokala historiken. Data försvinner vid en omstart.

Varför är `Datas` tom efter en omstart?

Efter en omstart behöver modulen en giltig UTC-tid och giltiga mätarramar innan historikprover kan registreras. Tills tillräckligt många giltiga prover har fångats kan API:t returnera en tom array Datas.

Är tidsstämplarna baserade på lokal tid?

Nej. Samplingsintervallen är anpassade till halvtimmesgränser i UTC.

Hur bör programvara tolka värdearrayen?

Läs alltid fältet channels först. Värdena i varje array Datas[].values följer samma ordning som kanalnamnen.