Integrating Solax X3 Hybrid G4 API into Home Assistant

With your own PV-Panels on the roof the idea to integrate the Solax System into Home Assistant comes up. This opens new possibilities. You can create Automations together with a Wallbox for example or only to get better access to the Systems Data. I will show you how I integrated our Solax X3 Hybrid G4 into my Home Assistant instance using the Solax API.

If you only want to take a look in the configuration.yaml take a look in the End of the Post. For Instances that are accessible from the internet it’s recommended to save the API-Key in the secrets.yaml!

Automation Ideas for the Inverter-Integration

• Stop Charging of the Wallbox if the Home Battery is under 80%.
• Start the washing maschine if the export in to the grid is higher than 1kW
• Take a look at your power consumption and combine this with a smart meter
• Display the Power of multiple PV String with other smart Gadgets in one Dashboard

Connecting your Solax Inverter to Home Assistant

The data from the Solax solar system can be accessed in different ways. The options depend on the gateway installed on the inverter. Some of the gateways can output the data directly via ModBus-TCP. Otherwise the API from Solax must be used. Whether Modbus is supported or not has been well summarized in this article . The overview table is available here.

With a Modbus-TCP-Gateway, the HACS integration Solax-Modbus can be used. The setup is explained very well in this video. Advantage: The data can be queried more often than via the API and the query runs via the internal network. No third server application is involved.

Without a Modbus TCP gateway, the data must be queried via the Solax API. Disadvantage: Just like in the app, the data is only updated here every 5 minutes, as the same server is queried. Advantage: The queries are much more reliable than in the Solax app, there are virtually no connection interruptions since I use the API in homeassistant.

Requirements for setup via API

• Installation of the File editor add-on: Settings/Add-ons/Add-on Store: Search for File editor, then install and after a short wait click on start. After a reload of the web interface, the add-on appears in the bar on the left
• All the steps described here are carried out in the Configuration.yaml file. This can be accessed via the file editor. Click on the folder symbol at the top left after open the file editor and select the configuration.yaml file.
• Note: This source and these instructions in particular helped me with the implementation. Many thanks to Colin Robbins and mf76130. I have changed and simplified the instructions in some places in order to be able to use the Solax API without additional plugins.

Step 1: Configuring the API query

The Solax API provides the solar system data in json format. To determine your own information, you need the API code and the serial number of your own system. Both can be determined via the Solax web interface. Log in at solaxcloud.com. Then copy the inverter registration number from the table under Device/Inverter and insert it instead of SN_HERE into the code below. Then copy the tokenID under Service/API and paste it instead of API_CODE_HERE.

To check whether everything fits, you can call up the link: https://www.solaxcloud.com:9443/proxy/api/getRealtimeInfo.do?tokenId=API_CODE_HERE&sn=SN_HERE in the browser. With your values for SN_HERE and API_CODE_HERE. If the values of the solar system are displayed in the browser, everything is correct and the link below can be copied into configuration.yaml behind resource.

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

This configuration creates a sensor, that reads the Solax API. The API Answers with a .json-file. This is a structured file, so the values we need for home assistant can be easily read out by software. For our configuration only the values of the subitem “$.result” are interesting, so we only use this path. Next name all the values that you want to use in Home Assistant: yieldtoday, yieldtotal, acpower, uploadTime, … . In my case I don’t need powerdc3 and powerdc4 for example because my inverter has only two string. So they are not listed in “json_attributes:”. However, just like other attributes, they could simply be added or removed as required.

Step 2: Make Solax values available in Home Assistant

In the next step, individual entities must be assigned to the values of the Solax sensor. These receive units for example kWh or kW or the entities interpret the values of the solar system and make them available in Home Assistant.

To do this, add this template to configuration.yaml and restart Home Assistant. After the restart, the new entities should appear in the overview. The entities can be built into Automations.

template:
  - sensor:
    - name: "Solax yield today"
      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 yield"
      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 Inverter power total"
      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 last update"
      state: >
        {% set time = state_attr('sensor.solax', 'uploadTime') %}
        {{ as_timestamp(time) | timestamp_custom('%H:%M') }}
      unique_id: solax_5
      icon: mdi:clock

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

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

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

    - name: "Solax power grid"
      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 power grid 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 power grid 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 energyexport"
      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 energyimport"
      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 and automations

Now, of course, the new sensors have to be used. My dashboard looks like this at the moment. I implemented the power overview on the right with Power Flow Card Plus from the Homeassistant Community Store (HACS). Once installed, you can simply add the add-on to the dashboard and configure it via the web interface.

Step 3: Backup

Now the inverter is fully integrated into Home Assistant via the Solax API. Before you start testing with the new sensors, its recommended making a backup: Settings/System/Backups/Create backup. If something no longer works properly, it is easier to roll back.

Complete code for the 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 yield today"
      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 yield"
      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 Inverter power total"
      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 last update"
      state: >
        {% set time = state_attr('sensor.solax', 'uploadTime') %}
        {{ as_timestamp(time) | timestamp_custom('%H:%M') }}
      unique_id: solax_5
      icon: mdi:clock

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

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

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

    - name: "Solax power grid"
      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 power grid 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 power grid 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 energyexport"
      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 energyimport"
      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