Místní API historie energie pro odečty kWh

title: Místní API historie energie pro odečty kWh

abstract: Čtěte půlhodinovou historii kWh lokálně pro offline analýzu.

language: cs

author: Jessica

Úvod

Pro uživatele, kteří si vytvářejí vlastní dashboardy, automatizace nebo nástroje pro offline analýzu, jsou skutečná energetická data užitečnější, když jsou dostupná ve stabilním intervalu. Jediné měření výkonu v reálném čase ukáže, co se děje právě teď, ale půlhodinová historie kWh pomáhá uživatelům pochopit, jak se odběr a přetok elektřiny v průběhu času mění.

Od verze firmwaru i.91.063TS8.bin, vydané 2. června 2026, IAMMETER podporuje nové místní API: GET /api/energyhistory. Toto API vrací lokálně uložené odečty kWh vzorkované kolem půlhodinových hranic UTC, což usnadňuje analýzu nedávné spotřeby energie bez nutnosti spoléhat se pouze na historii v cloudu.

To je obzvláště užitečné pro monitorování fotovoltaiky, monitorování spotřeby domácnosti a vlastní pracovní postupy řízení energie, kde uživatelé chtějí porovnávat data o odběru, přetoku a energii na úrovni jednotlivých fází. IAMMETER není jen monitor; smyslem sběru těchto dat je pomoci uživatelům optimalizovat spotřebu energie, zvýšit vlastní spotřebu fotovoltaiky a snížit účty za elektřinu.

Co API historie energie poskytuje

Nový koncový bod je:

GET /api/energyhistory

Vrací odečty energie v kWh, vzorkované kolem těchto půlhodinových hranic UTC:

00:00
00:30
01:00
01:30
a tak dále

Firmware uchovává až 96 záznamů, což odpovídá 48 hodinám historie v 30minutových intervalech. Záznamy jsou uloženy v RAM Wi-Fi modulu, takže se po restartu zařízení ztratí.

Typická odpověď obsahuje:

utc: aktuální časové razítko UTC modulu
timeSynced: zda má modul platný čas UTC
interval: interval vzorkování, v současnosti 1800 sekund
count: počet dostupných záznamů historie
order: v současnosti newest_first
unit: v současnosti kWh
channels: názvy kanálů odpovídající jednotlivým hodnotám
Datas: půlhodinové záznamy historie

Každá položka v Datas obsahuje časové razítko UTC a pole hodnot kWh. Hodnoty jsou ve stejném pořadí jako pole channels.

Proč je půlhodinová historie kWh důležitá

Půlhodinová energetická data jsou praktická, protože uživatelům poskytují kompaktní, ale smysluplný pohled na energetické chování. Namísto ukládání každého bodu v reálném čase mohou uživatelé analyzovat kumulované hodnoty odběru a přetoku za pevné časové úseky.

Uživatel může například místní data využít k tomu, aby:

Zkontroloval nedávno odebranou a dodanou energii, aniž by čekal na cloudové reporty.
Exportoval posledních 48 hodin odečtů kWh do místní databáze nebo souboru CSV.
Porovnal vzorce přetoku z fotovoltaiky se spotřebou domácnosti.
Ověřil, zda automatizační strategie mění spotřebu elektřiny v konkrétních obdobích.
Vytvořil místní dashboard pro nedávnou historii energie.

Pro širší scénáře monitorování fotovoltaiky viz IAMMETER Solar Energy Monitoring Solution. Pro monitorování spotřeby v domácnostech viz IAMMETER Home Energy Monitoring Solution.

Podporované uspořádání kanálů

Pole channels říká klientovi, jak interpretovat hodnoty v každém záznamu historie. Různé konfigurace měřidel vracejí různá uspořádání kanálů.

Jedna fáze

["imp", "exp"]

Rozdělená fáze

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

Tři fáze

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

Tři fáze se zapnutým čistým měřením

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

Protože se názvy kanálů vracejí v odpovědi, měl by vlastní software nejprve načíst pole channels a teprve poté podle něj přiřadit každou hodnotu v Datas[].values.

Původní příklady návratových hodnot API

Následující dva příklady ukazují původní návratové hodnoty API pro prázdnou odpověď a pro odpověď s daty.

Příklad prázdné odpovědi

Po spuštění zařízení může být pole historie prázdné, dokud není k dispozici platný čas UTC a platné rámce měřidla. V takovém případě může API vrátit count: 0 a prázdné pole 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": []
}

Tato odpověď je po spuštění normální. Místní dashboard nebo skript by měl tento stav ošetřit a počkat na nové půlhodinové vzorky.

Příklad odpovědi s daty

Následující příklad ukazuje dva půlhodinové záznamy z třífázového měřidla. Odpověď je seřazena od nejnovějšího po nejstarší.

{
  "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 nejnovějším záznamu je a_imp rovno 11.337 kWh, a_exp je 11.201 kWh a tak dále. Význam každé hodnoty je definován polem channels.

Použití návratových hodnot v softwaru

Výše uvedené původní příklady návratových hodnot stačí k vytvoření jednoduché logiky místní analýzy. Klíčové je nejprve načíst channels a toto pořadí pak použít na každou položku v Datas.

Přiřazení `channels` k `values`

Při vytváření softwaru nad tímto API se vyhněte pevnému zakódování pozic, pokud není konfigurace měřidla neměnná. Bezpečnějším přístupem je převést seznam kanálů a pole hodnot na pojmenovaný 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);

Pro výše uvedenou ukázkovou třífázovou odpověď by latestByChannel obsahoval:

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

Díky tomu jsou data snadněji uložitelná, zobrazitelná nebo exportovatelná do nástroje místní analýzy.

Výpočet půlhodinové změny kWh

Pokud vrácené hodnoty kWh používáte jako kumulativní odečty energie, lze změnu mezi dvěma sousedními záznamy vypočítat odečtením starší hodnoty od novější hodnoty pro stejný kanál.

S použitím výše uvedeného třífázového příkladu:

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

Tento typ výpočtu může uživatelům pomoci sestavit report nedávného odběru a přetoku, porovnat změny energie na úrovni fází nebo zjistit, kolik energie bylo odebráno či dodáno během konkrétního půlhodinového úseku.

Důležité chování při vzorkování

Historii energie vytváří lokálně Wi-Fi modul. Při tvorbě integrací nebo analytických nástrojů je chování při vzorkování důležité:

Vzorkování je řízeno platnými rámci měřidla po UART.
Modul ukládá vzorek nejblíže každé půlhodinové hranici UTC.
Před uložením záznamů historie musí být čas UTC platný.
Pokud je timeSynced rovno 0, nezaznamenávají se žádné nové vzorky historie.
Po spuštění může být Datas prázdné, dokud není zachyceno dostatek platných vzorků.
Současné úložiště je v RAM, takže API je určeno pro nedávnou místní historii, nikoli pro dlouhodobé ukládání.

Díky tomu je API vhodné pro místní dotazování, krátkodobou analýzu a testování integrací. Pro dlouhodobé energetické reporty by uživatelé měli nadále udržovat trvalý zdroj dat, jako jsou data v cloudu IAMMETER nebo jejich vlastní databáze.

Příklady nápadů na integraci

Vývojáři a pokročilí uživatelé mohou použít /api/energyhistory jako jednoduchý místní zdroj dat pro nedávnou historii kWh.

Běžným přístupem je periodicky dotazovat koncový bod, načíst seznam channels a uložit všechny nové záznamy Datas do místní databáze. To může podpořit místní dashboardy, vlastní reporty nebo skripty pro offline analýzu.

Dalším užitečným scénářem je analýza vlastní spotřeby fotovoltaiky. Porovnáním hodnot odebrané a dodané kWh v půlhodinových úsecích mohou uživatelé lépe pochopit, kdy domácí spotřebiče spotřebovávají vyrobenou solární energii lokálně a kdy je přebytečná energie dodávána do sítě. To může podpořit lepší automatizační rozhodnutí, jako je přesun flexibilních zátěží do období s vyšším výkonem fotovoltaiky.

Pokud vytváříte místní integrace, podívejte se také na Local API, Modbus/TCP and MQTT a na IAMMETER Local API Explorer.

Jak to zapadá do řízení energie

Hodnota API historie energie nespočívá jen v tom, že zpřístupňuje více dat. Klíčové je, co uživatelé s těmito daty dokážou dělat.

S půlhodinovou historií kWh mohou uživatelé analyzovat nedávný odběr a přetok elektřiny, identifikovat vzorce spotřeby a vyhodnotit, zda strategie fotovoltaiky nebo řízení zátěže skutečně pomáhají. To podporuje širší cíl IAMMETER: přeměnit data z monitorování energie na praktická rozhodnutí, která zvyšují energetickou účinnost a snižují účty za elektřinu.

Pro uživatele, kteří kombinují IAMMETER s automatizačními platformami, může místní historie energie poskytnout také pohodlnou datovou vrstvu pro testování a ověřování řídicí logiky. Například uživatelé Home Assistant, kteří optimalizují využití přebytku fotovoltaiky, mohou porovnat nedávné změny kWh s chováním automatizace. Související případ použití najdete v Home Assistant Solar Energy Automation with IAMMETER.

Časté dotazy

Může toto API nahradit dlouhodobou historii energie?

Ne. API ukládá do RAM až 96 záznamů, tedy 48 hodin půlhodinových dat. Je určeno pro nedávnou místní historii. Data se po restartu ztratí.

Proč je `Datas` po spuštění prázdné?

Po spuštění modul potřebuje platný čas UTC a platné rámce měřidla, než může zaznamenat vzorky historie. Dokud není zachyceno dostatek platných vzorků, může API vrátit prázdné pole Datas.

Jsou časová razítka založena na místním čase?

Ne. Úseky vzorkování jsou zarovnány na půlhodinové hranice UTC.

Jak má software interpretovat pole hodnot?

Vždy nejprve načtěte pole channels. Hodnoty v každém poli Datas[].values jsou ve stejném pořadí jako názvy kanálů.