Il template SolaX HAC Cloud API collega TapHome a una wallbox SolaX X1-HAC o X3-HAC per veicoli elettrici tramite l’API del SolaX Developer Portal (OpenAPI). L’autore del template indica anche i caricatori A1-HAC e C1/C3-HAC. TapHome non comunica direttamente con il caricatore: il caricatore invia i dati a SolaXCloud tramite Wi-Fi, LAN o 4G, e TapHome li legge dal cloud SolaX tramite HTTPS ogni 60 secondi. I comandi di scrittura (modalità di funzionamento, avvio e arresto, blocco, limite di corrente) tornano al caricatore attraverso il cloud nello stesso modo.
Prima di importare il template devono essere soddisfatte due condizioni. Il caricatore deve essere online in un account SolaXCloud, e per questo account serve un’applicazione nel SolaX Developer Portal che fornisce Client ID e Client Secret. Se il caricatore lavora insieme a un inverter SolaX, nello stesso progetto TapHome può funzionare anche il template SolaX Inverter (Cloud API). Questo utilizza la precedente API di monitoraggio SolaxCloud con un proprio token.
Collegamento del caricatore a SolaXCloud
Connessione di rete
Il caricatore offre tre modi per connettersi a internet. Tutti utilizzano DHCP, quindi il router assegna l’indirizzo IP automaticamente.
- Wi-Fi: solo 2,4 GHz (802.11 b/g/n). Le reti a 5 GHz non sono supportate.
- Ethernet (LAN): la porta RJ45 LAN (/ DI). Ethernet utilizza i pin 1, 2, 3 e 6 (TX+, TX−, RX+, RX−). Se serve solo Ethernet, lasciare scollegati gli altri pin. Con una connessione LAN la configurazione Wi-Fi può essere saltata.
- 4G: solo per i modelli con “4G” nel nome (ad esempio X3-HAC-22P-B4G). Un tecnico autorizzato deve installare una nano SIM che supporti Cat-M, NB-IoT o GSM. SolaX consiglia almeno 100 MB di dati al mese negli scenari Solar e Standard.

Il cavo Ethernet verso il caricatore deve essere protetto dai fulmini. Se servono sia la LAN sia l’ingresso di segnale DI, crimpare i pin 1, 2, 3 e 6 per Ethernet e i pin 4, 5 e 8 per DI, quindi unire i due cavi con il connettore di giunzione RJ45 fornito con il caricatore.
La connessione 4G si configura nell’app SolaXCloud in modalità locale: aprire Dongle, poi il pulsante delle impostazioni, impostare Device Networking Mode su 4G, inserire l’APN dell’operatore e scegliere il tipo di rete supportato dalla SIM.
Aggiunta del caricatore nell’app SolaXCloud
- Installare l’app SolaXCloud dall’App Store o da Google Play e registrare un account con un indirizzo e-mail o un numero di telefono e un codice di verifica.
- Al primo accesso, creare un impianto (plant): consentire l’accesso alla posizione, inserire il nome dell’impianto e completare le altre impostazioni.
- Aggiungere il caricatore scansionando o digitando il Registration No. riportato sulla targhetta. I caricatori aggiunti in seguito passano dalla pagina Device, dall’icona +, poi da Add Device o Scan.
- Se il caricatore si connette tramite Wi-Fi, inserire il nome e la password della rete Wi-Fi.

La targhetta riporta due numeri diversi. Il Registration No. serve per aggiungere il caricatore nell’app e per l’accesso locale. Il SN (numero di serie del dispositivo) è quello che il template TapHome richiede come DeviceSN. L’app mostra l’SN del dispositivo nella pagina Basic information del caricatore (toccare la parte superiore della pagina Details del caricatore). È riportato anche nel Developer Portal in Device > Device List.
Riconnessione Wi-Fi e accesso locale
Se il caricatore va offline, aprire la pagina Device nell’app, toccare la scheda del caricatore contrassegnata come offline e scegliere Reconfigure. Quindi inserire di nuovo la rete a 2,4 GHz e la password.

Se la riconfigurazione non riesce, c’è un secondo modo. Collegare un telefono o un portatile alla rete Wi-Fi propria del caricatore, che prende il nome dal suo Registration No. (Wifi_XC…). Quindi aprire http://192.168.10.10/ in un browser e accedere come admin, con il Registration No. come password. La modalità locale nell’app (More > Local Access, oppure Service > Application > Local Access da utente connesso) utilizza la stessa rete.
Il caricatore spegne automaticamente la propria rete Wi-Fi locale un’ora dopo essersi collegato correttamente alla rete. Per usare l’accesso locale in seguito, riattivare la rete nell’app in Network > Local Access.
Scenario di applicazione e modalità di carica
Il caricatore funziona in uno dei tre scenari di applicazione, scelto nell’app in Advanced setting > Application scene:
- Solar (predefinito): sono disponibili le modalità di carica Green, Eco e Fast. Green ed Eco richiedono che il caricatore comunichi con l’inverter, oppure con un CT (trasformatore di corrente) o un contatore sul punto di connessione alla rete, per conoscere il surplus fotovoltaico.
- Standard: il caricatore si limita ad avviare e arrestare la carica. Green ed Eco non esistono in questo scenario.
- OCPP: il caricatore è gestito tramite un server OCPP, e l’app SolaXCloud nasconde la selezione della modalità.

L’inverter si collega alla porta COM1-S- (A1/B1). Un contatore o un CT si collega alla porta COM2-M- (A2/B2, ingressi CT sugli altri pin). Il livello della corrente di carica per la modalità Green (3 A o 6 A) e per la modalità Eco (6, 10, 16, 20 o 25 A) si imposta nell’app in Details > Function Control > Charge Level. Sui modelli da 11 kW, Eco offre solo 6 A e 10 A. La carica Green ed Eco richiede inoltre un veicolo conforme alla norma IEC 61851.
Configurazione dell’accesso API nel SolaX Developer Portal
- Accedere al SolaX Developer Portal e aprire Quick Start o Application.
- Creare un’applicazione per l’impianto SolaXCloud che contiene il caricatore. L’applicazione deve avere almeno un impianto autorizzato.
- Nella scheda Authorization dell’applicazione, copiare Client ID e Client Secret.
- In Service API > Authorize, abilitare i servizi di monitoraggio Data Monitoring Service (
API_Telemetry_V2) e Information Access Service (API_Info_V2). Abilitare anche il servizio di controllo del caricatore EV, necessario per il selettore della modalità di funzionamento e per le azioni di servizio. Il solo monitoraggio funziona anche senza. - Trovare il numero di serie del caricatore in Device > Device List. È lo stesso SN dell’app SolaXCloud.
Il template è impostato sull’host API europeo
openapi-eu.solaxcloud.com. SolaX gestisce host separati per la Cina (openapi-cn.solaxcloud.com) e per l’India (openapi-in.solaxcloud.com). La regione dell’account è indicata nel Developer Portal. Così come viene importato, il template non funziona con un’applicazione di un’altra regione.
Parametri di importazione
In TapHome, importare il template e compilare i tre parametri seguenti. Tutto il resto (token, polling, nuovi tentativi) è gestito dal modulo.
| Parametro | Descrizione | Dove trovarlo |
|---|---|---|
ClientId | Client ID dell’applicazione nel Developer Portal | Application > Authorization |
ClientSecret | Client Secret della stessa applicazione | Application > Authorization |
DeviceSN | Numero di serie del caricatore (non il Registration No.) | Developer Portal Device > Device List, oppure Basic information nell’app SolaXCloud |
Usare una coppia Client ID e Client Secret per un solo client. Ogni applicazione ha un solo token di accesso valido, quindi una nuova richiesta di token annulla quello precedente. Una seconda istanza del template TapHome, o un altro strumento che interroga con le stesse credenziali, continua ad annullare il token di questo template. Per un secondo caricatore, o per un altro sistema, creare un’applicazione separata nel Developer Portal.
Funzionalità del dispositivo
I nomi dei dispositivi nel template sono in slovacco. Ognuno è riportato qui sotto con il suo nome nell’app tra parentesi.
Potenza ed energia di carica
Potenza di carica (Nabíjací výkon) è un contatore elettrico. Mostra la potenza di carica attuale in kW e l’energia caricata totale in kWh. I suoi attributi di servizio mostrano l’energia della sessione in corso (Energia aktuálnej relácie [kWh]), le correnti di fase L1, L2 e L3 (Prúd L1 [A], Prúd L2 [A], Prúd L3 [A]) e la corrente monofase (Jednofázový prúd [A]).
Stato di carica e codice di stato
- Carica in corso (
Nabíjanie prebieha) è un contatto. È attivo (Nabíja) solo mentre il caricatore segnala lo stato Charging. In ogni altro stato è disattivo (Nenabíja), inclusi Suspended EV e Suspended EVSE. - Stato del caricatore (
Stav nabíjačky) è il codice di stato grezzo del caricatore:
| Codice | Stato | Codice | Stato |
|---|---|---|---|
| 0 | Available | 7 | Suspended EV |
| 1 | Preparing | 8 | Suspended EVSE |
| 2 | Charging | 9 | Update |
| 3 | Finishing | 10 | Card Activation |
| 4 | Faulted | 11 | Start Delay |
| 5 | Unavailable | 12 | Charge Pause |
| 6 | Reserved | 13 | Stopping |
Modalità di funzionamento
Modalità di funzionamento (Pracovný režim) è un selettore multi-valore con quattro valori: STOP, FAST, ECO e GREEN. Legge la modalità attuale del caricatore e ne imposta una nuova da TapHome. ECO e GREEN si comportano come descritto sopra per lo scenario Solar e dipendono dalla comunicazione del caricatore con l’inverter o con il contatore.
Azioni di servizio
Il dispositivo di stato del caricatore dispone di quattro azioni di servizio:
- Avvia carica (
Spustiť nabíjanie) e Arresta carica (Zastaviť nabíjanie). - Blocca / rendi disponibile (
Zamknúť / sprístupniť nabíjačku), con i valori Blocca (Zamknúť) e Rendi disponibile (Sprístupniť). - Imposta limite di corrente (
Nastaviť limit prúdu): 6–32 A sui modelli da 7 kW e 22 kW, 6–16 A sul modello da 11 kW.
I comandi sono asincroni. La risposta “OK, príkaz odoslaný” significa che il cloud SolaX ha accettato il comando, non che il caricatore lo abbia già eseguito. Il risultato compare nelle letture dei cicli successivi.
Cronologia delle carte e delle sessioni nei grafici
- Carta RFID (
RFID karta) mostra il numero della carta che ha avviato la sessione, oppure 0 quando non si usa alcuna carta. - Tempo di carica della sessione (
Čas nabíjania relácie) mostra la durata della sessione in corso in minuti.
L’API SolaX non fornisce una cronologia delle carte. Con i grafici (Charts) abilitati su queste due variabili, TapHome costruisce da sé la cronologia: quale carta ha caricato, quando e per quanto tempo, con una risoluzione di 60 secondi. Le carte vengono usate solo quando la modalità di attivazione del caricatore è impostata su RFID nell’app SolaXCloud (Charger setting > Activation mode). La modalità predefinita Plug & Charge non usa carte.
Risoluzione dei problemi
Nessun dato o errore di autenticazione sul modulo
- Verificare che il caricatore sia online nell’app SolaXCloud. L’icona del server sul display del caricatore indica se è connesso a SolaXCloud.
- Confrontare
ClientIdeClientSecretcon la scheda Authorization. Un secret rigenerato nel portale deve essere inserito di nuovo. - Verificare che
DeviceSNsia il numero di serie del caricatore, non il Registration No. - Verificare che l’applicazione abbia un impianto autorizzato con il caricatore e che i servizi di monitoraggio siano autorizzati. Un codice API 10403 significa che il servizio API non ha diritti di accesso. Un codice 10500 significa che l’applicazione non ha l’autorizzazione per i dati di questo dispositivo.
- I codici 10400 e 10402 indicano che il token non è valido. Il modulo richiede un nuovo token e ripete la lettura nello stesso ciclo. Se il modulo segnala ancora un errore con il testo “aj po obnove tokenu” (“anche dopo il rinnovo del token”), le credenziali o i servizi autorizzati sono errati.
Le letture smettono di cambiare
I codici 10405 e 10406 indicano che è stato raggiunto il limite di chiamate API. Il modulo mostra un avviso e mantiene i valori dell’ultimo ciclo riuscito. Il template effettua una richiesta al minuto. Altri strumenti che leggono lo stesso account SolaX consumano lo stesso limite.
La modalità di funzionamento o le azioni non funzionano
- Un’azione di servizio restituisce il testo
SolaX API kód <code>quando il cloud rifiuta il comando. Un codice 10403 (nessun diritto di accesso all’interfaccia) può significare che il servizio di controllo del caricatore EV non è autorizzato per l’applicazione. - ECO e GREEN funzionano solo nello scenario Solar e richiedono una connessione funzionante con l’inverter o con il CT/contatore. Nello scenario Standard il caricatore si limita ad avviare e arrestare la carica.
Installazioni commerciali
Il template legge il caricatore come parte di un impianto residenziale (businessType=1). Secondo l’autore del template, un caricatore in un impianto commerciale e industriale richiede il valore 4, e i suoi valori di potenza sono allora in kW anziché in W.
