Un inverter, una colonnina di ricarica o una pompa di calore che già invia dati al produttore offre due percorsi per accedervi. Si può interrogare l'API del produttore oppure leggere il dispositivo sul sito tramite Modbus o un'altra interfaccia locale. I sottocontatori vicini di solito non hanno una connessione cloud: per loro un gateway locale è l'unico percorso. Scegliere per ciascun dispositivo, non per l'intero sito.
Alcune API di terze parti aggregano i cloud di più produttori. Riducono il lavoro di integrazione, ma inseriscono un secondo fornitore, con un proprio intervallo e una propria quota di chiamate, fra il sito e i dati.
Confronto diretto
| Domanda | API cloud del produttore | Gateway locale |
|---|---|---|
| Quali punti? | Quelli che il fornitore espone all'account, spesso meno di quelli disponibili sul dispositivo | Quelli offerti dall'interfaccia locale del dispositivo e mappabili dal gateway |
| Intervallo | Quello di caricamento del dispositivo e di aggregazione del fornitore, poi limitato dalla quota di chiamate | Intervallo di interrogazione o invio configurato sul sito, spesso da 1 s a 1 min |
| Marca temporale | Momento della misura o del caricamento, secondo l'API | Momento dell'interrogazione, salvo che il dispositivo fornisca il proprio tempo |
| Interruzione internet | Non arrivano nuovi dati. Il vuoto si riempie dopo solo se il dispositivo conserva le misure e l'API rende disponibile lo storico | Acquisizione, storico locale, dashboard e automazione continuano. L'invio a monte riprende dal buffer |
| Quali apparecchiature? | Gamma di un produttore, o più gamme tramite un aggregatore | Ogni dispositivo con interfaccia locale supportata, in un modello dei dati controllato dal gestore |
| Sul sito | Nessun hardware aggiuntivo | Gateway, alimentazione e collegamento di rete |
| Gestione continua | Credenziali, rinnovo dei token e modifiche dell'API del fornitore | Aggiornamenti software, backup e regole del firewall |
| Controllo | Solo i comandi esposti dal fornitore, attraverso i suoi server | Scritture locali, con limiti e interblocchi configurati sul sito |
Quando è adatta un'API cloud
Un'API cloud è il percorso più rapido se le apparecchiature sono già online e lo scopo è la rendicontazione. La quota di chiamate determina però la frequenza ottenibile. L'API Enlighten v4 di Enphase consente 10 chiamate al minuto e 1.000 al mese nel piano gratuito Watt, 50.000 al mese in Kilowatt e 300.000 in Megawatt (piani per sviluppatori Enphase). Una chiamata ogni 15 minuti per ciascun sistema equivale a 96 al giorno, circa 2.900 al mese. Il piano gratuito non sostiene questa frequenza neppure per un sistema. Quaranta sistemi richiedono circa 117.000 chiamate mensili, oltre il limite Kilowatt.
Gli stessi 40 sistemi richiedono soltanto 40 chiamate al giorno se l'integrazione acquisisce una volta di notte gli intervalli dell'intera giornata da un endpoint che restituisce un giorno per chiamata. Un report mensile del portafoglio si adatta bene a questo schema; una dashboard che deve mostrare l'ultima ora, no.
Verificare con un account e un dispositivo reali, non soltanto con gli esempi della documentazione:
- l'intervallo effettivamente restituito dall'API per i dispositivi in uso e la quota del proprio piano;
- quanto indietro si estende lo storico e se gli intervalli mancanti compaiono in seguito;
- se ogni marca temporale indica il momento della misura o del caricamento e in quale fuso orario;
- come l'API rappresenta un dispositivo offline: vuoto, ultimo valore ripetuto oppure zero;
- chi possiede l'account e come si trasferisce l'accesso quando il sito o l'asset viene venduto;
- quanto preavviso offre il fornitore prima di ritirare un endpoint.
L'ultimo punto è un rischio concreto. Il 20 febbraio 2026 Enphase annunciò il ritiro di nove endpoint per il 16 marzo 2026, con 24 giorni di preavviso. Dopo tale data, le chiamate a quegli endpoint restituiscono HTTP 401 (avviso di ritiro Enphase).
Quando è adatto un gateway locale
Un gateway locale è adatto se i dispositivi hanno interfacce locali ma non una connessione cloud. Un esempio è un sito con 20 sottocontatori Modbus RTU su un bus RS-485, un'uscita a impulsi sul contatore del gas e un sistema di gestione dell'edificio BACnet/IP. Nessuno di questi invia dati altrove. Il gateway li legge all'intervallo configurato, conserva lo storico sul sito ed esegue l'automazione senza passare da un server remoto.
Quando si legge direttamente un dispositivo, anche la mappatura diventa responsabilità del progetto. Gli errori frequenti sono nei registri: un valore a 32 bit letto con le due parole nell'ordine sbagliato, un fattore di scala applicato due volte oppure un registro di energia in Wh dichiarato in kWh nella mappa. Ognuno può produrre un numero plausibile ma errato. La guida alla mappa dei registri Modbus spiega come confrontare ogni punto con il display del contatore.
Anche il gateway è un'apparecchiatura da gestire. In fase di messa in servizio, assegnare a una persona la responsabilità di aggiornamenti software, backup e regole firewall. Un gateway senza responsabile non viene aggiornato.
Marche temporali e intervalli di domanda
Un addebito sulla domanda di 15 minuti è calcolato dall'energia di ciascun intervallo: la marca temporale determina quindi dove ricade una lettura. Supponiamo che un dispositivo accumuli misure durante un'interruzione di tre ore a una media di 400 kW e carichi 1.200 kWh quando il collegamento ritorna alle 14:07. Se l'API o la piattaforma assegnano alle letture l'ora del caricamento, tutti i 1.200 kWh finiscono nell'intervallo 14:00–14:15. L'intervallo mostra allora una domanda di 4.800 kW, dodici volte quella reale.
La soluzione è conservare il momento della misura dal dispositivo fino alla piattaforma. Anche l'interrogazione locale presenta una versione ridotta dello stesso problema. Il gateway attribuisce al dato Modbus il momento dell'interrogazione; un registro che si aggiorna una volta al minuto può quindi essere vecchio di quasi un minuto al momento della lettura. La guida al tempo della sorgente e di arrivo spiega come specificare il significato temporale di ciascun campo. Il calcolatore della domanda per intervallo mostra come un singolo intervallo errato cambi il picco fatturato.
Architetture ibride
Un sito usa spesso entrambi i percorsi. Consideriamo un impianto fotovoltaico da 250 kW i cui inverter comunicano con il portale del produttore, un contatore principale di prelievo e sei sottocontatori Modbus, uno sulla linea del fotovoltaico. Due regole mantengono corretta l'architettura.
La prima regola è una sorgente per ciascun punto. Nei 15 minuti fino alle 13:00, il contatore sulla linea fotovoltaica misura 182 kW e l'API degli inverter comunica 185 kW. Sono due misure dello stesso flusso. Se si sommano entrambe alla produzione del sito, il report indica 367 kW da un impianto di 250 kW. Usare il contatore della linea, perché se ne conosce la classe di accuratezza, e mantenere il valore API per la diagnostica degli inverter. Non sostituire un valore mancante del contatore con quello dell'API senza contrassegnarlo come sostituito.
La seconda regola è un solo responsabile per ogni punto scrivibile. Una piattaforma di flessibilità comanda la batteria del sito tramite l'API del produttore e imposta la scarica a 0 kW per un evento di carica. Nello stesso momento, una regola locale di taglio dei picchi scrive 150 kW di scarica quando il prelievo supera il limite. Ciascuna interfaccia segnala un successo. Il setpoint cambia a ogni scrittura e il suo andamento oscilla a dente di sega. Assegnare il setpoint a un solo sistema: l'altro lo legge o chiede una modifica al responsabile.
La guida alla qualità dei dati spiega come contrassegnare valori sostituiti e obsoleti.
Sicurezza e accesso
I due percorsi collocano il confine di fiducia in luoghi diversi. Con un'API cloud, la credenziale è l'asset da proteggere. Enlighten API v4 usa OAuth 2.0. Il proprietario del sistema approva l'applicazione; il token di accesso dura un giorno e quello di rinnovo un mese (guida rapida Enphase). Se l'integrazione non rinnova il token entro quel mese, occorre una nuova approvazione del proprietario. Registrare a quale account è associato ogni asset. La vendita del sito o il cambio di installatore può revocare l'accesso.
Con un gateway, l'asset da proteggere è il dispositivo nella rete OT. Non serve aprire una porta verso internet: il gateway si collega in uscita alla piattaforma. La sezione 5.2.3.1 di NIST SP 800-82 Rev. 3 raccomanda di separare OT e IT, consentire collegamenti soltanto fra zone adiacenti e limitare le regole in uscita quanto quelle in ingresso. Per un gateway significa autorizzare solo le destinazioni effettive: broker o endpoint della piattaforma, server dell'ora e servizio di aggiornamento. Una regola che consente tutto il traffico HTTPS in uscita non è una lista di destinazioni consentite.
Provare un'interruzione
Prima di impegnare un intero portafoglio su uno dei due percorsi, interrompere internet in un sito pilota secondo un piano concordato. Scollegare il collegamento WAN, non l'alimentazione del gateway: un'interruzione elettrica verifica un guasto diverso. Mantenere il collegamento interrotto per almeno due ore, attraversando così otto intervalli di domanda da 15 minuti.
- Durante l'interruzione, registrare ciò che continua a funzionare sul sito: letture, storico locale, dashboard e automazione.
- Registrare come la piattaforma rappresenta il periodo mancante: un vuoto, un valore obsoleto mantenuto costante oppure zeri. Gli zeri sono il risultato peggiore, perché sembrano misure reali.
- Ripristinare il collegamento e contare le letture arrivate. Cinquanta punti a intervalli di 1 minuto per due ore devono produrre 6.000 letture. Un numero inferiore indica perdite; uno superiore indica duplicati, che la piattaforma deve eliminare. MQTT QoS 1 prevede la consegna almeno una volta (MQTT 5.0, sezione 4.3.2): i duplicati dopo una riconnessione sono un comportamento normale, non necessariamente un guasto.
- Verificare che le letture recuperate conservino il momento originale della misura e che nessun intervallo di domanda mostri un picco come quello dell'esempio precedente.
- Per un'API, verificare se e in quanto tempo il fornitore riempie il vuoto, e se l'integrazione richiede nuovamente il periodo mancante.
La prova è superata quando il numero delle letture è corretto, ciascuna mantiene la propria marca temporale originale e la piattaforma non ha mai rappresentato l'interruzione con zeri. La lista di controllo per la messa in servizio offre un verbale per la prova. La guida al buffer di memorizzazione e inoltro mostra come dimensionare la memoria locale per l'interruzione più lunga prevista.
Rendicontazione e controllo sono attività diverse
Un'integrazione per la rendicontazione richiede letture periodiche. Una per il controllo richiede invece un ciclo di vita del comando: scadenza, limiti locali, riscontro misurato e comportamento di sicurezza se il collegamento cade. Un'API cloud non può fornire questo comportamento locale, perché il collegamento guasto è proprio il percorso verso il cloud.
Una risposta positiva dell'API significa che il fornitore ha accettato il comando. Una risposta positiva a una scrittura Modbus significa che il registro è stato scritto. Nessuna delle due dimostra che l'asset abbia agito. La guida alla verifica dei comandi BESS mostra come confermare la risposta tramite misure. La matrice dei guasti degli interblocchi mostra come decidere il comportamento del sito quando il percorso di comando fallisce.
Edge sul Gateway
Edge funziona sul Gateway ZGW-20 nel sito. Legge dispositivi wireless EpiSensor, dispositivi Zigbee e LoRaWAN di terzi, apparecchiature Modbus TCP e RTU e controllori BACnet/IP in un unico inventario. Conserva lo storico localmente ed esegue dashboard e automazione senza connessione internet. Invia i dati tramite MQTT o HTTPS, oppure come file via FTPS, in JSON o CSV. Nessun servizio cloud EpiSensor si trova in questo percorso. Il Gateway assorbe 5 W a riposo e al massimo 15 W.
Nella prova d'interruzione, Edge inserisce in una coda su disco le consegne non riuscite. Per le destinazioni gestite da Edge, controlla la coda ogni minuto e ritrasmette quando la destinazione torna disponibile. Le letture ritrasmesse conservano le marche temporali originali e non eseguono di nuovo l'automazione locale. Due limiti incidono sul conteggio del punto 3: un lotto ancora in memoria quando il Gateway perde alimentazione può andare perso; un lotto che il ricevitore ha memorizzato prima che Edge registri l'esito positivo può arrivare due volte.
Domande frequenti
Qual è la differenza fra un’API cloud e un gateway locale?
Un’API cloud restituisce ciò che le apparecchiature hanno già caricato presso il produttore. Un gateway locale legge le apparecchiature sul sito tramite Modbus, BACnet, Zigbee o LoRaWAN e conserva le letture prima di inoltrarle. Durante un’interruzione internet il gateway continua ad acquisire, mentre l’API non ha nuovi dati da restituire. Nessuno dei due percorsi raggiunge la piattaforma finché il collegamento non torna disponibile.
Quando basta un’API cloud?
Quando le apparecchiature comunicano già con il produttore, l’API espone i punti necessari alla frequenza richiesta e lo scopo è la rendicontazione, non il controllo. Un report mensile per un portafoglio di impianti fotovoltaici è un caso tipico.
Perché usare un gateway Edge per il monitoraggio energetico?
Molti sottocontatori nei siti commerciali hanno soltanto un’interfaccia Modbus o a impulsi e nessuna connessione cloud: un gateway è quindi l’unico modo per leggerli. Lo stesso gateway mantiene storico locale e automazione anche durante un’interruzione internet.