TapHome

SolaX Inverter (Cloud API)

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 03. 2026
SolaX Inverter (Cloud API)

Il template SolaX Cloud API collega TapHome a qualsiasi inverter SolaX attraverso la piattaforma di monitoraggio SolaxCloud. A differenza del template SolaX Hybrid X1/X3 Gen 4, che utilizza Modbus RTU su RS-485, questa integrazione cloud non richiede alcun cablaggio fisico verso l’inverter. TapHome interroga i server SolaX Cloud via HTTPS e riceve dati in tempo reale in formato JSON.

Il template supporta tutti i tipi di inverter SolaX (23 modelli nelle serie X1, X3, A1 e J1) e fornisce 11 dispositivi di monitoraggio che coprono uscita AC, stato della batteria, flusso di energia in rete e produzione FV per singolo ingresso MPPT. Gli unici requisiti sono un account SolaxCloud, un dongle di comunicazione connesso a internet (Pocket WiFi, LAN o 4G) e il token API.

Configurazione

Configurazione dell’account SolaxCloud

L’inverter deve essere registrato e online su SolaxCloud. Un modulo di comunicazione (Pocket WiFi, LAN o dongle 4G) deve essere installato sull’inverter e connesso a internet.

Ottenere il token API (tokenID)
  1. Accedi a SolaxCloud su www.solaxcloud.com
  2. Nella barra laterale sinistra, vai a Service > Third-party ecosystem (o la sezione API)
  3. Copia il tokenID visualizzato — si tratta di una stringa di 23 o 24 caratteri

Il token è gratuito per tutti gli utenti registrati SolaxCloud.

Trovare il numero di registrazione (sn)

Il parametro sn è il numero di registrazione del dongle di comunicazione — non il numero di serie dell’inverter. Questa è una fonte comune di confusione.

Dove trovarlo:

  • Sul dongle — stampato sull’etichetta del modulo Pocket WiFi / LAN / 4G (codice a barre o codice QR)
  • In SolaxCloud — vai a Device > Inverter e cerca la colonna Registration No. nella tabella
Parametri di importazione

Quando importi il template in TapHome, inserisci:

  • Token ID — il tokenID da SolaxCloud
  • Registration No. — il numero di serie a 10 caratteri del dongle di comunicazione
Dipendenza da internet

Questa è un’integrazione esclusivamente cloud. Tutti i dati transitano attraverso i server SolaX Cloud (www.solaxcloud.com:9443). Il template non funziona senza una connessione internet attiva sia sulla CCU TapHome che sul dongle di comunicazione dell’inverter.

Per gli utenti che preferiscono la comunicazione locale senza dipendenza dal cloud, il template SolaX Hybrid X1/X3 Gen 4 (Modbus RTU) fornisce comunicazione diretta RS-485 con gli inverter ibridi Gen 4.

Funzionalità dei dispositivi

Uscita AC e produzione energetica

Il contatore AC Output misura la produzione totale di energia AC (yieldtotal in kWh) e la potenza di uscita in tempo reale (acpower in W, convertita in kW). Un attributo di servizio riporta la produzione giornaliera (yieldtoday in kWh) che si azzera a mezzanotte.

Monitoraggio della batteria
  • Battery SOC — stato di carica della batteria in percentuale dal campo soc. Il valore è diviso per 100 per l’intervallo di ingresso analogico TapHome 0–1 (es. 85% → 0,85). Questo è il dispositivo interrogato più frequentemente con un intervallo di 2,5 secondi
  • Battery Power — potenza istantanea di carica/scarica della batteria in watt. Valori positivi indicano carica (da FV o rete), valori negativi indicano scarica verso il carico
Potenza di rete e misurazione dell’energia

Tre dispositivi coprono il flusso di potenza della rete:

  • Grid Power — potenza di rete bidirezionale grezza in watt. Positivo = esportazione in rete, negativo = importazione dalla rete
  • PV From Grid — contatore che traccia l’energia consumata dalla rete. Consumo totale (consumeenergy in kWh) e potenza di importazione in tempo reale (estratta da feedinpower quando negativo, convertita in kW)
  • PV To Grid — contatore che traccia l’energia esportata in rete. Energia totale immessa in rete (feedinenergy in kWh) e potenza di esportazione in tempo reale (estratta da feedinpower quando positivo, convertita in kW)
Monitoraggio della produzione FV

Il template fornisce cinque dispositivi per la produzione FV:

  • PV Production (Total) — sensore calcolato che somma la potenza DC da tutti i 4 ingressi MPPT. Null-safe — gli inverter con meno di 4 stringhe restituiscono null per gli MPPT non utilizzati, che la formula tratta come zero
  • PV Production (MPPT 1–4) — letture individuali della potenza DC per ogni ingresso stringa FV in watt
Diagnostica a livello di modulo

Lo script del modulo verifica lo stato dell’inverter ad ogni interrogazione e segnala i problemi:

  • Lo stato 100 (Wait Mode) e 110 (Standby) generano avvisi in TapHome
  • Lo stato 103 (Fault Mode) e 104 (Permanent Fault Mode) generano errori
  • Se la risposta API indica un errore, il messaggio dal campo exception viene segnalato

Due attributi di servizio sono disponibili sul modulo:

  • Inverter status — mappa i codici di stato 100–113 su nomi leggibili (Wait Mode, Check Mode, Normal Mode, Fault Mode, Permanent Fault Mode, Update Mode, EPS Check Mode, EPS Mode, Self-Test Mode, Idle Mode, Standby Mode, Pv Wake Up Bat Mode, Gen Check Mode, Gen Run Mode)
  • Inverter type — mappa i codici tipo 1–23 su nomi dei modelli (X1-LX, X-Hybrid, X1-Boost/Air/Mini, X3-Hybrid-G4 ecc.)
Funzionalità aggiuntive

L’API SolaX Cloud fornisce anche la potenza AC del Meter 2 (feedinpowerM2), la potenza EPS (Emergency Power Supply) per tre fasi (peps1–peps3), il timestamp di caricamento dati, il numero di serie dell’inverter e lo stato della batteria. Questi possono essere aggiunti in un futuro aggiornamento del template.

Risoluzione dei problemi

L’API restituisce un errore o nessun dato
  1. Verifica che l’inverter sia online su SolaxCloud — accedi al portale web e controlla lo stato del dispositivo
  2. Conferma che il tokenID sia corretto e non sia stato rigenerato (i vecchi token diventano non validi)
  3. Assicurati che il parametro sn sia il numero di registrazione del dongle di comunicazione, non il numero di serie dell’inverter
  4. Verifica che il dongle di comunicazione abbia una connessione internet attiva
Letture obsolete o ritardate

L’API SolaX Cloud restituisce i dati più recenti caricati dal dongle di comunicazione. La freschezza dei dati dipende dall’intervallo di caricamento del dongle (tipicamente ogni 5 minuti). Il template interroga l’API ogni 20 secondi, ma i dati sottostanti possono aggiornarsi meno frequentemente.

Errori di limite API

L’API consente un massimo di 10 richieste al minuto e 10.000 richieste al giorno. Il template interroga a intervalli di 20 secondi (circa 3 richieste al minuto), entro i limiti. Se più sistemi (TapHome, Home Assistant, altri strumenti) condividono lo stesso tokenID, il tasso combinato di richieste potrebbe superare il limite.

L’API SolaX Cloud richiede una connessione internet attiva e dipende dalla disponibilità dei server SolaX Cloud. Durante interruzioni del cloud o problemi di connettività, il template non riceverà dati aggiornati. Per installazioni che richiedono un controllo locale garantito, considera il template Modbus RTU.

Dispositivi disponibili

SolaX Inverter Modulo
Attributi di servizio
Stato dell'inverterModalità operativa attuale — Wait, Check, Normal, Fault, Permanent Fault, Update, EPS Check, EPS, Self-Test, Idle, Standby, Pv Wake Up Bat, Gen Check, Gen Run
Tipo di inverterModello di inverter collegato — identifica la serie SolaX (X1, X3, A1, J1) e la generazione installata
Variabili personalizzate
tokenID (string)SolaX Cloud API token ID (obtain from your SolaX Cloud account API page)
sn (string)Serial number of the SolaX communication module (Registration No.)

Solax Inverter

Lettura (modulo)
var response := sendhttprequest("/proxy/api/getRealtimeInfo.do?tokenId="+tokenID+"&sn="+sn);

if parsejson(response.Content, "success")
	json := parsejson(response.Content, "result", 1);
	
	var statusCode := parsejson(json,"inverterStatus");
	if statusCode = "100"
	  addwarning("Inverter in waiting - Check DC");
	end
	if statusCode =  "103"
	  adderror("Inverter in fault mode");
	end
	if statusCode = "104"
	  adderror("Inverter in permanent fault mode");
	end
	if statusCode = "110"
	  addwarning("Inverter in standby mode");
	end
else
 	adderror(parsejson(response.Content, "exception"));
end
Attributi di servizio
Inverter status
var statusCode := parsejson(json,"inverterStatus");

IF(statusCode = "100",return("Wait Mode"));
IF(statusCode = "101",return("Check Mode"));
IF(statusCode = "102",return("Normal Mode"));
IF(statusCode = "103",return("Fault Mode"));
IF(statusCode = "104",return("Permanent Fault Mode"));
IF(statusCode = "105",return("Update Mode"));
IF(statusCode = "106",return("EPS Check Mode"));
IF(statusCode = "107",return("EPS Mode"));
IF(statusCode = "108",return("Self-Test Mode"));
IF(statusCode = "109",return("Idle Mode"));
IF(statusCode = "110",return("Standby Mode"));
IF(statusCode = "111",return("Pv Wake Up Bat Mode"));
IF(statusCode = "112",return("Gen Check Mode"));
IF(statusCode = "113",return("Gen Run Mode"));
Inverter type
var type := parsejson(json,"inverterType");

IF(type = "1",return("X1-LX"));
IF(type = "2",return("X-Hybrid"));
IF(type = "3",return("X1-Hybiyd/Fit"));
IF(type = "4",return("X1-Boost/Air/Mini"));
IF(type = "5",return("X3-Hybiyd/Fit"));
IF(type = "6",return("X3-20K/30K"));
IF(type = "7",return("X3-MIC/PRO"));
IF(type = "8",return("X1-Smart"));
IF(type = "9",return("X1-AC"));
IF(type = "10",return("A1-Hybrid"));
IF(type = "11",return("A1-Fit"));
IF(type = "12",return("A1-Grid"));
IF(type = "13",return("J1-ESS"));
IF(type = "14",return("X3-Hybrid-G4"));
IF(type = "15",return("X1-Hybrid-G4"));
IF(type = "16",return("X3-MIC/PRO-G2"));
IF(type = "17",return("X1-SPT"));
IF(type = "18",return("X1-Boost/Mini-G4"));
IF(type = "19",return("A1-HYB-G2"));
IF(type = "20",return("A1-AC-G2"));
IF(type = "21",return("A1-SMT-G2"));
IF(type = "22",return("X3-FTH"));
IF(type = "23",return("X3-MGA-G2"));
Uscita AC Contatore elettrico Solo lettura

Produzione di energia AC totale e giornaliera (kWh) con potenza di uscita in tempo reale (kW)

numeric Unità: kWh / kW JSON parsejson()
Attributi di servizio
Inverter.AC.energy.out.daily [kWh]Produzione giornaliera di energia AC — si azzera a mezzanotte

Uscita AC

Lettura consumo totale
parsejson(json, "yieldtotal", 1)
Lettura domanda
parsejson(json, "acpower", 1) / 1000
Attributi di servizio
Inverter.AC.energy.out.daily [kWh]
parsejson(json, "yieldtoday", 1)
SOC batteria Ingresso analogico Solo lettura

Stato di carica della batteria in percentuale — 0% (vuota) a 100% (piena)

numeric Unità: % JSON parsejson()

SOC batteria

Lettura livello ingresso
parsejson(json, "soc", 1) / 100
Potenza batteria Variabile Solo lettura

Potenza istantanea della batteria in watt — positiva in carica, negativa in scarica

numeric Unità: W JSON parsejson()

Potenza batteria

Lettura
parsejson(json,"batPower",1)
Energia dalla rete Contatore elettrico Solo lettura

Energia consumata dalla rete — consumo totale (kWh) e potenza di importazione in tempo reale (kW)

numeric Unità: kWh / kW JSON parsejson()

Energia dalla rete

Lettura consumo totale
parsejson(json, "consumeenergy", 1)
Lettura domanda
var power := parsejson(json, "feedinpower", 1);
if(power < 0, power * -1, 0) / 1000
Potenza di rete Variabile Solo lettura

Potenza di rete bidirezionale in watt — positiva in esportazione, negativa in importazione

numeric Unità: W JSON parsejson()

Potenza di rete

Lettura
parsejson(json, "feedinpower", 1)
Produzione FV (totale) Variabile Solo lettura

Potenza DC combinata da tutti gli ingressi MPPT — somma automaticamente le stringhe disponibili

numeric Unità: W JSON parsejson()

Produzione FV (totale)

Lettura
var PV1 := parsejson(json,"powerdc1",1);
var PV2 := parsejson(json,"powerdc2",1);
var PV3 := parsejson(json,"powerdc3",1);
var PV4 := parsejson(json,"powerdc4",1);

if(isnull(PV1), 0, PV1) +
if(isnull(PV2), 0, PV2) +
if(isnull(PV3), 0, PV3) +
if(isnull(PV4), 0, PV4)
Produzione FV (MPPT 1) Variabile Solo lettura
numeric Unità: W JSON parsejson()

Produzione FV (MPPT 1)

Lettura
parsejson(json,"powerdc1",1)
Produzione FV (MPPT 2) Variabile Solo lettura
numeric Unità: W JSON parsejson()

Produzione FV (MPPT 2)

Lettura
parsejson(json,"powerdc2",1)
Produzione FV (MPPT 3) Variabile Solo lettura
numeric Unità: W JSON parsejson()

Produzione FV (MPPT 3)

Lettura (modulo)
parsejson(json,"powerdc3",1)
Produzione FV (MPPT 4) Variabile Solo lettura
numeric Unità: W JSON parsejson()

Produzione FV (MPPT 4)

Lettura (modulo)
parsejson(json,"powerdc4",1)
Energia in rete Contatore elettrico Solo lettura

Energia esportata in rete — energia totale immessa (kWh) e potenza di esportazione in tempo reale (kW)

numeric Unità: kWh / kW JSON parsejson()

Energia in rete

Lettura consumo totale
parsejson(json, "feedinenergy", 1)
Lettura domanda
var power := parsejson(json, "feedinpower", 1);
if(power > 0, power, 0) / 1000
Connessione: Packet Parser → HTTP
Possibili miglioramenti (7)
  • Meter 2 AC Power — Inverter.Meter2.AC.power.total, 1 W. Secondary meter power reading — available for dual-meter setups
  • EPS Phase 1 Power — Inverter.AC.EPS.power.R, 1 W. Emergency Power Supply output phase R
  • EPS Phase 2 Power — Inverter.AC.EPS.power.S, 1 W. Emergency Power Supply output phase S
  • EPS Phase 3 Power — Inverter.AC.EPS.power.T, 1 W. Emergency Power Supply output phase T
  • Upload Time — Last data upload timestamp from inverter to SolaX Cloud. Useful for stale-data detection
  • Inverter Serial Number — Serial number of the inverter hardware (different from communication module SN)
  • Battery Status — Battery status code with mapped states. Documented in HA integration but not in official API V6.1 PDF

Fonti