Lokalne API historii energii dla odczytów kWh

Wprowadzenie

Dla użytkowników, którzy tworzą własne pulpity, automatyzacje lub narzędzia do analizy offline, rzeczywiste dane energetyczne są tym przydatniejsze, im stabilniejszy jest odstęp czasu, w jakim są dostępne. Pojedynczy odczyt mocy w czasie rzeczywistym pokazuje, co dzieje się teraz, natomiast półgodzinna historia kWh pomaga zrozumieć, jak pobór i oddawanie energii zmieniają się w czasie.

Począwszy od wersji firmware i.91.063TS8.bin, wydanej 2 czerwca 2026 r., IAMMETER obsługuje nowe lokalne API: GET /api/energyhistory. To API zwraca lokalnie buforowane odczyty kWh, próbkowane wokół półgodzinnych granic czasu UTC, co ułatwia analizę ostatniego zużycia energii bez opierania się wyłącznie na historii po stronie chmury.

Jest to szczególnie przydatne w monitorowaniu instalacji fotowoltaicznych, monitorowaniu energii w domu oraz we własnych procesach zarządzania energią, w których użytkownicy chcą porównywać dane o poborze, oddawaniu i energii na poziomie poszczególnych faz. IAMMETER to nie tylko monitor — celem zbierania tych danych jest pomoc użytkownikom w optymalizacji zużycia energii, zwiększeniu autokonsumpcji energii słonecznej i obniżeniu rachunków za prąd.

Co udostępnia API historii energii

Nowy punkt końcowy to:

GET /api/energyhistory

Zwraca odczyty energii w kWh, próbkowane wokół następujących półgodzinnych granic czasu UTC:

• 00:00
• 00:30
• 01:00
• 01:30
• i tak dalej

Firmware przechowuje do 96 rekordów, co odpowiada 48 godzinom historii w 30-minutowych odstępach. Rekordy są zapisywane w pamięci RAM modułu Wi-Fi, dlatego są tracone po restarcie urządzenia.

Typowa odpowiedź zawiera:

• utc: bieżący znacznik czasu UTC modułu
• timeSynced: informacja, czy moduł ma prawidłowy czas UTC
• interval: interwał próbkowania, obecnie 1800 sekund
• count: liczba dostępnych rekordów historii
• order: obecnie newest_first
• unit: obecnie kWh
• channels: nazwy kanałów odpowiadające poszczególnym wartościom
• Datas: półgodzinne rekordy historii

Każdy element w Datas zawiera znacznik czasu UTC oraz tablicę wartości kWh. Wartości występują w tej samej kolejności co tablica channels.

Dlaczego półgodzinna historia kWh ma znaczenie

Półgodzinne dane energetyczne są praktyczne, ponieważ dają użytkownikom zwięzły, ale zarazem wartościowy obraz zachowania energii. Zamiast przechowywać każdy punkt w czasie rzeczywistym, użytkownicy mogą analizować narastające wartości poboru i oddawania energii w stałych przedziałach czasu.

Na przykład użytkownik może wykorzystać dane lokalne do:

• przeglądu ostatnio pobranej i oddanej energii bez czekania na raporty z chmury;
• wyeksportowania ostatnich 48 godzin odczytów kWh do lokalnej bazy danych lub pliku CSV;
• porównania wzorców oddawania energii z instalacji fotowoltaicznej ze zużyciem w gospodarstwie domowym;
• sprawdzenia, czy strategia automatyzacji zmienia zużycie energii w określonych okresach;
• zbudowania lokalnego pulpitu z ostatnią historią energii.

W przypadku szerszych scenariuszy monitorowania fotowoltaiki zobacz Rozwiązanie IAMMETER do monitorowania energii słonecznej. W przypadku monitorowania energii w budynkach mieszkalnych zobacz Rozwiązanie IAMMETER do monitorowania energii w domu.

Obsługiwane układy kanałów

Pole channels informuje klienta, jak interpretować wartości w każdym rekordzie historii. Różne konfiguracje liczników zwracają różne układy kanałów.

Jednofazowy

["imp", "exp"]

Split phase

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

Trójfazowy

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

Trójfazowy z włączonym net meteringiem

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

Ponieważ nazwy kanałów są zwracane w odpowiedzi, własne oprogramowanie powinno najpierw odczytać tablicę channels, a następnie odpowiednio przypisać każdą wartość z Datas[].values.

Przykłady oryginalnych odpowiedzi API

Poniższe dwa przykłady pokazują oryginalne wartości zwracane przez API dla pustej odpowiedzi oraz dla odpowiedzi z danymi.

Przykład pustej odpowiedzi

Po uruchomieniu urządzenia tablica historii może być pusta, dopóki nie będzie dostępny prawidłowy czas UTC i prawidłowe ramki z licznika. W takim przypadku API może zwrócić count: 0 oraz pustą tablicę 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 odpowiedź jest normalna po uruchomieniu. Lokalny pulpit lub skrypt powinien obsłużyć ten stan i poczekać na nowe półgodzinne próbki.

Przykład odpowiedzi z danymi

Poniższy przykład pokazuje dwa półgodzinne rekordy z licznika trójfazowego. Odpowiedź jest uporządkowana od najnowszego do najstarszego rekordu.

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

W najnowszym rekordzie a_imp wynosi 11.337 kWh, a_exp wynosi 11.201 kWh i tak dalej. Znaczenie każdej wartości określa tablica channels.

Wykorzystanie zwracanych wartości w oprogramowaniu

Powyższe przykłady oryginalnych odpowiedzi wystarczą do zbudowania prostej logiki analizy lokalnej. Kluczowe jest, aby najpierw odczytać channels, a następnie zastosować tę kolejność do każdego elementu w Datas.

Mapowanie channels na values

Tworząc oprogramowanie korzystające z tego API, unikaj zakodowanych na stałe pozycji, chyba że konfiguracja licznika jest stała. Bezpieczniejszym podejściem jest zamiana listy kanałów i tablicy wartości na obiekt z nazwanymi polami.

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

Dla powyższego przykładowego licznika trójfazowego latestByChannel zawierałoby:

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

Dzięki temu dane łatwiej zapisać, wyświetlić lub wyeksportować do lokalnego narzędzia analitycznego.

Obliczanie zmiany kWh w ciągu pół godziny

Jeśli zwracane wartości kWh są wykorzystywane jako narastające odczyty energii, zmianę między dwoma sąsiednimi rekordami można obliczyć, odejmując starszą wartość od nowszej wartości dla tego samego kanału.

Korzystając z powyższego przykładu trójfazowego:

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

Tego typu obliczenia mogą pomóc użytkownikom w tworzeniu raportu ostatniego poboru i oddawania energii, porównywaniu zmian energii na poziomie faz lub sprawdzeniu, ile energii pobrano lub oddano w danym półgodzinnym przedziale.

Ważne informacje o sposobie próbkowania

Historia energii jest generowana lokalnie przez moduł Wi-Fi. Sposób próbkowania ma istotne znaczenie przy budowaniu integracji lub narzędzi analitycznych:

• próbkowanie opiera się na prawidłowych ramkach UART z licznika;
• moduł zapisuje próbkę najbliższą każdej półgodzinnej granicy czasu UTC;
• czas UTC musi być prawidłowy, zanim rekordy historii zostaną zapisane;
• jeśli timeSynced ma wartość 0, nowe próbki historii nie są zapisywane;
• po uruchomieniu Datas może być puste, dopóki nie zostanie zebrana wystarczająca liczba prawidłowych próbek;
• obecny magazyn danych opiera się na pamięci RAM, dlatego API jest przeznaczone do niedawnej historii lokalnej, a nie do długoterminowego przechowywania.

Dzięki temu API nadaje się do lokalnego odpytywania, krótkoterminowej analizy i testowania integracji. W przypadku długoterminowych raportów energetycznych użytkownicy nadal powinni prowadzić trwałe źródło danych, takie jak dane w chmurze IAMMETER lub własna baza danych.

Przykładowe pomysły na integracje

Programiści i zaawansowani użytkownicy mogą wykorzystać /api/energyhistory jako proste lokalne źródło danych o niedawnej historii kWh.

Jednym z typowych podejść jest okresowe odpytywanie punktu końcowego, odczyt listy channels i zapisywanie nowych rekordów Datas do lokalnej bazy danych. Może to obsłużyć lokalne pulpity, własne raporty lub skrypty analizy offline.

Innym przydatnym scenariuszem jest analiza autokonsumpcji energii słonecznej. Porównując wartości kWh poboru i oddawania w kolejnych półgodzinnych przedziałach, użytkownicy mogą lepiej zrozumieć, kiedy odbiorniki w domu zużywają energię z instalacji fotowoltaicznej na miejscu, a kiedy nadwyżka energii jest oddawana do sieci. Wspiera to lepsze decyzje automatyzacji, na przykład przesuwanie elastycznych odbiorów na okresy o większej produkcji energii słonecznej.

Jeśli tworzysz lokalne integracje, zobacz także Lokalne API, Modbus/TCP i MQTT oraz IAMMETER Local API Explorer.

Jak to wpisuje się w zarządzanie energią

Wartość API historii energii nie polega tylko na udostępnianiu większej ilości danych. Kluczowe jest to, co użytkownicy mogą z tymi danymi zrobić.

Dzięki półgodzinnej historii kWh użytkownicy mogą analizować niedawny pobór i oddawanie energii, rozpoznawać wzorce zużycia oraz oceniać, czy strategie dotyczące fotowoltaiki lub sterowania odbiorami rzeczywiście przynoszą efekty. Wspiera to szerszy cel IAMMETER: zamianę danych z monitoringu energii w praktyczne decyzje, które poprawiają efektywność energetyczną i obniżają rachunki za prąd.

Użytkownikom, którzy łączą IAMMETER z platformami automatyzacji, lokalna historia energii może również zapewnić wygodną warstwę danych do testowania i weryfikacji logiki sterowania. Na przykład użytkownicy Home Assistant, którzy optymalizują wykorzystanie nadwyżki energii słonecznej, mogą przeglądać ostatnie zmiany kWh wraz z zachowaniem automatyzacji. Powiązany przypadek użycia opisano w Automatyzacja energii słonecznej w Home Assistant z IAMMETER.

Najczęściej zadawane pytania

Czy to API może zastąpić długoterminową historię energii?

Nie. API przechowuje do 96 rekordów, czyli 48 godzin danych półgodzinnych, w pamięci RAM. Jest przeznaczone do niedawnej historii lokalnej. Dane są tracone po restarcie.

Dlaczego Datas jest puste po uruchomieniu?

Po uruchomieniu moduł potrzebuje prawidłowego czasu UTC i prawidłowych ramek z licznika, zanim próbki historii będą mogły zostać zapisane. Dopóki nie zostanie zebrana wystarczająca liczba prawidłowych próbek, API może zwracać pustą tablicę Datas.

Czy znaczniki czasu są oparte na czasie lokalnym?

Nie. Przedziały próbkowania są wyrównane do półgodzinnych granic czasu UTC.

Jak oprogramowanie powinno interpretować tablicę wartości?

Zawsze najpierw odczytuj pole channels. Wartości w każdej tablicy Datas[].values występują w tej samej kolejności co nazwy kanałów.