API local de istoric energetic pentru valorile kWh

Introducere

Pentru utilizatorii care își construiesc propriile tablouri de bord, automatizări sau instrumente de analiză offline, datele energetice reale sunt mai utile atunci când sunt disponibile la un interval stabil. O singură citire de putere în timp real poate arăta ce se întâmplă în acest moment, dar istoricul kWh pe intervale de jumătate de oră îi ajută pe utilizatori să înțeleagă cum se modifică în timp importul și exportul de energie electrică.

Începând cu versiunea de firmware i.91.063TS8.bin, lansată pe 2 iunie 2026, IAMMETER acceptă un nou API local: GET /api/energyhistory. Acest API returnează valori kWh stocate în cache local, eșantionate în jurul limitelor de jumătate de oră UTC, ceea ce facilitează analizarea consumului recent de energie fără a depinde exclusiv de istoricul din cloud.

Acest lucru este util în special pentru monitorizarea solară, monitorizarea energiei la domiciliu și fluxurile de lucru personalizate de gestionare a energiei, în care utilizatorii doresc să compare importul, exportul și datele de energie la nivel de fază. IAMMETER nu este doar un dispozitiv de monitorizare; scopul colectării acestor date este de a-i ajuta pe utilizatori să optimizeze consumul de energie, să îmbunătățească autoconsumul solar și să reducă facturile la energie electrică.

Ce oferă API-ul Energy History

Noul endpoint este:

GET /api/energyhistory

Acesta returnează valori de energie în kWh, eșantionate în jurul acestor limite de jumătate de oră UTC:

• 00:00
• 00:30
• 01:00
• 01:30
• și așa mai departe

Firmware-ul păstrează până la 96 de înregistrări, echivalentul a 48 de ore de istoric la intervale de 30 de minute. Înregistrările sunt stocate în memoria RAM a modulului Wi-Fi, astfel încât se pierd după repornirea dispozitivului.

Un răspuns tipic include:

• utc: timestamp-ul UTC curent al modulului
• timeSynced: dacă modulul are o oră UTC validă
• interval: intervalul de eșantionare, în prezent 1800 secunde
• count: numărul de înregistrări de istoric disponibile
• order: în prezent newest_first
• unit: în prezent kWh
• channels: numele canalelor corespunzătoare fiecărei valori
• Datas: înregistrările de istoric pe jumătate de oră

Fiecare element din Datas include un timestamp UTC și un tablou de valori kWh. Valorile respectă aceeași ordine ca tabloul channels.

De ce contează istoricul kWh pe jumătate de oră

Datele energetice pe jumătate de oră sunt practice, deoarece oferă o imagine compactă, dar semnificativă, a comportamentului energetic. În loc să stocheze fiecare punct în timp real, utilizatorii pot analiza valorile acumulate de import și export pe intervale de timp fixe.

De exemplu, un utilizator poate folosi datele locale pentru a:

• Examina energia importată și exportată recent, fără a aștepta rapoartele din cloud.
• Exporta ultimele 48 de ore de valori kWh într-o bază de date locală sau într-un fișier CSV.
• Compara tiparele de export solar cu consumul gospodăriei.
• Verifica dacă o strategie de automatizare modifică utilizarea energiei electrice în anumite perioade.
• Construi un tablou de bord local pentru istoricul energetic recent.

Pentru scenarii mai ample de monitorizare solară, consultați Soluția de monitorizare a energiei solare IAMMETER. Pentru monitorizarea energiei electrice rezidențiale, consultați Soluția de monitorizare a energiei la domiciliu IAMMETER.

Structuri de canale acceptate

Câmpul channels indică clientului cum să interpreteze valorile din fiecare înregistrare de istoric. Diferite configurații de contor returnează structuri de canale diferite.

Monofazat

["imp", "exp"]

Split-phase (două faze)

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

Trifazat

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

Trifazat cu contorizare netă (NEM) activată

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

Deoarece numele canalelor sunt returnate în răspuns, software-ul personalizat ar trebui să citească mai întâi tabloul channels și apoi să mapeze corespunzător fiecare valoare din Datas[].values.

Exemple de răspunsuri originale ale API-ului

Următoarele două exemple arată valorile originale returnate de API pentru un răspuns gol și pentru un răspuns cu date.

Exemplu de răspuns gol

După pornirea dispozitivului, tabloul de istoric poate fi gol până când sunt disponibile o oră UTC validă și cadre valide de la contor. În acest caz, API-ul poate returna count: 0 și un tablou Datas gol.

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

Acest răspuns este normal după pornire. Un tablou de bord local sau un script ar trebui să gestioneze această stare și să aștepte noile eșantioane de jumătate de oră.

Exemplu de răspuns cu date

Următorul exemplu arată două înregistrări de jumătate de oră de la un contor trifazat. Răspunsul este ordonat de la cel mai nou la cel mai vechi.

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

În înregistrarea cea mai nouă, a_imp este 11.337 kWh, a_exp este 11.201 kWh și așa mai departe. Semnificația fiecărei valori este definită de tabloul channels.

Utilizarea valorilor returnate în software

Exemplele originale de răspuns de mai sus sunt suficiente pentru a construi o logică simplă de analiză locală. Cheia este să citiți mai întâi channels, apoi să aplicați această ordine fiecărui element din Datas.

Maparea channels la values

Când construiți software în jurul acestui API, evitați codificarea rigidă a pozițiilor, cu excepția cazului în care configurația contorului este fixă. O abordare mai sigură este convertirea listei de canale și a tabloului de valori într-un obiect cu proprietăți denumite.

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

Pentru exemplul de răspuns trifazat de mai sus, latestByChannel ar conține:

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

Acest lucru face datele mai ușor de stocat, afișat sau exportat către un instrument local de analiză.

Calcularea variației de kWh pe jumătate de oră

Dacă folosiți valorile kWh returnate ca valori acumulate de energie, variația dintre două înregistrări adiacente poate fi calculată scăzând valoarea mai veche din valoarea mai nouă pentru același canal.

Folosind exemplul trifazat de mai sus:

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

Acest tip de calcul îi poate ajuta pe utilizatori să construiască un raport recent de import/export, să compare variațiile de energie la nivel de fază sau să verifice câtă energie a fost importată sau exportată într-un anumit interval de jumătate de oră.

Comportament important de eșantionare

Istoricul energetic este generat local de modulul Wi-Fi. Comportamentul de eșantionare este important atunci când construiți integrări sau instrumente de analiză:

• Eșantionarea este determinată de cadre UART valide de la contor.
• Modulul stochează eșantionul cel mai apropiat de fiecare limită de jumătate de oră UTC.
• Ora UTC trebuie să fie validă înainte de stocarea înregistrărilor de istoric.
• Dacă timeSynced este 0, nu se înregistrează eșantioane noi de istoric.
• După pornire, Datas poate fi gol până când au fost capturate suficiente eșantioane valide.
• Stocarea actuală se face în RAM, astfel încât API-ul este destinat istoricului local recent, nu stocării pe termen lung.

Acest lucru face API-ul potrivit pentru interogarea locală periodică, analiza pe termen scurt și testarea integrărilor. Pentru rapoarte energetice pe termen lung, utilizatorii ar trebui să păstreze în continuare o sursă de date persistentă, cum ar fi datele din cloud IAMMETER sau propria bază de date.

Idei de integrare exemplu

Dezvoltatorii și utilizatorii avansați pot folosi /api/energyhistory ca sursă simplă de date locale pentru istoricul kWh recent.

O abordare frecventă este interogarea periodică a endpoint-ului, citirea listei channels și salvarea oricăror înregistrări noi din Datas într-o bază de date locală. Aceasta poate susține tablouri de bord locale, rapoarte personalizate sau scripturi de analiză offline.

Un alt scenariu util este analiza autoconsumului solar. Comparând valorile kWh importate și exportate pe intervale de jumătate de oră, utilizatorii pot înțelege mai bine când sarcinile gospodăriei consumă local energia solară generată și când surplusul de energie este exportat. Acest lucru poate susține decizii de automatizare mai bune, cum ar fi mutarea sarcinilor flexibile în perioadele cu producție solară mai mare.

Dacă construiți integrări locale, consultați și API local, Modbus/TCP și MQTT și IAMMETER Local API Explorer.

Cum se integrează în gestionarea energiei

Valoarea unui API de istoric energetic nu constă doar în faptul că expune mai multe date. Punctul esențial este ce pot face utilizatorii cu aceste date.

Cu istoricul kWh pe jumătate de oră, utilizatorii pot analiza importul și exportul recent de energie electrică, pot identifica tipare de consum și pot evalua dacă strategiile solare sau de control al sarcinilor ajută cu adevărat. Aceasta susține obiectivul mai amplu al IAMMETER: transformarea datelor de monitorizare a energiei în decizii practice care îmbunătățesc eficiența energetică și reduc facturile la energie electrică.

Pentru utilizatorii care combină IAMMETER cu platforme de automatizare, istoricul energetic local poate oferi, de asemenea, un strat de date convenabil pentru testarea și validarea logicii de control. De exemplu, utilizatorii Home Assistant care optimizează utilizarea surplusului solar pot examina variațiile recente de kWh alături de comportamentul automatizării. Consultați Automatizarea energiei solare cu Home Assistant și IAMMETER pentru un caz de utilizare similar.

Întrebări frecvente

Poate acest API să înlocuiască istoricul energetic pe termen lung?

Nu. API-ul stochează până la 96 de înregistrări, adică 48 de ore de date pe jumătate de oră, în RAM. Este conceput pentru istoricul local recent. Datele se pierd după repornire.

De ce este Datas gol după pornire?

După pornire, modulul are nevoie de o oră UTC validă și de cadre valide de la contor înainte ca eșantioanele de istoric să poată fi înregistrate. Până când sunt capturate suficiente eșantioane valide, API-ul poate returna un tablou Datas gol.

Timestamp-urile se bazează pe ora locală?

Nu. Intervalele de eșantionare sunt aliniate la limitele de jumătate de oră UTC.

Cum ar trebui software-ul să interpreteze tabloul de valori?

Citiți întotdeauna mai întâi câmpul channels. Valorile din fiecare tablou Datas[].values respectă aceeași ordine ca numele canalelor.