API della cronologia energetica locale per le letture in kWh

Introduzione

Per gli utenti che creano le proprie dashboard, automazioni o strumenti di analisi offline, i dati energetici reali sono più utili quando sono disponibili a intervalli regolari. Una singola lettura di potenza in tempo reale può mostrare cosa sta accadendo in questo momento, ma la cronologia dei kWh ogni mezz'ora aiuta a capire come cambiano nel tempo l'energia importata e quella esportata.

A partire dalla versione firmware i.91.063TS8.bin, rilasciata il 2 giugno 2026, IAMMETER supporta una nuova API locale: GET /api/energyhistory. Questa API restituisce le letture in kWh memorizzate nella cache locale, campionate in corrispondenza dei confini di mezz'ora UTC, rendendo più semplice analizzare i consumi energetici recenti senza affidarsi soltanto alla cronologia lato cloud.

È particolarmente utile per il monitoraggio solare, il monitoraggio energetico domestico e i flussi di lavoro personalizzati di gestione dell'energia, in cui gli utenti vogliono confrontare i dati di energia importata, esportata e a livello di fase. IAMMETER non è solo un misuratore; lo scopo della raccolta di questi dati è aiutare gli utenti a ottimizzare l'uso dell'energia, migliorare l'autoconsumo solare e ridurre le bollette elettriche.

Cosa fornisce l'API della cronologia energetica

Il nuovo endpoint è:

GET /api/energyhistory

Restituisce le letture energetiche in kWh, campionate in corrispondenza di questi confini di mezz'ora UTC:

• 00:00
• 00:30
• 01:00
• 01:30
• e così via

Il firmware conserva fino a 96 record, pari a 48 ore di cronologia con intervalli di 30 minuti. I record sono memorizzati nella RAM del modulo Wi-Fi, quindi vengono persi dopo il riavvio del dispositivo.

Una risposta tipica include:

• utc: il timestamp UTC corrente del modulo
• timeSynced: indica se il modulo dispone di un orario UTC valido
• interval: l'intervallo di campionamento, attualmente 1800 secondi
• count: il numero di record di cronologia disponibili
• order: attualmente newest_first
• unit: attualmente kWh
• channels: i nomi dei canali corrispondenti a ciascun valore
• Datas: i record di cronologia ogni mezz'ora

Ogni elemento in Datas include un timestamp UTC e un array di valori in kWh. I valori seguono lo stesso ordine dell'array channels.

Perché la cronologia dei kWh ogni mezz'ora è importante

I dati energetici ogni mezz'ora sono pratici perché offrono una visione compatta ma significativa del comportamento energetico. Invece di memorizzare ogni punto in tempo reale, gli utenti possono analizzare i valori accumulati di importazione ed esportazione su intervalli di tempo fissi.

Ad esempio, un utente può usare i dati locali per:

• Esaminare l'energia importata ed esportata di recente senza attendere i report del cloud.
• Esportare le ultime 48 ore di letture in kWh verso un database locale o un file CSV.
• Confrontare i pattern di esportazione solare con i consumi domestici.
• Verificare se una strategia di automazione modifica il consumo elettrico in periodi specifici.
• Creare una dashboard locale per la cronologia energetica recente.

Per scenari più ampi di monitoraggio solare, consulta la soluzione di monitoraggio dell'energia solare IAMMETER. Per il monitoraggio dell'elettricità residenziale, consulta la soluzione di monitoraggio energetico domestico IAMMETER.

Layout dei canali supportati

Il campo channels indica al client come interpretare i valori in ciascun record di cronologia. Configurazioni diverse del misuratore restituiscono layout di canali diversi.

Monofase

["imp", "exp"]

Bifase

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

Trifase

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

Trifase con net metering abilitato

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

Poiché i nomi dei canali vengono restituiti nella risposta, il software personalizzato dovrebbe leggere prima l'array channels e poi mappare di conseguenza ogni valore in Datas[].values.

Esempi di risposta originali dell'API

I due esempi seguenti mostrano i valori di ritorno originali dell'API per una risposta vuota e per una risposta con dati.

Esempio di risposta vuota

Dopo l'avvio del dispositivo, l'array della cronologia può essere vuoto finché non sono disponibili un orario UTC valido e frame validi del misuratore. In questo caso, l'API può restituire count: 0 e un array Datas vuoto.

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

Questa risposta è normale dopo l'avvio. Una dashboard o uno script locale dovrebbe gestire questo stato e attendere nuovi campioni ogni mezz'ora.

Esempio di risposta con dati

L'esempio seguente mostra due record ogni mezz'ora di un misuratore trifase. La risposta è ordinata dal più recente al più vecchio.

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

Nel record più recente, a_imp è 11.337 kWh, a_exp è 11.201 kWh, e così via. Il significato di ciascun valore è definito dall'array channels.

Utilizzo dei valori di ritorno nel software

Gli esempi di ritorno originali riportati sopra sono sufficienti per costruire una semplice logica di analisi locale. La chiave è leggere prima channels e poi applicare quell'ordine a ciascun elemento in Datas.

Mappatura di channels sui values

Quando si sviluppa software attorno a questa API, evita di codificare le posizioni in modo fisso, a meno che la configurazione del misuratore non sia fissa. Un approccio più sicuro consiste nel convertire l'elenco dei canali e l'array di valori in un oggetto con nomi espliciti.

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

Per la risposta trifase di esempio riportata sopra, latestByChannel conterrebbe:

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

Questo rende i dati più facili da memorizzare, visualizzare o esportare verso uno strumento di analisi locale.

Calcolo della variazione di kWh in mezz'ora

Se utilizzi i valori in kWh restituiti come letture di energia accumulate, la variazione tra due record adiacenti può essere calcolata sottraendo il valore più vecchio dal valore più recente per lo stesso canale.

Usando l'esempio trifase precedente:

variazione a_imp = 11.337 - 11.330 = 0.007 kWh
variazione a_exp = 11.201 - 11.198 = 0.003 kWh
variazione b_imp = 11.039 - 11.030 = 0.009 kWh
variazione b_exp = 10.908 - 10.900 = 0.008 kWh

Questo tipo di calcolo può aiutare gli utenti a creare un report recente di importazione/esportazione, confrontare le variazioni di energia a livello di fase o verificare quanta energia è stata importata o esportata in uno specifico intervallo di mezz'ora.

Comportamento di campionamento importante

La cronologia energetica è generata localmente dal modulo Wi-Fi. Il comportamento di campionamento è importante quando si sviluppano integrazioni o strumenti di analisi:

• Il campionamento è guidato da frame UART validi del misuratore.
• Il modulo memorizza il campione più vicino a ciascun confine di mezz'ora UTC.
• L'orario UTC deve essere valido prima che i record di cronologia vengano memorizzati.
• Se timeSynced è 0, non viene registrato alcun nuovo campione di cronologia.
• Dopo l'avvio, Datas può essere vuoto finché non sono stati acquisiti campioni validi sufficienti.
• L'archiviazione attuale è basata sulla RAM, quindi l'API è pensata per la cronologia locale recente, non per l'archiviazione a lungo termine.

Ciò rende l'API adatta al polling locale, all'analisi a breve termine e ai test di integrazione. Per i report energetici a lungo termine, gli utenti dovrebbero comunque mantenere una fonte di dati persistente, come i dati cloud di IAMMETER o un proprio database.

Idee di integrazione di esempio

Gli sviluppatori e gli utenti avanzati possono usare /api/energyhistory come semplice fonte di dati locale per la cronologia recente dei kWh.

Un approccio comune consiste nell'interrogare periodicamente l'endpoint, leggere l'elenco channels e salvare i nuovi record di Datas in un database locale. Questo può supportare dashboard locali, report personalizzati o script di analisi offline.

Un altro scenario utile è l'analisi dell'autoconsumo solare. Confrontando i valori in kWh importati ed esportati nei diversi intervalli di mezz'ora, gli utenti possono capire meglio quando i carichi domestici consumano localmente la produzione solare e quando l'energia in eccesso viene esportata. Questo può favorire decisioni di automazione migliori, come spostare i carichi flessibili nei periodi con maggiore produzione solare.

Se stai sviluppando integrazioni locali, consulta anche API locale, Modbus/TCP e MQTT e l'IAMMETER Local API Explorer.

Come si inserisce nella gestione dell'energia

Il valore di un'API per la cronologia energetica non sta soltanto nel fatto che espone più dati. Il punto chiave è ciò che gli utenti possono fare con quei dati.

Con la cronologia dei kWh ogni mezz'ora, gli utenti possono analizzare l'importazione e l'esportazione recenti di elettricità, individuare i pattern di consumo e valutare se le strategie solari o di controllo dei carichi stanno effettivamente aiutando. Questo sostiene l'obiettivo più ampio di IAMMETER: trasformare i dati di monitoraggio energetico in decisioni pratiche che migliorano l'efficienza energetica e riducono le bollette.

Per gli utenti che combinano IAMMETER con piattaforme di automazione, la cronologia energetica locale può anche fornire un comodo livello di dati per testare e validare la logica di controllo. Ad esempio, gli utenti di Home Assistant che ottimizzano l'uso dell'energia solare in eccesso possono esaminare le variazioni recenti dei kWh insieme al comportamento dell'automazione. Consulta Automazione dell'energia solare con Home Assistant e IAMMETER per un caso d'uso correlato.

FAQ

Questa API può sostituire la cronologia energetica a lungo termine?

No. L'API memorizza fino a 96 record, ovvero 48 ore di dati ogni mezz'ora, nella RAM. È progettata per la cronologia locale recente. I dati vengono persi dopo il riavvio.

Perché Datas è vuoto dopo l'avvio?

Dopo l'avvio, il modulo necessita di un orario UTC valido e di frame validi del misuratore prima che i campioni di cronologia possano essere registrati. Finché non sono stati acquisiti campioni validi sufficienti, l'API può restituire un array Datas vuoto.

I timestamp si basano sull'ora locale?

No. Gli intervalli di campionamento sono allineati ai confini di mezz'ora UTC.

Come dovrebbe il software interpretare l'array dei valori?

Leggi sempre prima il campo channels. I valori in ciascun array Datas[].values seguono lo stesso ordine dei nomi dei canali.