Solax X3 Hybrid G4 API in Home Assistant einbinden

Die Integration der PV-Anlage in Home Assistant bringt neue Möglichkeiten. So können Wallboxen und Wechselrichter unterschiedlicher Hersteller verknüpft und neue Automations- oder Dokumentationsideen entstehen. In diesem Tutorial zeige ich, wie ich unsere Solax X3 Hybrid G4 über die API von Solax in meine Home–Assistant-Instanz eingebunden habe.

Wer explizit die gesamte configuration.yaml sucht, der findet sie ganz am Ende. Für öffentlich verfügbare Instanzen sollte der API-Key in der secrets.yaml gespeichert werden!

Mögliche Automationsideen

• Schalte die Wallbox ab, wenn der Akku unter 80% und der Akku über 600W ins Hausnetz speist
• Starte die Spülmaschine, wenn der Export ins Netz über ein Kilowatt beträgt.
• Auswertung der Verbrauchdaten und Verknüpfung mit einem smarten Stromzähler.
• Erfassung und Darstellung der Leistung der einzelnen PV-Strings auf dem Dach

Anbindungsmöglichkeiten in Home Assistant

Die Daten der Solax Solaranlage können auf unterschiedlichen Wegen abgefragt werden. Die Möglichkeiten hängen vom verbauten Gateway am Wechselrichter ab. Die Gateways können teilweise direkt über ModBus-TCP Daten der Solaranlage ausgeben. Sonst muss die API von Solax verwendet werden. Ob Modbus unterstützt wird, wurde in diesem Beitrag gut zusammengefasst. Die Übersichtstabelle gibt es hier.

Mit Modbus-TCP-Gateway kann die HACS Integration Solax-Modbus genutzt werden. Die Einrichtung wird in diesem Video sehr gut erklärt. Vorteil: Die Daten können öfter als über die API abfragt werden und die Abfrage läuft über das interne Netz.

Ohne Modbus-TCP-Gateway müssen die Daten über die Solax API abgefragt werden. Nachteil: Genau wie in der App aktualisieren sich die Daten hier nur alle 5 min, da der gleiche Server abgefragt wird. Vorteil: Die Abfragen sind deutlich zuverlässiger als in der Solax-App, Verbindungsabbrüche gibt es so gut wie keine.

Voraussetzungen für die Einrichtung per API

• Installation des File editor Add-ons: Einstellungen/Add-ons/Add-on Store: Suche nach File editor, dann installieren und nach kurzem Warten auf starten klicken. Nach einem reload der Weboberfläche erscheint das Add-on links in der Leiste
• Alle hier beschriebenen Schritte werden in der Datei Configuration.yaml ausgeführt. Diese erreicht man über den File editor. Dort auf das Ordnersymbol oben links klicken und die Datei configuration.yaml auswählen.
• Hinweis: Bei der Umsetzung hat mir insbesondere diese Quelle und diese Anleitung geholfen. Daher vielen Dank an Colin Robbins und mf76130. Ich habe die Anleitung an einige Stellen verändert und vereinfacht um auch ohne weitere Plugins die Solax API zu nutzen.

Schritt 1: Konfiguration der API-Abfrage

Die Solax-API stellt die Daten der Solaranlage im json Format bereit. Um die eigenen Informationen zu ermitteln benötigt man den API-Code und die Seriennummer der eigenen Anlage. Beide kann man über das Webinterface von Solax ermitteln. Unter solaxcloud.com anmelden. Dann unter Device/Inverter die Inverter SN aus der Tabelle kopieren statt SN_HERE in den Code unten einfügen. Dann unter Service/API die tokenID kopieren und anstelle von API_CODE_HERE einfügen.

Um zu überprüfen ob alles passt kann der Link: https://www.solaxcloud.com:9443/proxy/api/getRealtimeInfo.do?tokenId=API_CODE_HERE&sn=SN_HERE im Browser aufgerufen werden. Werden die Werte der Solaranlage im Browser angezeigt ist alles richtig gelaufen und der Code unten kann in die configuration.yaml kopiert werden.

sensor:
  - platform: rest
    resource: https://www.solaxcloud.com:9443/proxy/api/getRealtimeInfo.do?tokenId=API_CODE_HERE&sn=SN_HERE
    name: "Solax"
    json_attributes_path: "$.result"
    json_attributes:
      - yieldtoday
      - yieldtotal
      - acpower
      - uploadTime
      - inverterStatus
      - feedinpower
      - feedinenergy
      - consumeenergy
      - soc
      - batPower
      - powerdc1
      - powerdc2
      - batStatus
    value_template: 'Active'  # dummy value, not used; avoids the "State max length is 255 characters" error

Wir haben mit dieser Konfiguration einen Sensor erstellt. Der Sensor fragt die Solax-API ab. Diese gibt eine strukturierte Datei in json-Format zurück. Für uns sind nur die Attribute im Unterpunkt "$.result" der Datei interessant, daher nutzen wir diesen Pfad. Anschließend benennen alle Werte, die wir in Home Assistant verwenden wollen: yieldtoday, yieldtotal, acpower, uploadTime, … . Da unsere Anlage nur 2 Strings nutzt, betrachte ich powerdc3 und powerdc4 nicht. Sie könnten aber genau wie anderen Attribute einfach bei Bedarf hinzugefügt werden.

Schritt 2: Solax Werte in Home Assistant verfügbar machen

Im nächsten Schritt müssen den Werten des Sensors Solax einzelne Entitäten zugewiesen werden. Diese erhalten Einheiten oder interpretieren die Werte der Solaranlage und stellen sie in Home Assistant zur Verfügung.

Dazu dieses Template zur configuration.yaml hinzufügen und Home Assistant neu starten. Nach dem Neustart sollten die neuen Entitäten in der Übersicht erscheinen und in Integrationen eingebaut werden.

template:
  - sensor:
    - name: "Solax Ertrag heute"
      state: "{{ state_attr('sensor.solax', 'yieldtoday') }}"
      unit_of_measurement: "kWh"
      unique_id: solax_2
      icon: mdi:flash
      device_class: energy
      state_class: total_increasing

    - name: "Solax Gesamtertrag"
      state: "{{ state_attr('sensor.solax', 'yieldtotal') }}"
      unit_of_measurement: "kWh"
      unique_id: solax_3
      icon: mdi:flash
      device_class: energy
      state_class: total_increasing

    - name: "Solax Wechselrichter Gesamtleistung"
      unit_of_measurement: "W"
      state: "{{ state_attr('sensor.solax', 'acpower') }}"
      unique_id: solax_4
      icon: mdi:flash
      device_class: energy
      state_class: measurement

    - name: "Solax letzte Aktualisierung"
      state: >
        {% set time = state_attr('sensor.solax', 'uploadTime') %}
        {{ as_timestamp(time) | timestamp_custom('%H:%M') }}
      unique_id: solax_5
      icon: mdi:clock

    - name: "Solax Batterie Status"
      state: "{{ state_attr('sensor.solax', 'batStatus') }}"
      unique_id: solax_6
      icon: mdi:battery

    - name: "Solax Solarpanel dc1"
      state: "{{ state_attr('sensor.solax', 'powerdc1') }}"
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_7
      icon: mdi:solar-power-variant

    - name: "Solax Solarpanel dc2"
      state: "{{ state_attr('sensor.solax', 'powerdc2') }}"
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_8
      icon: mdi:solar-power-variant

    - name: "Solax Batterieleistung"
      state: "{{ state_attr('sensor.solax', 'batPower') }}"
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_9
      icon: mdi:battery

    - name: "Solax Batterieleistung In"
      state: >
        {% set attr = state_attr('sensor.solax', 'batPower') %}
        {{ attr if is_number(attr) and (attr|float > 0) else 0 }}
      state_class: measurement
      device_class: power
      unit_of_measurement: "W"
      unique_id: solax_10
      icon: mdi:battery

    - name: "Solax Batterieleistung Out"
      state: >
        {% set attr = state_attr('sensor.solax', 'batPower') %}
        {{ (0 - attr) if is_number(attr) and (attr|float < 0) else 0 }}
      state_class: measurement
      device_class: power
      unit_of_measurement: "W"
      unique_id: solax_11
      icon: mdi:battery

    - name: "Solax Akkustand"
      state: "{{ state_attr('sensor.solax', 'soc') }}"
      unit_of_measurement: "%"
      device_class: battery
      state_class: measurement
      unique_id: solax_12
      icon: mdi:battery

    - name: "Solax Netzleistung"
      state: >
        {% set attr = state_attr('sensor.solax', 'feedinpower') %}
        {{ (0 - attr) if is_number(attr) else 0 }}
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_13
      icon: mdi:transmission-tower

    - name: "Solax Netzleistung in"
      state: >
        {% set attr = state_attr('sensor.solax', 'feedinpower') %}
        {{ (0 - attr) if is_number(attr) and (attr|float < 0) else 0 }}
      unit_of_measurement: "W"
      unique_id: solax_14
      icon: mdi:transmission-tower

    - name: "Solax Netzleistung out"
      state: >
        {% set attr = state_attr('sensor.solax', 'feedinpower') %}
        {{ attr if is_number(attr) and (attr|float > 0) else 0 }}
      unit_of_measurement: "W"
      unique_id: solax_15
      icon: mdi:transmission-tower

    - name: "Solax Energieexport"
      state: "{{ state_attr('sensor.solax', 'feedinenergy') }}"
      unit_of_measurement: "kWh"
      unique_id: solax_16
      icon: mdi:transmission-tower
      device_class: energy
      state_class: total_increasing

    - name: "Solax Energieimport"
      state: "{{ state_attr('sensor.solax', 'consumeenergy') }}"
      unit_of_measurement: "Wh"
      unique_id: solax_19
      icon: mdi:transmission-tower
      device_class: energy
      state_class: total_increasing

    - name: "Solax Status"
      unique_id: solax_20
      icon: mdi:solar-power-variant
      state: >
          {% set attr = state_attr('sensor.solax', 'inverterStatus') %}
          {% if attr == '100' %}Wait
          {% elif attr == '101' %}Check
          {% elif attr == '102' %}Normal
          {% elif attr == '103' %}Fault
          {% elif attr == '104' %}Permanent Fault
          {% elif attr == '105' %}Update
          {% elif attr == '106' %}EPS Check
          {% elif attr == '107' %}EPS
          {% elif attr == '108' %}Self-test
          {% elif attr == '109' %}Idle
          {% elif attr == '110' %}Standby
          {% elif attr == '111' %}Pv Wake Up Bat
          {% elif attr == '112' %}Gen Check
          {% elif attr == '113' %}Gen Run
          {% else %}unknown{% endif %}

    - name: Total Home Use
      unique_id: home use
      state: >
          {% set battery = states('sensor.solax_battery_use') %}
          {% set grid = states('sensor.solax_grid_power') %}
          {% set solar = states('sensor.solar_panel_power') %}
          {% set total = 0 - battery|float if is_number(battery) else 0 %}
          {% set total = total + (solar|float if is_number(solar) else 0) %}
          {% set total = total + (grid|float if is_number(grid) else 0) %}
          {{ total }}
      state_class: measurement
      icon: 'mdi:flash'
      unit_of_measurement: W
      device_class: power

Schritt 3: Dashboard und Automationen

Jetzt müssen die neuen Sensoren natürlich genutzt werden. Mein Dashboard schaut im Moment so aus. Die Leistungsübersicht rechts habe ich mit Power Flow Card Plus aus dem Homeassistant Community Store (HACS) realisiert. Das Add-on kann man nach dem Installieren einfach zum Dashboard hinzufügen und über das Webinterface konfigurieren.

Schritt 3: Backup

Damit ist die Solaranlage vollständig über die Solax API in Home Assistant integriert. Bevor das ausprobieren mit den neuen Sensoren beginnt empfielt sich ein Backup: Einstellungen/System/Backups/Backup erstellen Sollte etwas dann nicht mehr richtig funktionieren fällt die Rolle rückwärts leichter.

Vollständiger Code für die configuration.yaml

sensor:
  - platform: rest
    resource: https://www.solaxcloud.com:9443/proxy/api/getRealtimeInfo.do?tokenId=API_CODE_HERE&sn=SN_HERE
    name: "Solax"
    json_attributes_path: "$.result"
    json_attributes:
      - yieldtoday
      - yieldtotal
      - acpower
      - uploadTime
      - inverterStatus
      - feedinpower
      - feedinenergy
      - consumeenergy
      - soc
      - batPower
      - powerdc1
      - powerdc2
      - batStatus
    value_template: 'Active'  # dummy value, not used; avoids the "State max length is 255 characters" error


template:
  - sensor:
    - name: "Solax Ertrag heute"
      state: "{{ state_attr('sensor.solax', 'yieldtoday') }}"
      unit_of_measurement: "kWh"
      unique_id: solax_2
      icon: mdi:flash
      device_class: energy
      state_class: total_increasing

    - name: "Solax Gesamtertrag"
      state: "{{ state_attr('sensor.solax', 'yieldtotal') }}"
      unit_of_measurement: "kWh"
      unique_id: solax_3
      icon: mdi:flash
      device_class: energy
      state_class: total_increasing

    - name: "Solax Wechselrichter Gesamtleistung"
      unit_of_measurement: "W"
      state: "{{ state_attr('sensor.solax', 'acpower') }}"
      unique_id: solax_4
      icon: mdi:flash
      device_class: energy
      state_class: measurement

    - name: "Solax letzte Aktualisierung"
      state: >
        {% set time = state_attr('sensor.solax', 'uploadTime') %}
        {{ as_timestamp(time) | timestamp_custom('%H:%M') }}
      unique_id: solax_5
      icon: mdi:clock

    - name: "Solax Batterie Status"
      state: "{{ state_attr('sensor.solax', 'batStatus') }}"
      unique_id: solax_6
      icon: mdi:battery

    - name: "Solax Solarpanel dc1"
      state: "{{ state_attr('sensor.solax', 'powerdc1') }}"
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_7
      icon: mdi:solar-power-variant

    - name: "Solax Solarpanel dc2"
      state: "{{ state_attr('sensor.solax', 'powerdc2') }}"
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_8
      icon: mdi:solar-power-variant

    - name: "Solax Batterieleistung"
      state: "{{ state_attr('sensor.solax', 'batPower') }}"
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_9
      icon: mdi:battery

    - name: "Solax Batterieleistung In"
      state: >
        {% set attr = state_attr('sensor.solax', 'batPower') %}
        {{ attr if is_number(attr) and (attr|float > 0) else 0 }}
      state_class: measurement
      device_class: power
      unit_of_measurement: "W"
      unique_id: solax_10
      icon: mdi:battery

    - name: "Solax Batterieleistung Out"
      state: >
        {% set attr = state_attr('sensor.solax', 'batPower') %}
        {{ (0 - attr) if is_number(attr) and (attr|float < 0) else 0 }}
      state_class: measurement
      device_class: power
      unit_of_measurement: "W"
      unique_id: solax_11
      icon: mdi:battery

    - name: "Solax Akkustand"
      state: "{{ state_attr('sensor.solax', 'soc') }}"
      unit_of_measurement: "%"
      device_class: battery
      state_class: measurement
      unique_id: solax_12
      icon: mdi:battery

    - name: "Solax Netzleistung"
      state: >
        {% set attr = state_attr('sensor.solax', 'feedinpower') %}
        {{ (0 - attr) if is_number(attr) else 0 }}
      unit_of_measurement: "W"
      device_class: energy
      state_class: measurement
      unique_id: solax_13
      icon: mdi:transmission-tower

    - name: "Solax Netzleistung in"
      state: >
        {% set attr = state_attr('sensor.solax', 'feedinpower') %}
        {{ (0 - attr) if is_number(attr) and (attr|float < 0) else 0 }}
      unit_of_measurement: "W"
      unique_id: solax_14
      icon: mdi:transmission-tower

    - name: "Solax Netzleistung out"
      state: >
        {% set attr = state_attr('sensor.solax', 'feedinpower') %}
        {{ attr if is_number(attr) and (attr|float > 0) else 0 }}
      unit_of_measurement: "W"
      unique_id: solax_15
      icon: mdi:transmission-tower

    - name: "Solax Energieexport"
      state: "{{ state_attr('sensor.solax', 'feedinenergy') }}"
      unit_of_measurement: "kWh"
      unique_id: solax_16
      icon: mdi:transmission-tower
      device_class: energy
      state_class: total_increasing

    - name: "Solax Energieimport"
      state: "{{ state_attr('sensor.solax', 'consumeenergy') }}"
      unit_of_measurement: "Wh"
      unique_id: solax_19
      icon: mdi:transmission-tower
      device_class: energy
      state_class: total_increasing

    - name: "Solax Status"
      unique_id: solax_20
      icon: mdi:solar-power-variant
      state: >
          {% set attr = state_attr('sensor.solax', 'inverterStatus') %}
          {% if attr == '100' %}Wait
          {% elif attr == '101' %}Check
          {% elif attr == '102' %}Normal
          {% elif attr == '103' %}Fault
          {% elif attr == '104' %}Permanent Fault
          {% elif attr == '105' %}Update
          {% elif attr == '106' %}EPS Check
          {% elif attr == '107' %}EPS
          {% elif attr == '108' %}Self-test
          {% elif attr == '109' %}Idle
          {% elif attr == '110' %}Standby
          {% elif attr == '111' %}Pv Wake Up Bat
          {% elif attr == '112' %}Gen Check
          {% elif attr == '113' %}Gen Run
          {% else %}unknown{% endif %}

    - name: Total Home Use
      unique_id: home use
      state: >
          {% set battery = states('sensor.solax_battery_use') %}
          {% set grid = states('sensor.solax_grid_power') %}
          {% set solar = states('sensor.solar_panel_power') %}
          {% set total = 0 - battery|float if is_number(battery) else 0 %}
          {% set total = total + (solar|float if is_number(solar) else 0) %}
          {% set total = total + (grid|float if is_number(grid) else 0) %}
          {{ total }}
      state_class: measurement
      icon: 'mdi:flash'
      unit_of_measurement: W
      device_class: power