Skip to content

Installing and Configuring HA FoxESS Modbus

Jump to bottom
TonyM1958 edited this page Apr 17, 2024 · 46 revisions

You will need to install and edit files in Home Assistant to run the modbus integration. This page describes how to do this.

If you are migrating between integrations, read this first.

Install Add-ons for Home Assistant

You will need to be able to view files and edit them in HA. Various add-ons are available to do this. If you haven't installed something already, Studio Code Server can do the job and that's what is used for the example screen shots here.

  • Go to Settings, Add-ons in Home Assistant
  • Click on ADD-ON STORE and search for Studio Code Server.
  • Click to select the add-on and click INSTALL
  • Turn on the option to Show in sidebar and click START
  • Click the icon in the side bar to open Studio Code Server
  • If you want, click the Settings gear, select Themes, Colour Theme and chose a colour theme for Studio Code Server.

Download HA-FoxESS-Modbus files

  • Open HACS and go to Integrations
  • Click the three dots in the top right hand corner and select Custom repositories
  • Enter the Github address of this repository: "https://github.com/TonyM1958/HA-FoxESS-Modbus" and select the category Integration. Click ADD and then X to close the Custom repositories dialgoue.
  • Click EXPLORE & DOWNLOAD REPOSITORIES, search for FoxESS Community Modbus Integration and select this.
  • Click DOWNLOAD, confirm the folder location and select DOWNLOAD when prompted.

Configure the integration

  • Open Studio Code Server to see the folder structure under CONFIG
  • Expand custom_components, HA-FoxESS-Modbus to see the files
  • HA-FoxESS-Modbus contains templates for updating configuration.yaml and secrets.yaml in your CONFIG folder

  • Open 'template_configuration.yaml'

  • Select the lines containing the integration settings and copy them to the clipboard (ctl-c)

  • Open the file 'configuration.yaml' in CONFIG and paste the integration settings from the clipboard (ctl-v)

  • You need to select the modbus file for your inverter model and connection method: to do this, alter the lines by adding # (comment out) or removing # (uncomment) the start of the relevant lines:

    • If you have connected via an RS485 to LAN adapter, use 'modbusXX_RS485_LAN.yaml' for the integration (already selected in the template)
    • If you have connected via an RS485 to USB adapter, comment out the line containing 'modbusXX_RS485_LAN.yaml' and uncomment the line containing 'modbusXX_RS485.yaml'
    • Change XX to match your inverter. Set XX to 'H1' for H1, AC1 or AIO, 'H1G2' for H1 gen 2, 'KH' for K series or 'H3' for H3.

  • Save your file (ctl-s saves the file but Studio Code Server also autosaves)

  • Open 'template_secrets.yaml' and copy the lines with settings to the clipboard (ctl-c)

  • Open your 'secrets.yaml' file in CONFIG (create the file if it does not exist) and paste the lines from the clipboard (ctl-v)

  • The USB adapter port and slave address are configured already but you can update the settings if they are different in your case

  • If you connect via a LAN adapter, update 'fox_inv1_ip_address' with the IP address allocated to your RS-485 to LAN adapter

  • Save your file

Optionally, you may want to configure recorder to use MariaDB instead of SQLite, as this is supposed to work better as your history database size grows over time. To do this:

  • Go to Settings, Add-ons and find MariaDB in the Add-On Store.
  • Install and configure the add-on, creating a password for the database user. Copy your db password to the clipboard
  • Open 'secrets.yaml' and update mariadb_url, by pasting your db password where it says <your password>
  • In your configuration.yaml, select the line with recorder_maria.yaml instead of recorder_ha.yaml so that recorder will use Mariadb instead of SQLite
  • save your files
  • Go to Settings, Developer Tools and click CHECK CONFIGURATION to make sure your configuration is valid (if not, correct the problem)
  • Click RESTART, Restart Home Asssistant, RESTART and wait for Home Assistant to reconnect and finish starting
  • Go to Settings, Devices & Services, Entities and check the entities that are now available
  • Click on Status to sort and view any entities that are not available. Some statistical sensors will not be available until a number of data points are available (ignore these) but some may also not be supported by your inverter / connection type so you may want to check which ones are available / not available
  • You can also review the file home-assistant.log in CONFIG to check for any error messages

Configure Helpers

  • Go to Settings, Devices & Settings, Helpers
  • Find the helper named "Install Date" and set the date of your installation (dd/mm/yyyy). This is used to work out your remaining battery life by comparing the number of battery cycles used (where available) with how old your batteries are
  • Find the helper named "Battery Size" and set this to size of one of your batteries. The sizes for various batteries are: HV2600: 2.56, MIRA HV25: 2.45, ECS2800: 2.76, ECS2900: 2.88, ECS4100: 4.03, ECS4300H: 4.14, ECS4800: 4.74
  • Optionally, you can configure the helper "CT2 Handling", if you have a second inverter and CT2 is used. The values are: 0 = CT2 is not modified, 1 = CT2 is inverted, 2 = CT2 is added to Load Power, 3 = CT2 is inverted and added to Load Power

Build your dashboard

  • You can now add entities into your dashboard(s) so you can monitor your inverter in real time
  • By default, power sensors are updated every 10 seconds, voltage and current every minute and other sensors every 5 minutes. You can change these settings in your 'secrets.yaml' file if required, although faster scanning may cause problems if you are using a W610 adapter
  • Information on setting up a dash board is provided in Building a Dashboard

Automations

A range of automations that use the modbus write service to update settings on the inverter are included in the file 'automations.yaml'. These cannot be copied directly to a new instance as a system specific ID is created for each automation. To copy an automation, you will need to create a new automation on your system and copy the relevant section of yaml across from the example file. An example of how to do this is provided in Inverter Work Modes

To ensure automations you create appear under Settings, Automations, include this line in your configuration.yaml:

automation: !include automations.yaml

PV Output

Optionally, you can also configure updates of your generation and consumption data to pvoutput.org. Instructions for doing this are provided here. If you have installed this integration, the file 'rest_command.yaml' already exists and there are template entries for 'configuration.yaml' and 'secrets.yaml' that you can use. You will need to create and configure the automation (described above).

Adding your own templates

Advanced Users. This integration includes templates from the file custom_components/HA-FoxESS-Modbus/template.yaml. By default, there is just one template include file. You cannot edit this file to add your own templates as any changes will be over-written during an update.

You can however modify the configuration so you can add your own template files. Here is an outline of how to do this:

  • create a new folder called 'templates' under /CONFIG
  • create a symbolic link to the file ../custom_components/HA-FoxESS-Modbus/template.yaml in 'templates' (ln -s <file>)
  • modify configuration.yaml so the template include looks like this:
template: !include_dir_merge_list templates
  • add your own yaml files containing templates into the folder 'templates' (copy the format / indentation used by the existing file)

Alternative Integration

If you want to use the original Stealthchesnut integration, you can use this command to download and install the files:

wget -q -O - https://github.com/Stealthchesnut/HA-FoxESS-Modbus/archive/master.tar.gz | tar -xz --strip=1 --wildcards '*.yaml' -k

Clone this wiki locally