Paikallinen energian historian API kWh-lukemille

title: Paikallinen energian historian API kWh-lukemille

abstract: Lue puolen tunnin kWh-historia paikallisesti offline-analyysia varten.

language: fi

author: Jessica

Johdanto

Käyttäjille, jotka rakentavat omia hallintapaneelejaan, automaatioitaan tai offline-analyysityökalujaan, todellinen energiantuotantotieto on hyödyllisempää, kun se on saatavilla vakaalla aikavälillä. Yksi reaaliaikainen teholukema näyttää, mitä tapahtuu juuri nyt, mutta puolen tunnin kWh-historia auttaa käyttäjiä ymmärtämään, miten sähkön osto ja myynti muuttuvat ajan myötä.

Laiteohjelmistoversiosta i.91.063TS8.bin alkaen, joka julkaistiin 2. kesäkuuta 2026, IAMMETER tukee uutta paikallista rajapintaa: GET /api/energyhistory. Tämä rajapinta palauttaa paikallisesti välimuistiin tallennettuja kWh-lukemia, jotka on näytteistetty UTC-ajan puolen tunnin rajojen ympäriltä. Näin viimeaikaisen energiankulutuksen analysointi on helpompaa ilman, että tukeudutaan pelkästään pilvipuolen historiaan.

Tämä on erityisen hyödyllistä aurinkosähkön seurannassa, kodin energianseurannassa ja mukautetuissa energianhallinnan työnkuluissa, joissa käyttäjät haluavat verrata oston, myynnin ja vaihekohtaisen energian tietoja. IAMMETER ei ole vain mittari; näiden tietojen keräämisen tarkoitus on auttaa käyttäjiä optimoimaan energiankäyttöä, parantamaan aurinkosähkön omakäyttöä ja pienentämään sähkölaskuja.

Mitä energian historian rajapinta tarjoaa

Uusi päätepiste on:

GET /api/energyhistory

Se palauttaa energialukemat yksikössä kWh näytteistettyinä näiden UTC-ajan puolen tunnin rajojen ympäriltä:

00:00
00:30
01:00
01:30
ja niin edelleen

Laiteohjelmisto säilyttää enintään 96 tietuetta, mikä vastaa 48 tuntia historiaa 30 minuutin välein. Tietueet tallennetaan Wi-Fi-moduulin RAM-muistiin, joten ne menetetään laitteen uudelleenkäynnistyksen jälkeen.

Tyypillinen vastaus sisältää:

utc: moduulin nykyinen UTC-aikaleima
timeSynced: onko moduulilla kelvollinen UTC-aika
interval: näytteenottoväli, tällä hetkellä 1800 sekuntia
count: käytettävissä olevien historiatietueiden määrä
order: tällä hetkellä newest_first
unit: tällä hetkellä kWh
channels: kanavien nimet, jotka vastaavat kutakin arvoa
Datas: puolen tunnin historiatietueet

Jokainen Datas-taulukon alkio sisältää UTC-aikaleiman ja taulukon kWh-arvoja. Arvot noudattavat samaa järjestystä kuin channels-taulukko.

Miksi puolen tunnin kWh-historia on tärkeää

Puolen tunnin energiatiedot ovat käytännöllisiä, koska ne antavat käyttäjille tiiviin mutta merkityksellisen kuvan energiankäytöstä. Sen sijaan että tallennettaisiin jokainen reaaliaikainen mittapiste, käyttäjät voivat analysoida kertyneitä oston ja myynnin arvoja kiinteillä aikaväleillä.

Esimerkiksi käyttäjä voi hyödyntää paikallisia tietoja seuraaviin:

Tarkastele viimeaikaista ostettua ja myytyä energiaa odottamatta pilviraportteja.
Vie viimeisimmät 48 tunnin kWh-lukemat paikalliseen tietokantaan tai CSV-tiedostoon.
Vertaa aurinkosähkön myyntikuvioita kotitalouden kulutukseen.
Tarkista, muuttaako automaatiostrategia sähkönkäyttöä tietyillä jaksoilla.
Rakenna paikallinen hallintapaneeli viimeaikaiselle energian historialle.

Laajemmista aurinkosähkön seurantaskenaarioista katso IAMMETER Solar Energy Monitoring Solution. Kotitalouksien sähkönseurannasta katso IAMMETER Home Energy Monitoring Solution.

Tuetut kanavarakenteet

channels-kenttä kertoo asiakasohjelmalle, miten kunkin historiatietueen arvot tulkitaan. Erilaiset mittarikokoonpanot palauttavat erilaisia kanavarakenteita.

Yksivaiheinen

["imp", "exp"]

Kaksivaiheinen

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

Kolmivaiheinen

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

Kolmivaiheinen, netotus käytössä

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

Koska kanavien nimet palautetaan vastauksessa, mukautetun ohjelmiston tulisi lukea ensin channels-taulukko ja sen jälkeen yhdistää jokainen Datas[].values-taulukon arvo sen mukaisesti.

Alkuperäiset esimerkit rajapinnan paluuarvoista

Seuraavat kaksi esimerkkiä näyttävät rajapinnan alkuperäiset paluuarvot tyhjälle vastaukselle ja datavastaukselle.

Esimerkki tyhjästä vastauksesta

Kun laite on käynnistynyt, historialista voi olla tyhjä, kunnes kelvollinen UTC-aika ja kelvolliset mittarikehykset ovat saatavilla. Tässä tapauksessa rajapinta voi palauttaa arvon count: 0 ja tyhjän Datas-taulukon.

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

Tämä vastaus on normaali käynnistyksen jälkeen. Paikallisen hallintapaneelin tai skriptin tulisi käsitellä tämä tila ja odottaa uusia puolen tunnin näytteitä.

Esimerkki datavastauksesta

Seuraava esimerkki näyttää kaksi puolen tunnin tietuetta kolmivaihemittarilta. Vastaus on järjestetty uusimmasta vanhimpaan.

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

Uusimmassa tietueessa a_imp on 11.337 kWh, a_exp on 11.201 kWh ja niin edelleen. Kunkin arvon merkityksen määrittää channels-taulukko.

Paluuarvojen käyttäminen ohjelmistossa

Yllä olevat alkuperäiset paluuesimerkit riittävät yksinkertaisen paikallisen analyysilogiikan rakentamiseen. Olennaista on lukea ensin channels ja soveltaa tätä järjestystä jokaiseen Datas-taulukon alkioon.

Kanavien yhdistäminen arvoihin

Kun rakennat ohjelmistoa tämän rajapinnan ympärille, vältä sijaintien kovakoodausta, ellei mittarikokoonpano ole kiinteä. Turvallisempi tapa on muuntaa kanavaluettelo ja arvotaulukko nimetyksi olioksi.

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

Yllä olevassa kolmivaihemittarin esimerkkivastauksessa latestByChannel sisältäisi seuraavat:

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

Tämä helpottaa tietojen tallentamista, näyttämistä tai viemistä paikalliseen analyysityökaluun.

Puolen tunnin kWh-muutoksen laskeminen

Jos käytät palautettuja kWh-arvoja kertyneinä energialukemina, kahden vierekkäisen tietueen välinen muutos voidaan laskea vähentämällä vanhempi arvo uudemmasta arvosta saman kanavan osalta.

Käyttäen yllä olevaa kolmivaiheista esimerkkiä:

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

Tällainen laskenta voi auttaa käyttäjiä rakentamaan raportin viimeaikaisesta ostosta ja myynnistä, vertailemaan vaihekohtaisia energiamuutoksia tai tarkistamaan, kuinka paljon energiaa ostettiin tai myytiin tietyn puolen tunnin jakson aikana.

Tärkeää näytteenottokäyttäytymisestä

Energian historia muodostetaan paikallisesti Wi-Fi-moduulissa. Näytteenottokäyttäytyminen on tärkeää, kun rakennetaan integraatioita tai analyysityökaluja:

Näytteenotto perustuu kelvollisiin mittarin UART-kehyksiin.
Moduuli tallentaa näytteen, joka on lähimpänä kutakin UTC-ajan puolen tunnin rajaa.
UTC-ajan on oltava kelvollinen ennen kuin historiatietueita tallennetaan.
Jos timeSynced on 0, uusia historianäytteitä ei tallenneta.
Käynnistyksen jälkeen Datas voi olla tyhjä, kunnes riittävästi kelvollisia näytteitä on kerätty.
Nykyinen tallennus perustuu RAM-muistiin, joten rajapinta on tarkoitettu viimeaikaiseen paikalliseen historiaan, ei pitkäaikaiseen tallennukseen.

Tämä tekee rajapinnasta sopivan paikalliseen kyselyyn, lyhyen aikavälin analyysiin ja integraatiotestaukseen. Pitkäaikaisia energiaraportteja varten käyttäjien tulisi edelleen ylläpitää pysyvää tietolähdettä, kuten IAMMETER-pilvitietoja tai omaa tietokantaa.

Esimerkkejä integraatioideoista

Kehittäjät ja edistyneet käyttäjät voivat käyttää päätepistettä /api/energyhistory yksinkertaisena paikallisena tietolähteenä viimeaikaiselle kWh-historialle.

Yksi yleinen tapa on kysellä päätepistettä säännöllisesti, lukea channels-luettelo ja tallentaa kaikki uudet Datas-tietueet paikalliseen tietokantaan. Tämä voi tukea paikallisia hallintapaneeleja, mukautettuja raportteja tai offline-analyysiskriptejä.

Toinen hyödyllinen skenaario on aurinkosähkön omakäytön analysointi. Vertaamalla ostettuja ja myytyjä kWh-arvoja puolen tunnin jaksoittain käyttäjät voivat ymmärtää paremmin, milloin kotitalouden kuormat kuluttavat aurinkosähköä paikallisesti ja milloin ylimääräinen energia myydään verkkoon. Tämä voi tukea parempia automaatiopäätöksiä, kuten joustavien kuormien siirtämistä ajankohtiin, jolloin aurinkosähkön tuotto on suurempi.

Jos rakennat paikallisia integraatioita, katso myös Local API, Modbus/TCP and MQTT ja IAMMETER Local API Explorer.

Miten tämä sopii energianhallintaan

Energian historian rajapinnan arvo ei ole vain siinä, että se tarjoaa enemmän dataa. Olennaista on, mitä käyttäjät voivat tehdä tällä datalla.

Puolen tunnin kWh-historian avulla käyttäjät voivat analysoida viimeaikaista sähkön ostoa ja myyntiä, tunnistaa käyttökuvioita ja arvioida, auttavatko aurinkosähkö- tai kuormanohjausstrategiat todella. Tämä tukee IAMMETERin laajempaa tavoitetta: muuttaa energianseurannan data käytännön päätöksiksi, jotka parantavat energiatehokkuutta ja pienentävät sähkölaskuja.

Käyttäjille, jotka yhdistävät IAMMETERin automaatioalustoihin, paikallinen energian historia voi tarjota myös kätevän datakerroksen ohjauslogiikan testaamiseen ja validointiin. Esimerkiksi Home Assistant -käyttäjät, jotka optimoivat aurinkosähkön ylijäämän käyttöä, voivat tarkastella viimeaikaisia kWh-muutoksia yhdessä automaation toiminnan kanssa. Katso vastaavasta käyttötapauksesta Home Assistant Solar Energy Automation with IAMMETER.

UKK

Voiko tämä rajapinta korvata pitkäaikaisen energian historian?

Ei. Rajapinta tallentaa enintään 96 tietuetta eli 48 tuntia puolen tunnin dataa RAM-muistiin. Se on suunniteltu viimeaikaiseen paikalliseen historiaan. Tiedot menetetään uudelleenkäynnistyksen jälkeen.

Miksi `Datas` on tyhjä käynnistyksen jälkeen?

Käynnistyksen jälkeen moduuli tarvitsee kelvollisen UTC-ajan ja kelvolliset mittarikehykset ennen kuin historianäytteitä voidaan tallentaa. Kunnes riittävästi kelvollisia näytteitä on kerätty, rajapinta voi palauttaa tyhjän Datas-taulukon.

Perustuvatko aikaleimat paikalliseen aikaan?

Ei. Näytteenottojaksot on kohdistettu UTC-ajan puolen tunnin rajoihin.

Miten ohjelmiston tulisi tulkita arvotaulukko?

Lue aina ensin channels-kenttä. Jokaisen Datas[].values-taulukon arvot noudattavat samaa järjestystä kuin kanavien nimet.