Lokalni API za zgodovino energije za odčitke kWh

title: Lokalni API za zgodovino energije za odčitke kWh

abstract: Berite polurno zgodovino kWh lokalno za analizo brez povezave.

language: sl

author: Jessica

Uvod

Za uporabnike, ki gradijo lastne nadzorne plošče, avtomatizacije ali orodja za analizo brez povezave, so resnični podatki o energiji bolj uporabni, kadar so na voljo v stabilnem intervalu. Posamezen odčitek moči v realnem času lahko pokaže, kaj se dogaja zdaj, toda polurna zgodovina kWh pomaga uporabnikom razumeti, kako se uvoz in izvoz električne energije spreminjata skozi čas.

Od različice vdelane programske opreme i.91.063TS8.bin, izdane 2. junija 2026, IAMMETER podpira nov lokalni API: GET /api/energyhistory. Ta API vrača lokalno predpomnjene odčitke kWh, vzorčene okoli polurnih meja UTC, kar olajša analizo nedavne porabe energije, ne da bi se zanašali zgolj na zgodovino v oblaku.

To je še posebej uporabno pri spremljanju sončne energije, spremljanju energije v gospodinjstvu in delovnih tokovih upravljanja energije po meri, kjer uporabniki želijo primerjati uvoz, izvoz in energijo na ravni faz. IAMMETER ni le merilnik; namen zbiranja teh podatkov je pomagati uporabnikom optimizirati porabo energije, izboljšati lastno porabo sončne energije in znižati račune za elektriko.

Kaj ponuja API za zgodovino energije

Nova končna točka je:

GET /api/energyhistory

Vrača odčitke energije v kWh, vzorčene okoli teh polurnih meja UTC:

00:00
00:30
01:00
01:30
in tako naprej

Vdelana programska oprema hrani do 96 zapisov, kar ustreza 48 uram zgodovine v 30-minutnih intervalih. Zapisi so shranjeni v RAM-u modula Wi-Fi, zato se po ponovnem zagonu naprave izgubijo.

Tipičen odgovor vključuje:

utc: trenutni časovni žig UTC modula
timeSynced: ali ima modul veljaven čas UTC
interval: interval vzorčenja, trenutno 1800 sekund
count: število razpoložljivih zapisov zgodovine
order: trenutno newest_first
unit: trenutno kWh
channels: imena kanalov, ki ustrezajo vsaki vrednosti
Datas: polurni zapisi zgodovine

Vsak element v Datas vključuje časovni žig UTC in matriko vrednosti kWh. Vrednosti sledijo enakemu vrstnemu redu kot matrika channels.

Zakaj je polurna zgodovina kWh pomembna

Polurni podatki o energiji so praktični, ker uporabnikom dajejo jedrnat, a smiseln pogled na vedenje porabe energije. Namesto shranjevanja vsake točke v realnem času lahko uporabniki analizirajo zbrane vrednosti uvoza in izvoza v fiksnih časovnih oknih.

Uporabnik lahko na primer lokalne podatke uporabi za:

Pregled nedavno uvožene in izvožene energije, ne da bi čakal na poročila iz oblaka.
Izvoz zadnjih 48 ur odčitkov kWh v lokalno bazo podatkov ali datoteko CSV.
Primerjavo vzorcev izvoza sončne energije s porabo gospodinjstva.
Preverjanje, ali strategija avtomatizacije spremeni porabo električne energije v določenih obdobjih.
Izgradnjo lokalne nadzorne plošče za nedavno zgodovino energije.

Za širše scenarije spremljanja sončne energije glejte IAMMETER Solar Energy Monitoring Solution. Za spremljanje porabe električne energije v gospodinjstvu glejte IAMMETER Home Energy Monitoring Solution.

Podprte razporeditve kanalov

Polje channels pove odjemalcu, kako naj interpretira vrednosti v vsakem zapisu zgodovine. Različne konfiguracije merilnika vračajo različne razporeditve kanalov.

Enofazni

["imp", "exp"]

Razdeljena faza

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

Trifazni

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

Trifazni z omogočenim neto merjenjem

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

Ker se imena kanalov vrnejo v odgovoru, mora programska oprema po meri najprej prebrati matriko channels in nato ustrezno preslikati vsako vrednost v Datas[].values.

Primeri izvirnih odgovorov API

Naslednja dva primera prikazujeta izvirne vrednosti odgovorov API za prazen odgovor in za odgovor s podatki.

Primer praznega odgovora

Po zagonu naprave je matrika zgodovine lahko prazna, dokler nista na voljo veljaven čas UTC in veljavni okviri merilnika. V tem primeru lahko API vrne count: 0 in prazno matriko 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": []
}

Ta odgovor je po zagonu običajen. Lokalna nadzorna plošča ali skript naj obravnava to stanje in počaka na nove polurne vzorce.

Primer odgovora s podatki

Naslednji primer prikazuje dva polurna zapisa s trifaznega merilnika. Odgovor je razvrščen od najnovejšega do najstarejšega.

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

V najnovejšem zapisu je a_imp 11.337 kWh, a_exp je 11.201 kWh in tako naprej. Pomen vsake vrednosti določa matrika channels.

Uporaba vrnjenih vrednosti v programski opremi

Zgornji primeri izvirnih odgovorov zadostujejo za izgradnjo preproste lokalne logike analize. Ključno je, da najprej preberete channels in nato ta vrstni red uporabite za vsak element v Datas.

Preslikava `channels` v `values`

Pri razvoju programske opreme okoli tega API se izogibajte trdemu kodiranju položajev, razen če je konfiguracija merilnika nespremenljiva. Varnejši pristop je pretvoriti seznam kanalov in matriko vrednosti v poimenovan 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);

Za zgornji vzorčni trifazni odgovor bi latestByChannel vseboval:

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

Tako je podatke lažje shranjevati, prikazovati ali izvažati v lokalno orodje za analizo.

Izračun polurne spremembe kWh

Če vrnjene vrednosti kWh uporabljate kot zbrane odčitke energije, lahko spremembo med dvema sosednjima zapisoma izračunate tako, da za isti kanal od novejše vrednosti odštejete starejšo.

Z uporabo zgornjega trifaznega primera:

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

Tovrstni izračun lahko uporabnikom pomaga zgraditi poročilo o nedavnem uvozu in izvozu, primerjati spremembe energije na ravni faz ali preveriti, koliko energije je bilo uvožene ali izvožene v določenem polurnem oknu.

Pomembno vedenje vzorčenja

Zgodovino energije lokalno ustvari modul Wi-Fi. Vedenje vzorčenja je pomembno pri gradnji integracij ali orodij za analizo:

Vzorčenje poganjajo veljavni okviri merilnika prek UART.
Modul shrani vzorec, ki je najbližji vsaki polurni meji UTC.
Čas UTC mora biti veljaven, preden se zapisi zgodovine shranijo.
Če je timeSynced enak 0, se novi vzorci zgodovine ne beležijo.
Po zagonu je Datas lahko prazen, dokler ni zajetih dovolj veljavnih vzorcev.
Trenutna shramba temelji na RAM-u, zato je API namenjen nedavni lokalni zgodovini in ne dolgoročnemu shranjevanju.

Zato je API primeren za lokalno periodično poizvedovanje, kratkoročno analizo in testiranje integracij. Za dolgoročna poročila o energiji naj uporabniki še vedno ohranijo trajni vir podatkov, na primer podatke v oblaku IAMMETER ali lastno bazo podatkov.

Primeri idej za integracijo

Razvijalci in napredni uporabniki lahko uporabijo /api/energyhistory kot preprost lokalni vir podatkov za nedavno zgodovino kWh.

Pogost pristop je periodično poizvedovanje po končni točki, branje seznama channels in shranjevanje novih zapisov Datas v lokalno bazo podatkov. To lahko podpira lokalne nadzorne plošče, poročila po meri ali skripte za analizo brez povezave.

Drug uporaben scenarij je analiza lastne porabe sončne energije. S primerjavo uvoženih in izvoženih vrednosti kWh po polurnih oknih lahko uporabniki bolje razumejo, kdaj gospodinjski porabniki sončno proizvodnjo porabijo lokalno in kdaj se presežek energije izvozi. To lahko podpira boljše odločitve o avtomatizaciji, na primer premikanje prilagodljivih bremen v obdobja z večjo sončno proizvodnjo.

Če gradite lokalne integracije, glejte tudi Local API, Modbus/TCP and MQTT in IAMMETER Local API Explorer.

Kako se to vklaplja v upravljanje energije

Vrednost API-ja za zgodovino energije ni le v tem, da razkrije več podatkov. Ključno je, kaj lahko uporabniki s temi podatki naredijo.

S polurno zgodovino kWh lahko uporabniki analizirajo nedavni uvoz in izvoz električne energije, prepoznajo vzorce porabe in ocenijo, ali strategije sončne energije ali nadzora bremen dejansko pomagajo. To podpira širši cilj IAMMETER: pretvoriti podatke o spremljanju energije v praktične odločitve, ki izboljšajo energetsko učinkovitost in znižajo račune za elektriko.

Za uporabnike, ki IAMMETER kombinirate s platformami za avtomatizacijo, lahko lokalna zgodovina energije zagotovi tudi priročno podatkovno plast za testiranje in preverjanje krmilne logike. Uporabniki sistema Home Assistant, ki optimizirajo izkoriščanje presežka sončne energije, lahko na primer pregledajo nedavne spremembe kWh skupaj z vedenjem avtomatizacije. Glejte Home Assistant Solar Energy Automation with IAMMETER za povezan primer uporabe.

Pogosta vprašanja

Ali lahko ta API nadomesti dolgoročno zgodovino energije?

Ne. API shrani do 96 zapisov oziroma 48 ur polurnih podatkov v RAM-u. Namenjen je nedavni lokalni zgodovini. Podatki se po ponovnem zagonu izgubijo.

Zakaj je `Datas` po zagonu prazen?

Po zagonu modul potrebuje veljaven čas UTC in veljavne okvire merilnika, preden je mogoče zabeležiti vzorce zgodovine. Dokler ni zajetih dovolj veljavnih vzorcev, lahko API vrne prazno matriko Datas.

Ali časovni žigi temeljijo na lokalnem času?

Ne. Vzorčna okna so poravnana s polurnimi mejami UTC.

Kako naj programska oprema interpretira matriko vrednosti?

Vedno najprej preberite polje channels. Vrednosti v vsaki matriki Datas[].values sledijo enakemu vrstnemu redu kot imena kanalov.