IAMMETER Wi-Fi Energy Meter: API Locali e Interfacce Aperte

IAMMETER Wi-Fi Energy Meter: API Locali e Interfacce Aperte

IAMMETER Wi-Fi energy meters supportano IAMMETER-Cloud così come integrazioni locali e di terze parti.

Le interfacce disponibili includono:

• API HTTP locale sulla LAN
• Pubblicazione MQTT e MQTTS
• Modbus TCP
• Upload TCP/TLS
• Upload HTTP/HTTPS
• Funzionamento locale autonomo

Queste interfacce permettono ai contatori IAMMETER di agire come fonti di dati aperte per:

• Home Assistant e altre piattaforme smart-home
• Automazione Node-RED
• Dashboard self-hosted
• Sistemi PLC e SCADA
• Sistemi di Gestione dell'Energia (EMS) personalizzati
• Sistemi di Gestione dell'Edificio (BMS) personalizzati
• Server dati di terze parti

Questa guida descrive prima il firmware e WebUI corrente. Screenshot e metodi di configurazione per firmware precedenti sono conservati nella sezione Legacy finale.

Per un'applicazione pronta all'uso basata su queste funzionalità, vedi Monitoraggio Energetico Domestico, Monitoraggio dell'Energia Solare, o monitoraggio locale senza accesso a Internet.

1) Aggiornamento all'Ultimo Firmware

Il firmware IAMMETER viene aggiornato continuamente. Prima di configurare un'integrazione, controlla la versione corrente e la compatibilità del modello:

• Pagina delle Release del Firmware IAMMETER

Il WebUI del firmware più recente espone le opzioni di configurazione più comuni direttamente. Le chiamate API di configurazione manuale conservate più avanti in questo articolo sono utili principalmente per la manutenzione di installazioni precedenti.

2) Scelta della Modalità Operativa nel WebUI Corrente

Seleziona una modalità operativa in base a dove il contatore deve inviare i dati o come deve operare localmente.

La modalità operativa controlla il comportamento di upload dei dati. La disponibilità dell'API locale e di Modbus TCP deve comunque essere verificata per il modello di contatore, il firmware e l'integrazione selezionata.

3) Perché le Interfacce Aperte sono Importanti

Le interfacce aperte permettono agli utenti di decidere dove i dati elettrici vengono elaborati e archiviati.

Le ragioni tipiche includono:

• Mantenere le misurazioni all'interno della rete locale
• Inviare telemetria a un server esistente
• Connettere i dati energetici con Home Assistant o Node-RED
• Creare dashboard e allarmi personalizzati
• Combinare i dati elettrici con tariffe, logica solare o di controllo del carico
• Operare in un sito con accesso a Internet limitato o inaffidabile

L'accesso cloud e locale non si escludono necessariamente a vicenda. L'architettura appropriata dipende dal fatto che il progetto necessiti dei report IAMMETER-Cloud, di una piattaforma locale, di un server di terze parti o di una combinazione.

4) Invio Dati a un Server di Terze Parti

4.1 TCP e TLS

IAMMETER può inviare i dati del contatore a un endpoint TCP o TLS.

Nel WebUI corrente:

1. Seleziona la modalità operativa TCP.
2. Inserisci l'indirizzo di destinazione.
3. Configura l'intervallo di upload.
4. Salva le impostazioni e verifica i dati sul server ricevente.

Per un server TCP, usa:

{domain-or-ip}:{port}

Esempio:

abc.com:12345

Per un server TLS, usa:

tls://{domain-or-ip}:{port}

Esempio:

tls://abc.com:12345

Il panorama generale del firmware corrente documenta un intervallo minimo di upload di 2 secondi. Conferma la versione del firmware e la capacità del server ricevente prima di selezionare un intervallo breve.

4.2 MQTT e MQTTS

IAMMETER può pubblicare telemetria direttamente a un broker MQTT semplice o utilizzare MQTTS per il trasporto crittografato su firmware supportato.

Nel WebUI corrente:

1. Seleziona la modalità operativa MQTT.
2. Inserisci l'indirizzo IP o dominio del broker e la porta usando il formato MQTT o MQTTS appropriato.
3. Inserisci nome utente e password del broker quando richiesta l'autenticazione.
4. Configura l'intervallo di upload.
5. Salva e verifica che i messaggi arrivino al broker.

Per MQTT semplice, inserisci l'indirizzo e la porta del broker senza prefisso mqtt://:

192.168.11.163:1883

Per MQTTS, includi il prefisso mqtts://:

mqtts://{mqtt-broker-address}:{port}

Esempio:

mqtts://broker.example.com:8883

Il supporto MQTTS documentato nell'aggiornamento firmware di novembre 2025 ha le seguenti limitazioni attuali:

• Supporta TLS 1.2 e versioni precedenti.
• Il caricamento di un certificato CA personalizzato non è supportato.
• La verifica del nome host non è supportata.
• I certificati lato client per l'autenticazione TLS reciproca non sono supportati.

Queste limitazioni sono importanti nella scelta di un broker e nella valutazione dei requisiti di sicurezza della distribuzione.

Il panorama generale del firmware corrente documenta un intervallo minimo di upload di 2 secondi.

Home Assistant MQTT Discovery è una funzione aggiuntiva di scoperta di Home Assistant; non è richiesta per ogni integrazione MQTT. Vedi:

• Guida all'Integrazione MQTT IAMMETER
• MQTT Discovery in Home Assistant

Modifica Remota di uploadInterval tramite MQTT/MQTTS

Con il firmware descritto nell'aggiornamento di novembre 2025, un contatore in modalità MQTT si sottoscrive automaticamente a:

device/{sn}/config

Pubblica il seguente JSON da un altro client MQTT per modificare l'intervallo di upload da remoto:

{"uploadInterval": 10}

Sostituisci 10 con l'intervallo desiderato in secondi e {sn} con il numero di serie del contatore nel topic.

Questa configurazione MQTT remota è diversa dal più vecchio metodo locale /api/uploadinterval conservato nella sezione Legacy.

4.3 HTTP e HTTPS

IAMMETER può inviare dati a un server HTTP/HTTPS personalizzato.

Nel WebUI corrente:

1. Seleziona la modalità operativa HTTP.
2. Inserisci l'indirizzo e la porta del server.
3. Configura l'intervallo di upload.
4. Salva e verifica le richieste sul server.

Il firmware corrente supporta sia la porta HTTPS predefinita che una porta HTTPS personalizzata.

Usa uno di questi formati:

• HTTP semplice senza porta esplicita: {address} — porta predefinita 80.
• HTTP semplice con porta personalizzata: {address}:{port}.
• HTTPS senza porta esplicita: https://{address} — porta predefinita 443.
• HTTPS con porta personalizzata: https://{address}:{port} — utilizza la porta specificata.

Il prefisso https:// seleziona HTTPS. La porta 443 non è più l'unica porta disponibile per HTTPS.

Esempi:

api.example.com
api.example.com:8080
https://api.example.com
https://api.example.com:8443

Vedi Il Nuovo Firmware Aggiunge MQTTS, Configurazione Remota e Porta HTTPS Personalizzata per le note di rilascio del firmware.

Per la gestione del payload lato server, vedi anche Integrare IAMMETER con un Server di Terze Parti.

5) Lettura Locale dei Dati tramite HTTP

Collega il contatore alla LAN e richiedi i dati dal suo indirizzo IP locale. Queste richieste non richiedono IAMMETER-Cloud.

Prova le API in modo interattivo: Apri IAMMETER Local API Explorer, inserisci l'indirizzo IP locale del contatore e seleziona la pagina di test dell'API WEM. L'esploratore in stile Swagger elenca le API locali disponibili e permette di inviare richieste di test direttamente dal browser. Il browser e il contatore IAMMETER devono essere sulla stessa LAN.

5.1 GET /api/monitorjson

Restituisce le misurazioni elettriche in tempo reale.

I dati standard includono valori come:

• Tensione
• Corrente
• Potenza attiva
• kWh in avanti/import
• kWh inverso/export
• Frequenza
• Fattore di potenza

Esempio di risposta:

{
  "method": "uploadsn",
  "mac": "B0F8933C4F94",
  "version": "i.75.97.9",
  "server": "em",
  "SN": "3E0BAF87",
  "Datas": [
    [220.0, 9.99, 2198, 11.337, 11.201, 49.99, 1.00],
    [222.5, 9.99, 1100, 11.039, 10.908, 49.99, 0.50],
    [263.5, 9.99, 1213, 10.975, 10.846, 49.99, 0.55]
  ]
}

Il numero di array di misurazione dipende dal modello di contatore e dal numero di canali.

Se la misurazione della potenza reattiva è abilitata su un modello/firmware supportato, il formato della risposta può contenere campi aggiuntivi. Vedi Formato dei Dati di Misurazione della Potenza Reattiva.

5.2 GET /api/monitor

Restituisce una risposta estesa in tempo reale che include anche informazioni Wi-Fi come:

• ssid — nome del punto di accesso connesso
• sig — potenza del segnale Wi-Fi

Usa questo endpoint quando un'integrazione necessita sia di misurazioni elettriche che dello stato Wi-Fi di base.

5.3 GET /api/wifidata

Restituisce informazioni sulla configurazione del firmware, del dispositivo e della rete.

Esempio:

{
  "version": "i.75.97.9",
  "SN": "3E0BAF87",
  "mac": "B0F8933C4F94",
  "type": "PM",
  "ssid": "example-wifi",
  "ip": "192.168.11.62",
  "netmask": "255.255.255.0",
  "gw": "192.168.11.1",
  "dns": "192.168.11.1",
  "dhcp": 1,
  "runMode": "tcp",
  "uploadinterval": 60
}

Non pubblicare risposte contenenti numeri di serie del dispositivo, indirizzi MAC, indirizzi interni o informazioni Wi-Fi a meno che i valori non siano stati resi anonimi.

6) Formato JSON tra le Modalità di Upload

IAMMETER utilizza una struttura JSON di misurazione di base coerente tra HTTP, TCP, MQTT e l'API locale. Questo riduce il lavoro necessario quando un sistema ricevente supporta più metodi di trasporto.

Il metodo di trasporto e l'involucro possono comunque influenzare il modo in cui un ricevitore si connette, autentica o incapsula un messaggio. Implementa il sistema ricevente secondo il formato documentato per la modalità selezionata.

• Definizione dei Dati JSON del Contatore Energetico IAMMETER

7) Modbus TCP

I contatori IAMMETER supportano Modbus TCP per l'integrazione diretta in LAN con client compatibili.

I client tipici includono:

• Home Assistant
• PLC
• Sistemi SCADA
• Gateway industriali
• Applicazioni Modbus personalizzate

Riferimenti:

• Panoramica Modbus TCP IAMMETER
• Panoramica dell'Integrazione con Home Assistant

Conferma il modello di contatore, il firmware, la definizione dei registri, l'intervallo di polling e il comportamento del client prima della distribuzione.

8) Scenari di Integrazione

9) Riepilogo dell'Interfaccia Corrente e Risorse

Risorse aggiuntive:

• Ultimo Firmware
• Nota sul Firmware MQTTS e Porta HTTPS Personalizzata
• Video Tutorial
• Definizione dei Dati JSON
• Panoramica Modbus TCP
• Sviluppa il Tuo Sistema
• Monitoraggio senza Accesso a Internet

Le API locali e i protocolli aperti di IAMMETER rendono possibile iniziare con il monitoraggio in tempo reale e aggiungere successivamente un EMS personalizzato, una dashboard self-hosted o un flusso di automazione.

10) Pagine del Firmware Legacy e Metodi di Configurazione

Il seguente materiale è conservato solo per contatori che eseguono ancora firmware precedente o per utenti che mantengono un'integrazione esistente. Per una nuova installazione, aggiorna all'ultimo firmware e utilizza il WebUI corrente dove l'opzione richiesta è disponibile.

10.1 Pagina delle Modalità Operative Legacy

Il firmware precedente utilizzava la seguente pagina di selezione della modalità operativa:

La disposizione e i nomi delle opzioni potrebbero non corrispondere al WebUI corrente mostrato in precedenza in questa guida.

10.2 Pagina TCP/TLS Legacy

Le integrazioni con firmware precedente possono fare riferimento a questa pagina di configurazione TCP/TLS e alla guida correlata:

• Guida all'Integrazione con Server di Terze Parti Legacy
• Video di Upload su Server Legacy

10.3 Pagina MQTT Legacy

La documentazione MQTT precedente utilizzava questa interfaccia di configurazione:

Per il flusso di lavoro corrente, utilizza le istruzioni del WebUI corrente più sopra in questo articolo e la Guida all'Integrazione MQTT aggiornata.

10.4 Pagina HTTP/HTTPS Legacy

Il firmware precedente utilizzava la seguente pagina di destinazione HTTP/HTTPS:

La guida all'integrazione legacy è conservata in Upload tramite HTTP/HTTPS.

In questo flusso di lavoro precedente, HTTPS era associato alla porta predefinita 443 e non richiedeva il prefisso https://. Il firmware corrente invece utilizza il prefisso https:// per selezionare HTTPS e supporta sia la porta predefinita 443 che una porta personalizzata specificata esplicitamente.

10.5 API di Configurazione Legacy

Le seguenti chiamate API locali apparivano nei flussi di lavoro di configurazione precedenti. Nel firmware corrente, le impostazioni corrispondenti dovrebbero normalmente essere configurate tramite il WebUI quando l'opzione è disponibile.

/api/uploadinterval?x=<seconds>

Metodo legacy per impostare l'intervallo di upload non-Cloud.

/api/mqtt

Metodo legacy per configurare le credenziali MQTT.

/api/netmetring

Metodo legacy per abilitare o disabilitare la modalità Net Energy Metering.

• Riferimento Net Energy Metering

/api/ctcratio

Metodo legacy per applicare il moltiplicatore documentato della Fase-C in specifici scenari split-phase o bilanciati.

• Riferimento CTC Ratio

/api/reactive

Metodo legacy per abilitare o disabilitare la misurazione della potenza reattiva e dell'energia reattiva su firmware/modelli supportati.

• Riferimento Potenza Reattiva

/api/ratio — solo WEM3046T

WEM3046T utilizza TA esterni con uscite secondarie da 5 A. Le istruzioni di configurazione precedenti impostavano il rapporto TA con:

/api/ratio?x={ct_ratio}

Esempio:

/api/ratio?x=400

Questo endpoint è specifico per WEM3046T e non è valido per altri modelli IAMMETER. Per il firmware corrente, utilizza la configurazione WebUI del modello quando disponibile.

Materiale legacy conservato per riferimento; le installazioni correnti dovrebbero seguire il WebUI dell'ultimo firmware.