TapHome

SolaX Inverter (Cloud API)

Packet Parser → HTTP
Přidal
Poslední aktualizace: 03. 2026
SolaX Inverter (Cloud API)

Šablona SolaX Cloud API propojí TapHome s libovolným solárním invertorem SolaX prostřednictvím monitorovací platformy SolaxCloud. Na rozdíl od šablony SolaX Hybrid X1/X3 Gen 4, která používá Modbus RTU přes RS-485, tato cloudová integrace nevyžaduje žádné fyzické zapojení k invertoru. TapHome dotazuje servery SolaX Cloud přes HTTPS a přijímá data v reálném čase ve formátu JSON.

Šablona podporuje všechny typy invertorů SolaX (23 modelů napříč řadami X1, X3, A1 a J1) a poskytuje 11 monitorovacích zařízení pokrývajících AC výstup, stav baterie, tok energie do sítě a FV výrobu na jednotlivých MPPT vstupech. Jedinou požadavkem je účet na SolaxCloud, komunikační dongle s připojením k internetu (Pocket WiFi, LAN nebo 4G) a API token.

Konfigurace

Nastavení účtu SolaxCloud

Invertor musí být zaregistrovaný a online na SolaxCloud. Na invertoru musí být nainstalovaný komunikační modul (Pocket WiFi, LAN nebo 4G dongle) připojený k internetu.

Získání API tokenu (tokenID)
  1. Přihlaste se do SolaxCloud na www.solaxcloud.com
  2. V levém postranním panelu přejděte na Service > Third-party ecosystem (nebo sekci API)
  3. Zkopírujte zobrazený tokenID — jedná se o 23- nebo 24-znakový řetězec

Token je bezplatný pro všechny registrované uživatele SolaxCloud.

Nalezení registračního čísla (sn)

Parametr sn je registrační číslo komunikačního donglu — nikoliv sériové číslo invertoru. Toto je častý zdroj záměn.

Kde ho najít:

  • Na donglu — vytištěné na štítku modulu Pocket WiFi / LAN / 4G (čárový kód nebo QR kód)
  • V SolaxCloud — přejděte na Device > Inverter a vyhledejte sloupec Registration No. v tabulce
Importní parametry

Při importu šablony v TapHome zadejte:

  • Token ID — tokenID ze SolaxCloud
  • Registration No. — 10-znakové sériové číslo komunikačního donglu
Závislost na internetu

Toto je čistě cloudová integrace. Veškerá data proudí přes servery SolaX Cloud (www.solaxcloud.com:9443). Šablona nebude fungovat bez aktivního internetového připojení na TapHome CCU i na komunikačním donglu invertoru.

Pro uživatele, kteří preferují lokální komunikaci bez závislosti na cloudu, šablona SolaX Hybrid X1/X3 Gen 4 (Modbus RTU) poskytuje přímou komunikaci přes RS-485 s hybridními invertory Gen 4.

Schopnosti zařízení

AC výstup a energetická produkce

Elektroměr AC Output měří celkovou produkci AC energie (yieldtotal v kWh) a aktuální výstupní výkon (acpower ve W, konvertovaný na kW). Servisní atribut zobrazuje denní výnos (yieldtoday v kWh), který se resetuje o půlnoci.

Monitoring baterie
  • Battery SOC — stav nabití baterie v procentech z pole soc. Hodnota je dělena 100 pro rozsah analogového vstupu TapHome 0–1 (např. 85 % → 0,85). Toto je nejrychleji dotazované zařízení s intervalem 2,5 sekundy
  • Battery Power — okamžitý výkon nabíjení/vybíjení baterie ve wattech. Kladné hodnoty znamenají nabíjení (z FV nebo sítě), záporné hodnoty znamenají vybíjení do zátěže
Výkon sítě a měření energie

Tři zařízení pokrývají tok energie do/ze sítě:

  • Grid Power — surový obousměrný výkon sítě ve wattech. Kladný = export do sítě, záporný = odběr ze sítě
  • PV From Grid — elektroměr sledující energii spotřebovanou ze sítě. Celková spotřeba (consumeenergy v kWh) a aktuální výkon odběru (extrahovaný z feedinpower při záporné hodnotě, konvertovaný na kW)
  • PV To Grid — elektroměr sledující energii exportovanou do sítě. Celková energie dodaná do sítě (feedinenergy v kWh) a aktuální výkon dodávky (extrahovaný z feedinpower při kladné hodnotě, konvertovaný na kW)
Monitoring FV výroby

Šablona poskytuje pět zařízení pro FV výrobu:

  • PV Production (Total) — vypočtený senzor sčítající DC výkon ze všech 4 MPPT vstupů. Odolný vůči null hodnotám — invertory s méně než 4 stringy vracejí null pro nepoužité MPPT, což vzorec počítá jako nulu
  • PV Production (MPPT 1–4) — individuální DC výkony pro každý FV string vstup ve wattech
Diagnostika na úrovni modulu

Hlavní skript modulu kontroluje stav invertoru při každém dotazování a hlásí problémy:

  • Stav 100 (Wait Mode) a 110 (Standby) vyvolávají varování v TapHome
  • Stav 103 (Fault Mode) a 104 (Permanent Fault Mode) vyvolávají chyby
  • Pokud API odpověď indikuje selhání, chybová zpráva z pole exception je reportována

Na modulu jsou dostupné dva servisní atributy:

  • Inverter status — mapuje stavové kódy 100–113 na čitelné názvy (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 kódy typů 1–23 na názvy modelů (X1-LX, X-Hybrid, X1-Boost/Air/Mini, X3-Hybrid-G4 atd.)
Další možnosti

SolaX Cloud API také poskytuje výkon Meter 2 AC (feedinpowerM2), výkon EPS (Emergency Power Supply) pro tři fáze (peps1–peps3), časové razítko nahrání dat, sériové číslo invertoru a stav baterie. Tyto je možné přidat v budoucí aktualizaci šablony.

Řešení problémů

API vrací chybu nebo žádná data
  1. Ověřte, že invertor je online na SolaxCloud — přihlaste se na webový portál a zkontrolujte stav zařízení
  2. Zkontrolujte, zda je tokenID správný a nebyl regenerován (staré tokeny se zneplatní)
  3. Ujistěte se, že parametr sn je registrační číslo komunikačního donglu, nikoliv sériové číslo invertoru
  4. Zkontrolujte, zda má komunikační dongle aktivní internetové připojení
Zastaralé nebo opožděné hodnoty

SolaX Cloud API vrací nejnovější data nahraná komunikačním donglem. Aktuálnost dat závisí na intervalu nahrávání donglu (typicky každých 5 minut). Šablona dotazuje API každých 20 sekund, ale podkladová data se mohou aktualizovat méně často.

Chyby limitů API

API povoluje maximálně 10 požadavků za minutu a 10 000 požadavků za den. Šablona dotazuje v 20-sekundových intervalech (přibližně 3 požadavky za minutu), což je v rámci limitů. Pokud více systémů (TapHome, Home Assistant, jiné nástroje) sdílí stejný tokenID, kombinovaný počet požadavků může překročit limit.

SolaX Cloud API vyžaduje aktivní internetové připojení a závisí na dostupnosti serverů SolaX Cloud. Během výpadků cloudu nebo přerušení internetu šablona nebude přijímat aktualizovaná data. Pro instalace vyžadující garantované lokální řízení zvažte místo toho šablonu Modbus RTU.

Dostupná zařízení

SolaX Inverter Modul
Servisní atributy
Stav invertoruAktuální provozní režim — Wait, Check, Normal, Fault, Permanent Fault, Update, EPS Check, EPS, Self-Test, Idle, Standby, Pv Wake Up Bat, Gen Check, Gen Run
Typ invertoruPřipojený model invertoru — identifikuje nainstalovanou sérii SolaX (X1, X3, A1, J1) a generaci
Vlastní proměnné
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

Čtení (modul)
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
Servisní atributy
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"));
AC výstup Elektroměr Pouze ke čtení

Celková a denní produkce AC energie (kWh) s aktuálním výstupním výkonem (kW)

numeric Jednotka: kWh / kW JSON parsejson()
Servisní atributy
Inverter.AC.energy.out.daily [kWh]Denní výnos AC energie — resetuje se o půlnoci

AC výstup

Čtení celkové spotřeby
parsejson(json, "yieldtotal", 1)
Čtení odběru
parsejson(json, "acpower", 1) / 1000
Servisní atributy
Inverter.AC.energy.out.daily [kWh]
parsejson(json, "yieldtoday", 1)
SOC baterie Analogový vstup Pouze ke čtení

Stav nabití baterie v procentech — 0 % (prázdná) až 100 % (plná)

numeric Jednotka: % JSON parsejson()

SOC baterie

Čtení vstupní úrovně
parsejson(json, "soc", 1) / 100
Výkon baterie Proměnná Pouze ke čtení

Okamžitý výkon baterie ve wattech — kladný při nabíjení, záporný při vybíjení

numeric Jednotka: W JSON parsejson()

Výkon baterie

Čtení
parsejson(json,"batPower",1)
Odběr ze sítě Elektroměr Pouze ke čtení

Energie spotřebovaná ze sítě — celková spotřeba (kWh) a aktuální výkon odběru (kW)

numeric Jednotka: kWh / kW JSON parsejson()

Odběr ze sítě

Čtení celkové spotřeby
parsejson(json, "consumeenergy", 1)
Čtení odběru
var power := parsejson(json, "feedinpower", 1);
if(power < 0, power * -1, 0) / 1000
Výkon sítě Proměnná Pouze ke čtení

Obousměrný výkon sítě ve wattech — kladný při exportu, záporný při odběru

numeric Jednotka: W JSON parsejson()

Výkon sítě

Čtení
parsejson(json, "feedinpower", 1)
FV výroba (celková) Proměnná Pouze ke čtení

Kombinovaný DC výkon ze všech MPPT vstupů — automaticky sčítá dostupné stringy

numeric Jednotka: W JSON parsejson()

FV výroba (celková)

Čtení
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)
FV výroba (MPPT 1) Proměnná Pouze ke čtení
numeric Jednotka: W JSON parsejson()

FV výroba (MPPT 1)

Čtení
parsejson(json,"powerdc1",1)
FV výroba (MPPT 2) Proměnná Pouze ke čtení
numeric Jednotka: W JSON parsejson()

FV výroba (MPPT 2)

Čtení
parsejson(json,"powerdc2",1)
FV výroba (MPPT 3) Proměnná Pouze ke čtení
numeric Jednotka: W JSON parsejson()

FV výroba (MPPT 3)

Čtení (modul)
parsejson(json,"powerdc3",1)
FV výroba (MPPT 4) Proměnná Pouze ke čtení
numeric Jednotka: W JSON parsejson()

FV výroba (MPPT 4)

Čtení (modul)
parsejson(json,"powerdc4",1)
Dodávka do sítě Elektroměr Pouze ke čtení

Energie exportovaná do sítě — celková energie dodaná do sítě (kWh) a aktuální výkon dodávky (kW)

numeric Jednotka: kWh / kW JSON parsejson()

Dodávka do sítě

Čtení celkové spotřeby
parsejson(json, "feedinenergy", 1)
Čtení odběru
var power := parsejson(json, "feedinpower", 1);
if(power > 0, power, 0) / 1000
Připojení: Packet Parser → HTTP
Možná vylepšení (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

Zdroje