Integrating AlphaESS Inverter into Home Assistant via Modbus

After doing some research we got our solar system in April 2023. We went with a company that was using AlphaESS equipment and one of the reasons for choosing that particular installer was their neat work – a neighbour of ours allowed us to have a look. Our system had to be neat since we were planning to install it in a customer facing area of our little family business.

After enjoying the free electricity during the summer I started to get curious. Being a bit old fashioned I was wondering if and how the system can be monitored and controlled without AlphaESS’s cloud backend. So in December 2023 I read a lot about Modbus RTU, Modbus TCP, ioBroker and Home Assistant (HA). After trying both ioBroker and HA I decided to go with HA – the more popular home automation solution. I installed a test system in a VirtualBox and was able to monitor the AlphaESS system shortly after. I ordered a HA Green straight away, knowing that this was something I’d like to run 24/7.

It didn’t take long until I added the logic to run a scheduled force discharge of the batteries at night (from 23:30-02:00) – just before re-charging the batteries again (from 02:00-06:00). This schedule is running since January 2024 now and hasn’t had a single hiccup.

At this stage I decided to write things down, both for my own documentation and also to share my learnings – so here we go…

Update: as of end of August 2024 my HA instance isn’t hosted on the HA Green anymore but in a Proxmox VM on a Beelink MINI S12 PRO.

Update: as of start of September 2024 the integration contains automations to prioritise grid feed-in over battery charging to reduce clipping and maximise feed-in.

Get the latest copy of integration_alpha_ess.yaml here:
https://projects.hillviewlodge.ie/_alphaess/integration_alpha_ess.yaml

Useful AlphaESS reference documentation:
AlphaESS-ModbusRTU&TCP.pdf
AlphaESS-ModbusDispatchFunction.pdf
AlphaESS-ModbusRegisterParameterList.pdf

Disclaimer

Use the provided information at your own risk!

Be careful when making changes and double and triple check everything – writing inconsistent data into your AlphaESS Inverter’s Modbus registers might cause unexpected results which could damage your system!

I can’t offer official support but I’ll try to help if you need additional details, instructions or troubleshooting.

Tested on SMILE5 and SMILE-Hi10 but according to AlphaESS’s documentation the register addresses and values are consistent through all supported models.

Intended Audience

This guide’s intended audience are tech savvy persons, wanting to get more information out of their AlphaESS system without depending on AlphaESS’s cloud backend or persons, planning to access parts of the systems that cannot be accessed via App/WebUI.

Prerequisites

• Basic TCP/IP knowledge: this includes an understanding of what an IP address is, the function and identification of ports, and methods for locating devices within a home network.
• Proficiency in setting up and modifying Home Assistant and YAML files: This involves skills in configuring Home Assistant and the ability to edit YAML files, which are often used for configuration settings.
• I am providing a preconfigured YAML file containing the majority of the AlphaESS system’s available information and some configuration options. If this doesn’t cover your specific use case you will either have to extend the file with the bits relevant to you yourself or contact me and I will assist in modifying the file.
• Understanding of electrical units: a fundamental grasp of key electrical concepts and units such as Kilowatts (kW), Kilowatt-hours (kWh), Watts (W), Volts (V) and Amperes (A).

Coding/programming skills are not required.

Does your AlphaESS Inverter have Modbus TCP?

Identify your Inverter’s IP address and check if port 502 is open. That indicates that Modbus TCP is enabled and listening. If the port is closed check if it can be enabled via the Inverter’s control panel or reach out to support to get it enabled (Remote configuration or firmware update).

Modbus TCP capable Inverters:
SMILE5, SMILE-Hi5, SMILE-Hi10, SMILE-G3-S3.6/B5/S5.

If your Inverter doesn’t have Modbus TCP it might have Modbus RTU. In that case a converter can be used, there are Modbus RTU to USB (ca. €20) or Modbus RTU to Ethernet (ca. €50) converters available. I have no experience with any of these inverters therefore wouldn’t be able to provide any help.

Using a Modbus RTU to USB converter might require changes to the provided YAML file.*

Modbus RTU capable Inverters:
SMILE-i3, SMILE-T10 and older models of SMILE5, SMILE-Hi5, SMILE-Hi10, SMILE-G3-S3.6/B5/S5.

Note: the list of inverters above was taken from official AlphaESS documentation but seems to be incomplete, esp. the Modbus TCP capable ones. While a specific model is not listed it might still support Modbus TCP, carrying out a port 502 check as described above might still return a positive result.

Note: prior to buying any dedicated Home Assistant (HA) hardware a virtual test environment can easily be configured using VirtualBox/VMware Workstation/Hyper-V on a PC or Laptop.

Setup

The following instructions apply to Modbus TCP enabled Inverters only:

1. Connect your Inverter via LAN port (not WiFi) to your network. If wired network is not available you can use Powerline (€40) or a WiFi Repeater with an Ethernet port (€20) to extend your network alternatively.
2. Change your Inverter’s network configuration and assign a static IP Address. Assign an IP Address that’s outside of your main router’s DHCP range to avoid conflicts in the future. Configuring DHCP Reservations on your router can be used alternatively.
3. Get a HA instance installed, either in a virtual test environment or a HA device.
4. Install “Samba share” under “Settings/Add-ons/Add-on Store” and configure username and password.
5. From a computer connect to the HA instance (\\homeassistant) and use the Samba credentials.
6. Place a copy of integration_alpha_ess.yaml in \\homeassistant\config\packages (create \packages if required).
7. Edit \\homeassistant\config\configuration.yaml and append:

   homeassistant:
     packages: !include_dir_named packages

8. Edit \\homeassistant\config\secrets.yaml and append:

   alphaess_modbus_host_ip: “your Inverter’s IP Address”
   alphaess_modbus_host_port: 502
   alphaess_modbus_slaveId: 85

9. Perform a restart of your HA
10. In HA’s Overview select “Edit Dashboard/Add Card/By Entity/Search entities” picking the desired AlphaESS entities you want to add, click “Continue”, click “Add To Dashboard”

Note: many of the AlphaESS entities have been named for easy grouping, e.g. “. . . Grid . . .”, “. . . Battery . . .”, “. . . PV . . .”, “. . . Total . . .”, “. . . Today’s . . .”, “. . . Charging . . .” and “. . . Dispatch . . .”.

Configuration

Be careful when making changes and double and triple check everything – writing inconsistent data into your Inverter’s Modbus registers might cause unexpected results which could damage your system!

After making modifications navigate to “Developer Tools”, validate via “Check Configuration” and then reload “All YAML Configuration”.

Charging Default

To adjust the “Charging Default” settings (default: Charging Period 1: 2am-6am, Charging Period 2: 0-0 (disabled), Charging Cutoff SoC 100%) edit
\\homeassistant\config\packages\integration_alpha_ess.yaml,
find “AlphaESS_Charging_Default” and adjust the following values:

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2133 # Charging Cutoff SoC
    slave: !secret alphaess_modbus_slaveId
    value: 100

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2134 # Charging Period 1 Start Hour
    slave: !secret alphaess_modbus_slaveId
    value: 2

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2135 # Charging Period 1 Stop Hour
    slave: !secret alphaess_modbus_slaveId
    value: 6

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2136 # Charging Period 2 Start Hour
    slave: !secret alphaess_modbus_slaveId
    value: 0

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2137 # Charging Period 2 Stop Hour
    slave: !secret alphaess_modbus_slaveId
    value: 0

The Start Minutes and Stop Minutes can be configured in 1 minute steps using the predefined entities (default 0).

Charging Now

“Charging Now” will initiate an immediate charging session (default: for the next 2 hours, Charging Cutoff SoC 100%) and will, once finished, reset the settings to “Charging Default”.

To adjust the “Charging Now” settings edit
\\homeassistant\config\packages\integration_alpha_ess.yaml,
find “AlphaESS_Charging_Now” and adjust the following values:

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2133 # Charging Cutoff SoC
    slave: !secret alphaess_modbus_slaveId
    value: 100

- service: modbus.write_register
  data: # Fix day rollover
    value: >-
      {% if now().hour == 22 %}
        0
      {% elif now().hour == 23 %}
        1
      {% else %}
        {{now().hour + 2}}
      {% endif %}

- delay: "00:02:00" # Wait for 2 hours

Increasing or decreasing the hours will require adjusting the day rollover fix.

Dispatch

To adjust the “Dispatch” settings (default: 5kW for 2.5h or until 20% SoC) edit
\\homeassistant\config\packages\integration_alpha_ess.yaml,
find “AlphaESS_Dispatch_Initiate” and adjust the following values:

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2177 #Dispatch Power, 32000 Offset
    slave: !secret alphaess_modbus_slaveId
    value:
      - 0
      - 37000 # 5kW

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2182 #Dispatch SOC (0.4%/bit)
    slave: !secret alphaess_modbus_slaveId
    value: 50 # 20%/0.4

- service: modbus.write_register
  data:
    hub: modbuspvsystem
    address: 2183 #Dispatch Time
    slave: !secret alphaess_modbus_slaveId
    value:
      - 0
      - 9000 # 2.5h

Power Diagram (optional)

Get the latest copy of daily-power-diagram.yaml here:
https://projects.hillviewlodge.ie/_alphaess/daily-power-diagram.yaml.

As a prerequisite for the Power Diagram download the current apexcharts-card.js from https://github.com/RomRider/apexcharts-card/releases/latest and place the file in the folder \\homeassistant\config\www.

In HA’s Overview select “Edit Dashboard/⋮/Manage Resources/Add Resource” setting URL to “/local/apexcharts-card.js” and selecting “JavaScript Module” as the “Resource type”.

Restart HA.

In HA’s Overview select “Edit Dashboard/⋮/Manage dashboards/Add Dashboard”, pick “New dashboard from scratch”. Apply a random “Title” (random since the final title is configured in daily-power-diagram.yaml) and click “Create”. Click “Open” on the right, then “/⋮/Raw configuration editor”. Select the default content and replace it with the content of daily-power-diagram.yaml. Click “Save”.

Note: if you decided to change entity names in the provided integration_alpha_ess.yaml file you will have to adjust these in the daily-power-diagram.yaml accordingly.

Appendix

*Potentially required YAML modifications for a Modbus RTU to USB converter (where /dev/ttyUSB0 is depending on your individual HA hardware):

Change:

modbus:
  - name: modbuspvsystem
    type: tcp
    host: !secret alphaess_modbus_host_ip
    port: !secret alphaess_modbus_host_port
    message_wait_milliseconds: 10 # Waittime between 2 messages
    timeout: 10 # Timeout in seconds before connection is closed
    delay: 1 # Delay in seconds at startup

To:

modbus:
  - name: modbuspvsystem
    type: serial
    port: /dev/ttyUSB0 #USB FTDI device connected to the Inverter’s CAN/RS485 Modbus port
    baudrate: 9600
    bytesize: 8
    method: rtu
    parity: n
    stopbits: 1
    message_wait_milliseconds: 10 # Waittime between 2 messages
    timeout: 10 # Timeout in seconds before connection is closed
    delay: 1 # Delay in seconds at startup