TapHome

SolaX Inverter (Cloud API)

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 03. 2026
SolaX Inverter (Cloud API)

Szablon SolaX Cloud API łączy TapHome z dowolnym falownikiem SolaX za pośrednictwem platformy monitorującej SolaxCloud. W odróżnieniu od szablonu SolaX Hybrid X1/X3 Gen 4, który wykorzystuje Modbus RTU przez RS-485, ta integracja chmurowa nie wymaga żadnego fizycznego okablowania do falownika. TapHome odpytuje serwery SolaX Cloud przez HTTPS i otrzymuje dane w czasie rzeczywistym w formacie JSON.

Szablon obsługuje wszystkie typy falowników SolaX (23 modele z serii X1, X3, A1 i J1) i udostępnia 11 urządzeń monitorujących obejmujących wyjście AC, stan baterii, przepływ energii sieciowej i produkcję FV na poszczególnych wejściach MPPT. Jedynymi wymaganiami są konto SolaxCloud, dongle komunikacyjny z dostępem do internetu (Pocket WiFi, LAN lub 4G) oraz token API.

Konfiguracja

Konfiguracja konta SolaxCloud

Falownik musi być zarejestrowany i online na SolaxCloud. Na falowniku musi być zainstalowany moduł komunikacyjny (Pocket WiFi, LAN lub dongle 4G) podłączony do internetu.

Uzyskanie tokenu API (tokenID)
  1. Zaloguj się do SolaxCloud na www.solaxcloud.com
  2. W lewym panelu bocznym przejdź do Service > Third-party ecosystem (lub sekcji API)
  3. Skopiuj wyświetlony tokenID — jest to ciąg 23 lub 24 znaków

Token jest bezpłatny dla wszystkich zarejestrowanych użytkowników SolaxCloud.

Znajdowanie numeru rejestracyjnego (sn)

Parametr sn to numer rejestracyjny dongla komunikacyjnego — nie numer seryjny falownika. To częste źródło pomyłek.

Gdzie go znaleźć:

  • Na donglu — wydrukowany na etykiecie modułu Pocket WiFi / LAN / 4G (kod kreskowy lub kod QR)
  • W SolaxCloud — przejdź do Device > Inverter i znajdź kolumnę Registration No. w tabeli
Parametry importu

Podczas importowania szablonu w TapHome wprowadź:

  • Token ID — tokenID z SolaxCloud
  • Registration No. — 10-znakowy numer seryjny dongla komunikacyjnego
Zależność od internetu

To jest wyłącznie chmurowa integracja. Wszystkie dane przepływają przez serwery SolaX Cloud (www.solaxcloud.com:9443). Szablon nie będzie działać bez aktywnego połączenia internetowego zarówno na TapHome CCU, jak i na donglu komunikacyjnym falownika.

Dla użytkowników preferujących komunikację lokalną bez zależności od chmury, szablon SolaX Hybrid X1/X3 Gen 4 (Modbus RTU) zapewnia bezpośrednią komunikację RS-485 z falownikami hybrydowymi Gen 4.

Możliwości urządzeń

Wyjście AC i produkcja energii

Licznik energii AC Output mierzy całkowitą produkcję energii AC (yieldtotal w kWh) i moc wyjściową w czasie rzeczywistym (acpower w W, przeliczoną na kW). Atrybut serwisowy raportuje dzienny uzysk (yieldtoday w kWh), który resetuje się o północy.

Monitoring baterii
  • Battery SOC — stan naładowania baterii w procentach z pola soc. Wartość jest dzielona przez 100 dla zakresu wejścia analogowego TapHome 0–1 (np. 85% → 0,85). To najszybciej odpytywane urządzenie z interwałem 2,5 sekundy
  • Battery Power — chwilowa moc ładowania/rozładowywania baterii w watach. Wartości dodatnie oznaczają ładowanie (z FV lub sieci), wartości ujemne oznaczają rozładowywanie do obciążenia
Moc sieciowa i pomiar energii

Trzy urządzenia obejmują przepływ mocy sieciowej:

  • Grid Power — surowa dwukierunkowa moc sieciowa w watach. Dodatnia = eksport do sieci, ujemna = pobór z sieci
  • PV From Grid — licznik śledzący energię pobraną z sieci. Całkowite zużycie (consumeenergy w kWh) i moc poboru w czasie rzeczywistym (wyodrębniona z feedinpower przy wartości ujemnej, przeliczona na kW)
  • PV To Grid — licznik śledzący energię wyeksportowaną do sieci. Całkowita energia oddana do sieci (feedinenergy w kWh) i moc eksportu w czasie rzeczywistym (wyodrębniona z feedinpower przy wartości dodatniej, przeliczona na kW)
Monitoring produkcji FV

Szablon udostępnia pięć urządzeń do monitoringu produkcji FV:

  • PV Production (Total) — obliczany sensor sumujący moc DC ze wszystkich 4 wejść MPPT. Null-safe — falowniki z mniej niż 4 stringami zwracają null dla nieużywanych MPPT, co formuła traktuje jako zero
  • PV Production (MPPT 1–4) — indywidualne odczyty mocy DC dla każdego wejścia stringa FV w watach
Diagnostyka na poziomie modułu

Główny skrypt modułu sprawdza stan falownika przy każdym odpytaniu i zgłasza problemy:

  • Status 100 (Wait Mode) i 110 (Standby) wyzwalają ostrzeżenia w TapHome
  • Status 103 (Fault Mode) i 104 (Permanent Fault Mode) wyzwalają błędy
  • Jeśli odpowiedź API wskazuje na błąd, komunikat z pola exception jest raportowany

Na module dostępne są dwa atrybuty serwisowe:

  • Inverter status — mapuje kody stanu 100–113 na czytelne nazwy (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 — mapuje kody typów 1–23 na nazwy modeli (X1-LX, X-Hybrid, X1-Boost/Air/Mini, X3-Hybrid-G4 itd.)
Dodatkowe możliwości

API SolaX Cloud udostępnia również moc AC Meter 2 (feedinpowerM2), moc EPS (Emergency Power Supply) dla trzech faz (peps1–peps3), znacznik czasu przesłania danych, numer seryjny falownika i stan baterii. Mogą one zostać dodane w przyszłej aktualizacji szablonu.

Rozwiązywanie problemów

API zwraca błąd lub brak danych
  1. Sprawdź, czy falownik jest online na SolaxCloud — zaloguj się na portalu i zweryfikuj stan urządzenia
  2. Potwierdź, że tokenID jest prawidłowy i nie został wygenerowany ponownie (stare tokeny stają się nieważne)
  3. Upewnij się, że parametr sn to numer rejestracyjny dongla komunikacyjnego, a nie numer seryjny falownika
  4. Sprawdź, czy dongle komunikacyjny ma aktywne połączenie internetowe
Nieaktualne lub opóźnione odczyty

API SolaX Cloud zwraca najnowsze dane przesłane przez dongle komunikacyjny. Świeżość danych zależy od interwału przesyłania dongla (zazwyczaj co 5 minut). Szablon odpytuje API co 20 sekund, ale dane bazowe mogą aktualizować się rzadziej.

Błędy limitów API

API pozwala na maksymalnie 10 zapytań na minutę i 10 000 zapytań dziennie. Szablon odpytuje w 20-sekundowych interwałach (około 3 zapytania na minutę), co mieści się w limitach. Jeśli wiele systemów (TapHome, Home Assistant, inne narzędzia) współdzieli ten sam tokenID, łączna liczba zapytań może przekroczyć limit.

API SolaX Cloud wymaga aktywnego połączenia internetowego i zależy od dostępności serwerów SolaX Cloud. Podczas awarii chmury lub przerw w łączności szablon nie będzie otrzymywać zaktualizowanych danych. Dla instalacji wymagających gwarantowanego sterowania lokalnego rozważ szablon Modbus RTU.

Dostępne urządzenia

SolaX Inverter Moduł
Atrybuty serwisowe
Stan falownikaAktualny tryb pracy — Wait, Check, Normal, Fault, Permanent Fault, Update, EPS Check, EPS, Self-Test, Idle, Standby, Pv Wake Up Bat, Gen Check, Gen Run
Typ falownikaPodłączony model falownika — identyfikuje zainstalowaną serię SolaX (X1, X3, A1, J1) i generację
Zmienne niestandardowe
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

Odczyt (moduł)
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
Atrybuty serwisowe
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"));
Wyjście AC Licznik energii Tylko do odczytu

Całkowita i dzienna produkcja energii AC (kWh) z mocą wyjściową w czasie rzeczywistym (kW)

numeric Jednostka: kWh / kW JSON parsejson()
Atrybuty serwisowe
Inverter.AC.energy.out.daily [kWh]Dzienny uzysk energii AC — resetuje się o północy

Wyjście AC

Odczyt całkowitego zużycia
parsejson(json, "yieldtotal", 1)
Odczyt zapotrzebowania
parsejson(json, "acpower", 1) / 1000
Atrybuty serwisowe
Inverter.AC.energy.out.daily [kWh]
parsejson(json, "yieldtoday", 1)
SOC baterii Wejście analogowe Tylko do odczytu

Stan naładowania baterii w procentach — 0% (pusta) do 100% (pełna)

numeric Jednostka: % JSON parsejson()

SOC baterii

Odczyt poziomu wejściowego
parsejson(json, "soc", 1) / 100
Moc baterii Zmienna Tylko do odczytu

Chwilowa moc baterii w watach — dodatnia przy ładowaniu, ujemna przy rozładowywaniu

numeric Jednostka: W JSON parsejson()

Moc baterii

Odczyt
parsejson(json,"batPower",1)
Pobór z sieci Licznik energii Tylko do odczytu

Energia pobrana z sieci — całkowite zużycie (kWh) i moc poboru w czasie rzeczywistym (kW)

numeric Jednostka: kWh / kW JSON parsejson()

Pobór z sieci

Odczyt całkowitego zużycia
parsejson(json, "consumeenergy", 1)
Odczyt zapotrzebowania
var power := parsejson(json, "feedinpower", 1);
if(power < 0, power * -1, 0) / 1000
Moc sieciowa Zmienna Tylko do odczytu

Dwukierunkowa moc sieciowa w watach — dodatnia przy eksporcie, ujemna przy poborze

numeric Jednostka: W JSON parsejson()

Moc sieciowa

Odczyt
parsejson(json, "feedinpower", 1)
Produkcja FV (łącznie) Zmienna Tylko do odczytu

Łączna moc DC ze wszystkich wejść MPPT — automatycznie sumuje dostępne stringi

numeric Jednostka: W JSON parsejson()

Produkcja FV (łącznie)

Odczyt
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)
Produkcja FV (MPPT 1) Zmienna Tylko do odczytu
numeric Jednostka: W JSON parsejson()

Produkcja FV (MPPT 1)

Odczyt
parsejson(json,"powerdc1",1)
Produkcja FV (MPPT 2) Zmienna Tylko do odczytu
numeric Jednostka: W JSON parsejson()

Produkcja FV (MPPT 2)

Odczyt
parsejson(json,"powerdc2",1)
Produkcja FV (MPPT 3) Zmienna Tylko do odczytu
numeric Jednostka: W JSON parsejson()

Produkcja FV (MPPT 3)

Odczyt (moduł)
parsejson(json,"powerdc3",1)
Produkcja FV (MPPT 4) Zmienna Tylko do odczytu
numeric Jednostka: W JSON parsejson()

Produkcja FV (MPPT 4)

Odczyt (moduł)
parsejson(json,"powerdc4",1)
Oddawanie do sieci Licznik energii Tylko do odczytu

Energia oddana do sieci — całkowita energia oddana (kWh) i moc eksportu w czasie rzeczywistym (kW)

numeric Jednostka: kWh / kW JSON parsejson()

Oddawanie do sieci

Odczyt całkowitego zużycia
parsejson(json, "feedinenergy", 1)
Odczyt zapotrzebowania
var power := parsejson(json, "feedinpower", 1);
if(power > 0, power, 0) / 1000
Połączenie: Packet Parser → HTTP
Możliwe ulepszenia (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

Źródła