TapHome

SolaX Inverter (Cloud API)

Packet Parser → HTTP
Eingereicht von
Zuletzt aktualisiert: 03. 2026
SolaX Inverter (Cloud API)

Das SolaX Cloud API-Template verbindet TapHome mit jedem SolaX-Wechselrichter über die SolaxCloud-Monitoring-Plattform. Im Gegensatz zum Template SolaX Hybrid X1/X3 Gen 4, das Modbus RTU über RS-485 verwendet, erfordert diese cloudbasierte Integration keine physische Verkabelung zum Wechselrichter. TapHome fragt die SolaX Cloud-Server per HTTPS ab und empfängt Echtzeitdaten im JSON-Format.

Das Template unterstützt alle SolaX-Wechselrichtertypen (23 Modelle der Serien X1, X3, A1 und J1) und bietet 11 Überwachungsgeräte für AC-Ausgang, Batteriestatus, Netzleistung und PV-Produktion je MPPT-Eingang. Einzige Voraussetzungen sind ein SolaxCloud-Konto, ein internetverbundener Kommunikationsdongle (Pocket WiFi, LAN oder 4G) und der API-Token.

Konfiguration

SolaxCloud-Konto einrichten

Der Wechselrichter muss auf SolaxCloud registriert und online sein. Ein Kommunikationsmodul (Pocket WiFi, LAN oder 4G-Dongle) muss am Wechselrichter installiert und mit dem Internet verbunden sein.

API-Token abrufen (tokenID)
  1. Melden Sie sich bei SolaxCloud unter www.solaxcloud.com an
  2. Navigieren Sie in der linken Seitenleiste zu Service > Third-party ecosystem (oder dem Abschnitt API)
  3. Kopieren Sie die angezeigte tokenID — dies ist eine 23- oder 24-stellige Zeichenkette

Der Token ist für alle registrierten SolaxCloud-Benutzer kostenlos.

Registrierungsnummer finden (sn)

Der Parameter sn ist die Registrierungsnummer des Kommunikationsdongles — nicht die Seriennummer des Wechselrichters. Dies ist eine häufige Verwechslungsquelle.

Wo Sie sie finden:

  • Am Dongle — auf dem Etikett des Pocket WiFi / LAN / 4G-Moduls aufgedruckt (Barcode oder QR-Code)
  • In SolaxCloud — navigieren Sie zu Device > Inverter und suchen Sie die Spalte Registration No. in der Tabelle
Importparameter

Beim Import des Templates in TapHome geben Sie ein:

  • Token ID — die tokenID aus SolaxCloud
  • Registration No. — die 10-stellige Seriennummer des Kommunikationsdongles
Internetabhängigkeit

Dies ist eine reine Cloud-Integration. Alle Daten laufen über die SolaX Cloud-Server (www.solaxcloud.com:9443). Das Template funktioniert nicht ohne aktive Internetverbindung sowohl auf der TapHome CCU als auch am Kommunikationsdongle des Wechselrichters.

Für Nutzer, die lokale Kommunikation ohne Cloud-Abhängigkeit bevorzugen, bietet das Template SolaX Hybrid X1/X3 Gen 4 (Modbus RTU) direkte RS-485-Kommunikation mit Gen 4-Hybridwechselrichtern.

Gerätefunktionen

AC-Ausgang und Energieproduktion

Der Stromzähler AC Output erfasst die gesamte AC-Energieproduktion (yieldtotal in kWh) und die aktuelle Ausgangsleistung (acpower in W, umgerechnet in kW). Ein Service-Attribut zeigt den Tagesertrag (yieldtoday in kWh), der um Mitternacht zurückgesetzt wird.

Batterieüberwachung
  • Battery SOC — Ladezustand der Batterie in Prozent aus dem Feld soc. Der Wert wird durch 100 geteilt für den TapHome-Analogeingangsbereich von 0–1 (z. B. 85 % → 0,85). Dies ist das am schnellsten abgefragte Gerät mit einem Intervall von 2,5 Sekunden
  • Battery Power — momentane Lade-/Entladeleistung der Batterie in Watt. Positive Werte bedeuten Laden (von PV oder Netz), negative Werte bedeuten Entladen in die Last
Netzleistung und Energiemessung

Drei Geräte decken den Netzleistungsfluss ab:

  • Grid Power — rohe bidirektionale Netzleistung in Watt. Positiv = Einspeisung ins Netz, negativ = Bezug aus dem Netz
  • PV From Grid — Stromzähler, der den Energieverbrauch aus dem Netz erfasst. Gesamtverbrauch (consumeenergy in kWh) und aktuelle Bezugsleistung (aus feedinpower bei negativem Wert extrahiert, umgerechnet in kW)
  • PV To Grid — Stromzähler, der die ins Netz eingespeiste Energie erfasst. Gesamteinspeisung (feedinenergy in kWh) und aktuelle Einspeiseleistung (aus feedinpower bei positivem Wert extrahiert, umgerechnet in kW)
PV-Produktionsüberwachung

Das Template bietet fünf Geräte für die PV-Produktion:

  • PV Production (Total) — berechneter Sensor, der die DC-Leistung aller 4 MPPT-Eingänge summiert. Null-sicher — Wechselrichter mit weniger als 4 Strings geben null für ungenutzte MPPTs zurück, was die Formel als Null behandelt
  • PV Production (MPPT 1–4) — individuelle DC-Leistungswerte für jeden PV-String-Eingang in Watt
Diagnose auf Modulebene

Das Modulskript prüft den Wechselrichterstatus bei jeder Abfrage und meldet Probleme:

  • Status 100 (Wait Mode) und 110 (Standby) lösen Warnungen in TapHome aus
  • Status 103 (Fault Mode) und 104 (Permanent Fault Mode) lösen Fehler aus
  • Wenn die API-Antwort einen Fehler anzeigt, wird die Fehlermeldung aus dem Feld exception gemeldet

Zwei Service-Attribute sind am Modul verfügbar:

  • Inverter status — bildet Statuscodes 100–113 auf lesbare Bezeichnungen ab (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 — bildet Typcodes 1–23 auf Modellbezeichnungen ab (X1-LX, X-Hybrid, X1-Boost/Air/Mini, X3-Hybrid-G4 usw.)
Weitere Möglichkeiten

Die SolaX Cloud API stellt außerdem Meter 2 AC-Leistung (feedinpowerM2), EPS-Leistung (Emergency Power Supply) für drei Phasen (peps1–peps3), den Upload-Zeitstempel, die Wechselrichter-Seriennummer und den Batteriestatus bereit. Diese können in einem zukünftigen Template-Update hinzugefügt werden.

Fehlerbehebung

API gibt Fehler oder keine Daten zurück
  1. Überprüfen Sie, ob der Wechselrichter auf SolaxCloud online ist — melden Sie sich im Webportal an und prüfen Sie den Gerätestatus
  2. Bestätigen Sie, dass die tokenID korrekt ist und nicht neu generiert wurde (alte Tokens werden ungültig)
  3. Stellen Sie sicher, dass der Parameter sn die Registrierungsnummer des Kommunikationsdongles ist, nicht die Seriennummer des Wechselrichters
  4. Prüfen Sie, ob der Kommunikationsdongle eine aktive Internetverbindung hat
Veraltete oder verzögerte Messwerte

Die SolaX Cloud API gibt die neuesten vom Kommunikationsdongle hochgeladenen Daten zurück. Die Aktualität der Daten hängt vom Upload-Intervall des Dongles ab (typischerweise alle 5 Minuten). Das Template fragt die API alle 20 Sekunden ab, aber die zugrundeliegenden Daten können sich weniger häufig aktualisieren.

API-Limit-Fehler

Die API erlaubt maximal 10 Anfragen pro Minute und 10.000 Anfragen pro Tag. Das Template fragt in 20-Sekunden-Intervallen ab (etwa 3 Anfragen pro Minute), was innerhalb der Limits liegt. Wenn mehrere Systeme (TapHome, Home Assistant, andere Tools) dieselbe tokenID verwenden, kann die kombinierte Anfragerate das Limit überschreiten.

Die SolaX Cloud API erfordert eine aktive Internetverbindung und ist von der Verfügbarkeit der SolaX Cloud-Server abhängig. Bei Cloud-Ausfällen oder Internetunterbrechungen empfängt das Template keine aktualisierten Daten. Für Installationen, die garantierte lokale Steuerung benötigen, verwenden Sie stattdessen das Modbus RTU-Template.

Verfügbare Geräte

SolaX Inverter Modul
Serviceattribute
WechselrichterstatusAktueller Betriebsmodus — Wait, Check, Normal, Fault, Permanent Fault, Update, EPS Check, EPS, Self-Test, Idle, Standby, Pv Wake Up Bat, Gen Check, Gen Run
WechselrichtertypAngeschlossenes Wechselrichtermodell — identifiziert die installierte SolaX-Serie (X1, X3, A1, J1) und Generation
Benutzerdefinierte Variablen
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

Lesen (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
Serviceattribute
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-Ausgang Stromzähler Nur lesen

Gesamte und tägliche AC-Energieproduktion (kWh) mit Echtzeit-Ausgangsleistung (kW)

numeric Einheit: kWh / kW JSON parsejson()
Serviceattribute
Inverter.AC.energy.out.daily [kWh]Täglicher AC-Energieertrag — wird um Mitternacht zurückgesetzt

AC-Ausgang

Gesamtverbrauch lesen
parsejson(json, "yieldtotal", 1)
Bedarf lesen
parsejson(json, "acpower", 1) / 1000
Serviceattribute
Inverter.AC.energy.out.daily [kWh]
parsejson(json, "yieldtoday", 1)
Batterie-SOC Analogeingang Nur lesen

Batterieladezustand in Prozent — 0 % (leer) bis 100 % (voll)

numeric Einheit: % JSON parsejson()

Batterie-SOC

Eingangslevel lesen
parsejson(json, "soc", 1) / 100
Batterieleistung Variable Nur lesen

Momentane Batterieleistung in Watt — positiv beim Laden, negativ beim Entladen

numeric Einheit: W JSON parsejson()

Batterieleistung

Lesen
parsejson(json,"batPower",1)
Netzbezug Stromzähler Nur lesen

Aus dem Netz bezogene Energie — Gesamtverbrauch (kWh) und Echtzeit-Bezugsleistung (kW)

numeric Einheit: kWh / kW JSON parsejson()

Netzbezug

Gesamtverbrauch lesen
parsejson(json, "consumeenergy", 1)
Bedarf lesen
var power := parsejson(json, "feedinpower", 1);
if(power < 0, power * -1, 0) / 1000
Netzleistung Variable Nur lesen

Bidirektionale Netzleistung in Watt — positiv bei Einspeisung, negativ bei Bezug

numeric Einheit: W JSON parsejson()

Netzleistung

Lesen
parsejson(json, "feedinpower", 1)
PV-Produktion (Gesamt) Variable Nur lesen

Kombinierte DC-Leistung aller MPPT-Eingänge — summiert automatisch verfügbare Strings

numeric Einheit: W JSON parsejson()

PV-Produktion (Gesamt)

Lesen
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)
PV-Produktion (MPPT 1) Variable Nur lesen
numeric Einheit: W JSON parsejson()

PV-Produktion (MPPT 1)

Lesen
parsejson(json,"powerdc1",1)
PV-Produktion (MPPT 2) Variable Nur lesen
numeric Einheit: W JSON parsejson()

PV-Produktion (MPPT 2)

Lesen
parsejson(json,"powerdc2",1)
PV-Produktion (MPPT 3) Variable Nur lesen
numeric Einheit: W JSON parsejson()

PV-Produktion (MPPT 3)

Lesen (Modul)
parsejson(json,"powerdc3",1)
PV-Produktion (MPPT 4) Variable Nur lesen
numeric Einheit: W JSON parsejson()

PV-Produktion (MPPT 4)

Lesen (Modul)
parsejson(json,"powerdc4",1)
Netzeinspeisung Stromzähler Nur lesen

Ins Netz eingespeiste Energie — Gesamteinspeisung (kWh) und Echtzeit-Einspeiseleistung (kW)

numeric Einheit: kWh / kW JSON parsejson()

Netzeinspeisung

Gesamtverbrauch lesen
parsejson(json, "feedinenergy", 1)
Bedarf lesen
var power := parsejson(json, "feedinpower", 1);
if(power > 0, power, 0) / 1000
Verbindung: Packet Parser → HTTP
Mögliche Verbesserungen (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

Quellen