This post is about setting up FoxESS (Inverter and solar batteries) in Home Assistant and the steps to get the integration to work, allowing real-time data to be viewed in a dashboard on a computer, tablet or mobile phone. Click the link to find out how we came to get the FoxESS solar battery and inverter solution. 

Why Home Assistant?

Because the cloud-based solution FoxESS offers through their mobile app or browser is flakey at best. I don’t use it anymore because whenever I look at it, the site is either down or there is a problem. On the rare occasion, I have successfully loaded it, the information is minimal and delayed by 5 minutes. I would much rather have real-time data that can be incorporated into a custom dashboard.

What is FoxESS?

Fox is a global leader in developing inverter and energy storage solutions. Gas & Electrics Services based in East Grinstead installed my inverter and batteries solution. I’ll do another post on the installation soon.

What is Home Assistant?

Home Assistant is an open-source home automation that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts. Perfect for running on a Raspberry Pi or a local server.

What is a Raspberry Pi?

It is a tiny, dual-display desktop computer or a robot brain, a smart home hub, a media centre, a networked AI core, a factory controller, and much more.

Prerequisites for Home Assistant and following these instructions.

• You’ll need a Raspberry Pi 4 Model B for this installation guide.
• A computer to flash home assistant to a Micro SD card.
• Some knowledge of Micro SD cards (they might look the same, but they are different).
• Know how to run commands in Windows Command Prompt.
• There are over 70 steps involved, but fear not; I’ve provided screenshots for everything. 🙂
• Some common sense and a lot of patience.

Flashing Home Assistant for Raspberry Pi 4 Model B on a Micro SD Card.

1. Using the application BalenEtcher, flash the Home Assistant image (https://github.com/home-assistant/operating-system/releases/download/9.3/haos_rpi4-64-9.3.img.xz) to an Application Class 2 Micro SD card.
2. Insert the Micro SD Card into the Raspberry Pi 4 Model B, add a power cable, network cable and HDMI and boot it up.
3. Retrieve the IP address from the Home Assitant boot screen. Mine started with 192.168.xxx.xxx, but yours could be anything your network is configured to.
   

   How to load Home Assistant on a PC?

4. Go to a browser on your PC and type in the HTTP IPv4 address shown on the home Assistant screen earlier.
5. Set up a username and password and configure the location, unit & currency.
6. Accept all the default toggles and log into Home Assistant.
7. Click on your account or profile at the bottom and toggle on the Advanced mode.
   

   How to install Add-ons like File Editor, Terminal & SSH on Home Assistant?

8. Click Settings, Add-ons, Add-on store, select File editor, then Install. Wait for it to install, then select the toggle on Watchdog, Auto-Update and Show in the sidebar.
9. Click on Start.
   
10. Go back to the Add-on page and search for Terminal & SSH.
    1. Click on it and click Install.
    2. Wait for it to install, then select the toggle on Watchdog, Auto-Update and Show in the sidebar.
11. Click on Start.
    
12. If you plan to use SSH to log into your Raspberry Pi 4 from a different PC, you’ll want to set up a password. Click into the Configuration, and in the Password section, type in a password.
13. Under the Network, add 22 as the port.
14. Click Save and click on Restart.
    

    How to set up an SSH application on your PC?

15. With Terminal & SSH enabled, you can use any application to connect to the Home Assistant via SSH, which makes editing files much more accessible. I prefer using WinSCP on my windows machine to edit files, but anything that supports SSH will work. Remember to use the same password added to the configuration.
16. Add the hostname (from the above steps).
17. Set the port to 22.
18. Type in the username as root.
19. The password is whatever you’ve set the password to in step 12.
    
20. When prompted to accept the server’s Ed25519 key details, click Yes.
    
    
21. Finally, If you like using the command line, you may want to install PUTTY.EXE as well. Google search and download it.
    

    How to install HACS (Home Assistant Community Store)?

22. HACS stands for Home Assistant Community Store. HACS gives you a powerful UI to handle downloads of all your custom needs.
23. To install, open the terminal and type the following:
    1. wget -O – https://get.hacs.xyz | bash –
24. Quit the terminal.
25. Click Settings, Devices & Services (integrations, devices, entities and helpers) and click the + Add integration button (bottom right).
26. In the Search for a brand name, type HACS and select it.
    
27. Check all the checkboxes (4 of them) on the screen that pops up and click Submit.
28. Copy the code in the space, then click on the GitHub link.
    
29. Paste the code into the Device Activation and click Continue.
    
    
30. Next, you have to authorise HACS by clicking the green button.
    
31. Finally, you’ll see a message “Congratulations, and you’re all set!”
    
32. On the left sidebar, you should now see HACS.
    

    Installing the FoxESS Cloud Integration in Home Assistant. 

33. Note 1: if you want the cloud version of FoxESS then follow these steps (34 to 43).
    Note 2: If you want the LAN version, skip these steps and go to step 44.
34. Follow the instructions on this page: https://github.com/macxq/foxess-ha
35. Use hacs.io to manage the installation and update process.
36. Right now, this integration is part of HACS by default.
37. Click on HACS, Integrations, + Explore Integrations & Repositories.
38. Type FoxESS and when it appears, click on Download.
39. Restart Home Assistant.
40. When installed correctly, you’ll see it under HACS; integrations look like this:
    
41. Go to https://github.com/macxq/foxess-ha and copy the five lines starting with the sensor: into the Configuration.yaml
    
42. foxesscloud_inverter_id In UUID that can be found on the foxesscloud in the URL path on the Inverter Details page.
    ?? Please make sure that this is the exact value from the inverter details page address between = and & character:
    
    
43. Restart Home Assistant and check your Overview to see the sensors.
    

    FoxESS Community Modbus Integration (for LAN setup).

44. Follow the instructions on this page: https://github.com/StealthChesnut/HA-FoxESS-Modbus#readme – Always follow the instructions on the website as they are the latest. Listed below are all the other steps I took to get this integration working in my Home Assistant.
45. Plug an ethernet cable into the Inverter (see the manual to find the port) & the other end into your router or powerline adapter.
46. Back up your Home Assistant before making any changes. (Very important).
47. Remove any previous FoxESS cloud integration. (I initially didn’t do this but ended up with many duplicate entities).
    Restart the Home Assistant.
    Copy the code path from the GitHub code HTTPS link.
    
48. In the Home Assistant, click on HACS, Integrations.
49. At the top right, click on the three dots and select Custom Repositories.
50. Paste the address into the Repository, set the Category equal to Integration, and click ADD.
    
51. The FoxESS Community Modbus Integration will be added to the Custom Repositories list.
    
52. Click on the FoxESS Community Modbus Integration. This will load the page (URL: http://192.168.XXX.YYY:8123/hacs/repository/483415021),
53. Click on the DOWNLOAD button at the bottom.
    
54. A pop-up will appear showing the integration and version. Leave everything as is and click on the blue DOWNLOAD link.
55. Click on HACS on the sidebar, and you’ll see a red Pending restart notification at the top of the page.
    
56. Click on NAVIGATE and RESTART.
    
57. Open the File Editor, and click on the custom_components/HA-FoxESS-Modbus/modbusLAN.yaml
58. Remove the hash in front of the – on line 8 to make line 8 active.
59. Leave the type as TCP.
60. The host is the IP address of your inverter.
61. The port is 502.
62. Save the file.
    
63. Click on the configuration.yaml in the same folder
64. On line 15, add a # in front of the word modbus: !include custom_components/HA-FoxESS-Modbus/modbusUSB.yaml, which makes the line inactive.
65. Leave line 16 as it is.
    
66. Restart Home Assistant – Settings, System, click restart.
67. At this point, everything is done, and it should work. Check your Overview menu and see if the sensors exist.
    

    Troubleshooting FoxESS Community Modbus Integration

68. Everything was installed correctly, but nothing worked for me. As there are only a few configuration lines to change, the problem had to be with the IP address or the port.
69. My setup in the garage is as follows: Devolo Powerline adapter plugged into a wall socket. The Devolo has Wifi built in as well as two RJ45 ports for wired connections. This adapter acts like a router in the garage. It has an IP address of 192.168.XXX.YYY
70. The inverter wireless dongle connects to the Devolo Wifi to communicate to the cloud and phone app. This must stay on or as it is.
    The CAT 5/6/7 cable is plugged into the Ethernet port in the inverter. The other end is in the Devolo Powerline adapter, which uses the electric wires in the walls to communicate to another Devolo Powerline adapter at the wall socket where the router is situated. There is a CAT 6 cable plugged from the router into the Devolo Powerline adapter.

    Troubleshooting the port and IP Address

71. Add port 502 to router firewall rules.
72. Check if the Ethernet port is activated on the Inverter in the Settings panel.
    1. Go to Settings (code), communications, Ethernet, DHCP, and activate the Inverter.
73. Next, determine the IP address of the inverter. Look on the router under wired addresses and see if the Inverter name is listed. Mine wasn’t; instead, there were many MAC and IP Addresses.
74. In the Windows command prompt as administrator, type command: arm -a
    This will list all the IP addresses and their MAC Address.
75. If you know the MAC Address, then it can help you determine the IP address.
76. I have many wired devices, and finding the correct IP address took a while. Next, I decided to test port 502.
77. The FoxESS inverter LAN Port is:502 and to test if the IP address:502 is working, go to https://www.gineers.com/en/downloads.php and download Modbus RTU/TCP tester (free).
78. The app needs to be run in the command prompt.
    1. Remote IP Address: your Inverter IP
    2. Remote Port: 502
    3. Modbus Address: 247
    4. Read Modbus: Holding
    5. Address: 31000
    6. Count: 32
    7. Click Connect TCP when ready.
    8. REPEAT the process for each IP Address you might be testing.
79. This app aims to test the TCP connection between the inverter and the Router.
80. Using a process of elimination, I filtered out all the wired IP addresses I knew and the remaining IP addresses in the list I plugged into the app, one by one, until port 502 showed success. That confirmed the IP Address of the Inverter.
    
81. Another way to confirm the IP address and Port on the Inverter is to run a modpoll command.
82. Download modpoll.exe from here https://www.modbusdriver.com/modpoll.html
83. Download the windows file.
84. Unzip it and then run the modpoll.exe with some parameters in a command prompt. I got these from an example somewhere. The various parameters are the following:
    -m TCP is Modbus ASCII protocol
    -p is Even parity (default)
    502 is the Remote port
    -a is the Slave address
    247 is the Modbus address
    -t 3 is the 16-bit input register data type
    -0 is the first reference is 0 (PDU addressing) instead of 1
    -1 is the Poll rate in ms, (1000 is the default)
    -c is the Number of values to read (1-125, 1 is the default) option for writing (use -c 1 to force FC5 or FC6)
    16 is the value used for the Number of values to read
    -r is the Start reference (1-65536, 100 is the default)
    11000 is the Start reference used
    192.168.XXX.YYY is the remote IP Address used.

Type command: modpoll -m tcp -p 502 -a 247 -t 3 -0 -1 -c 16 -r 11000 192.168.XXX.YYY

1. This command also confirmed the IP Address.
2. Go back to Home Assistant, click on File editor and go to /config/custom_components/HA-FoxESS-Modbus/modbusLAN.yaml, and add the correct IP Address to line 10.
3. Save the file.
4. Restart Home Assistant.
5. In the Overview dashboard, check your sensors.

That is it! Well done if you have reached this far, and it is working! 😀

If you need more sources of inspiration, check out the Facebook group FoxESS Solar/Battery Owners Group