• Have you tried out dark mode?! Scroll to the bottom of any page to find a sun or moon icon to turn dark mode on or off!

diy solar

diy solar

Integrating EG4/SolarCloudSystem WEB API with Home Assistant: An Incomplete Guide

twistedpear

New Member
Joined
Jan 21, 2025
Messages
23
Location
Parry Sound, ON, Canada
Thought I'd share my journey of integrating data from the SolarCloudSystem/EG4 API directly into Home Assistant using custom sensors and scripts. This approach bypasses alternative solutions that rely on LuxPower or Solar Assistant, providing a direct connection to the web API ( e.g. ) . Additionally, I'll share a little about reverse engineering the API, defining an OpenAPI Spec, and creating a simple Python script for data retrieval.

I am very much at the beginning of my Home Assistant journey, but maybe this will help someone. There are plenty of improvements to make, especially around timing and handing of errors. Also note that my experience is limited and only with a SINGLE 12000XP, so I don't know the values for other inverters though MOST would likely be the same.

1741492117076.png

The HA integration is setup as follows (I attached the files, except secrets.yaml) :
  1. create secrets.yaml entries for account, password and serial number.
    1. eg4_account: <username to log into monitor.eg4electronics.com>
    2. eg4_password: <password to log into monitor.eg4electronics.com>
    3. eg4_serial_number: serialNum=<serialnumber of the inverter you want to monitor>
  2. create a shell_command (configuration.yaml) to perform authentication and capture the provided cookie (JSESSIONID)
  3. create an automation (automation.yaml) to run the shell_command on interval or when the API call fails
  4. create a command_line sensor (configuration.yaml) to read the token captured in 2.
  5. create REST sensors (configuration.yaml) to pull data, using the cookie from 4 and assign it to attributes
  6. create template sensors (configuration.yaml) to read and manipulate the REST sensors attributes
  7. restart home assistant
  8. add info to your energy dashboard
  9. create your own dashboards
Below are a few extras on my approach....

Reverse Engineering the EG4 API​

The SolarCloudSystem/EG4 API doesn't have official public documentation. To explore the API:
  1. I intercepted the network traffic using browser developer tools and MITMProxy to observe API requests.
  2. From these requests, I built an OpenAPI Spec to simplify interactions and used that in Insomnia and created an insomnia collection (file included)
  3. With this spec, I wrote a simple Python script to query the API, which I later adapted for use with my ESP32 project (https://diysolarforum.com/threads/eg4-rest-api.98576/post-1361390)
This gave me direct access to real-time data, which I later integrated into Home Assistant.


Creating Custom Sensors in Home Assistant​

Since no existing integration directly connected to the API, I created custom REST sensors and template sensors in Home Assistant, as I learn Home Assistant. I've seen a few "official" integrations and may produce something like that later (if needed).

See the config files and steps above

Next Steps and Future Plans​

Currently, this integration is read-only, but I may expand it by:

  • Implementing control functionality for generator start/stop.
  • Setting parameters such as Charge current
  • Writing a dedicated Home Assistant Integration for improved installation and user experience.
  • May make considerations for connecting directly to the inverter on the local network.
  • Creating a YouTube Tutorial to guide others in replicating this solution...but maybe not lol.


Feedback and Collaboration​

If you're working on a similar project or have insights on optimizing this integration, I'd love to hear from you. Whether through a dedicated forum post or future video content, I’m excited to share what I’ve learned and improve the solution further.

Stay tuned for updates on my progress!
 

Attachments

Last edited:
Thought I'd share my journey of integrating data from the SolarCloudSystem/EG4 API directly into Home Assistant using custom sensors and scripts. This approach bypasses alternative solutions that rely on LuxPower or Solar Assistant, providing a direct connection to the web API ( e.g. ) . Additionally, I'll share a little about reverse engineering the API, defining an OpenAPI Spec, and creating a simple Python script for data retrieval.

I am very much at the beginning of my Home Assistant journey, but maybe this will help someone. There are plenty of improvements to make, especially around timing and handing of errors. Also note that my experience is limited and only with a SINGLE 12000XP, so I don't know the values for other inverters though MOST would likely be the same.

View attachment 283444

The HA integration is setup as follows (I attached the files, except secrets.yaml) :
  1. create secrets.yaml entries for account, password and serial number.
    1. eg4_account: <username to log into monitor.eg4electronics.com>
    2. eg4_password: <password to log into monitor.eg4electronics.com>
    3. eg4_serial_number: serialNum=<serialnumber of the inverter you want to monitor>
  2. create a shell_command (configuration.yaml) to perform authentication and capture the provided cookie (JSESSIONID)
  3. create an automation (automation.yaml) to run the shell_command on interval or when the API call fails
  4. create a command_line sensor (configuration.yaml) to read the token captured in 2.
  5. create REST sensors (configuration.yaml) to pull data, using the cookie from 4 and assign it to attributes
  6. create template sensors (configuration.yaml) to read and manipulate the REST sensors attributes
  7. restart home assistant
  8. add info to your energy dashboard
  9. create your own dashboards
Below are a few extras on my approach....

Reverse Engineering the EG4 API​

The SolarCloudSystem/EG4 API doesn't have official public documentation. To explore the API:
  1. I intercepted the network traffic using browser developer tools and MITMProxy to observe API requests.
  2. From these requests, I built an OpenAPI Spec to simplify interactions and used that in Insomnia and created an insomnia collection (file included)
  3. With this spec, I wrote a simple Python script to query the API, which I later adapted for use with my ESP32 project (https://diysolarforum.com/threads/eg4-rest-api.98576/post-1361390)
This gave me direct access to real-time data, which I later integrated into Home Assistant.


Creating Custom Sensors in Home Assistant​

Since no existing integration directly connected to the API, I created custom REST sensors and template sensors in Home Assistant, as I learn Home Assistant. I've seen a few "official" integrations and may produce something like that later (if needed).

See the config files and steps above

Next Steps and Future Plans​

Currently, this integration is read-only, but I may expand it by:

  • Implementing control functionality for generator start/stop.
  • Setting parameters such as Charge current
  • Writing a dedicated Home Assistant Integration for improved installation and user experience.
  • May make considerations for connecting directly to the inverter on the local network.
  • Creating a YouTube Tutorial to guide others in replicating this solution...but maybe not lol.


Feedback and Collaboration​

If you're working on a similar project or have insights on optimizing this integration, I'd love to hear from you. Whether through a dedicated forum post or future video content, I’m excited to share what I’ve learned and improve the solution further.

Stay tuned for updates on my progress!
This is awesome, I saw another thread where someone replaced the wifi dongle with one from monitormy.solar and they were able to integrate it into home assistant. Here's the link. https://danielraffel.me/2024/10/28/...r-my-eg4-18kpv-inverter-using-home-assistant/
 
I got the JSESSIONID and generated the eg4_token and login files, but home assistant still shows the API status failed, any ideas?
 
Last edited:
I got the JSESSIONID and generated the eg4_token and login files, but home assistant still shows the API status failed, any ideas?
Sometimes there's a timing issue and you have to "wait" or force run it again.

Try a refresh of the configuration files from the developer section (not a restart).

I'm just re-writing the API as a python package today, and will then figure out how to create an HA Integration that you can just install...
 
The API works like a charm. Thank you for sharing all your work! Heads up I think you left your serial number in the configuration.yaml that you published above. I got it to communicate with home assistant once I changed all payloads to !secret eg4_serial_number.
 
Last edited:
Reposting from https://diysolarforum.com/threads/eg4-rest-api.98576/post-1381231

ok so the first attempt at custom integration has started...

https://github.com/twistedroutes/eg4_inverter_ha
using the api from
https://github.com/twistedroutes/eg4_inverter_api

I haven't written the readme yet...

I've got to write up some tests, validate the data scaling (e.g. where EG4 provide 5100 to represent 51.00 V), likely create a few virtual sensors (a sensor made from other sensors data, like capacity in KWh = voltage and capacity in amp-hours).

Then add some switches and inputs to change data

Then add an example dashboard (though this data can already be used in the Energy dashboard)

This can be loaded into your .homeassistant/custom_components (or wherever your custom_components folder is).

1741913480497.png1741913502330.png
1741913518245.png

1741913570047.png
 

diy solar

diy solar
Back
Top