Getting Started with Hanergy in 10 Minutes

Hanergy is a Home Assistant add-on that automatically distributes solar surplus across EV chargers, heat pumps, pool pumps, and batteries. This guide walks through installation and first-load configuration in under 10 minutes.

Prerequisites

Before starting, ensure the following are in place:

Home Assistant running on HAOS, Supervised, or Docker (Core).
Solar production sensor — an entity reporting current solar production in watts (e.g., sensor.solar_power).
Grid import/export sensors — entities reporting grid import and export in watts.
At least one controllable load — a switch, number, or input_number entity for the device to manage.

Step 1: Install the Add-on

For HAOS or Supervised installations:

Go to Settings > Add-ons > Add-on Store.
Open the menu and select Repositories.
Add https://gitlab.com/hanergy.app/hanergy and save.
Find Hanergy in the store and click Install.
Enable Show in sidebar and click Start.

For Docker installations, run:

docker run -d --name hanergy -p 8099:8099 \
  -e HA_URL=http://your-ha-ip:8123 \
  -e HA_TOKEN=your_long_lived_access_token \
  -v hanergy-config:/config/addons/hanergy \
  ghcr.io/cusspvz/hanergy:latest

Step 2: Map Your Sensors

Open Hanergy from the sidebar (or navigate to http://your-ip:8099). The setup wizard prompts for four sensors:

Solar production — the sensor reporting current PV output in watts.
Grid import — power drawn from the grid.
Grid export — power fed back to the grid.
Total consumption (optional) — total household consumption for more accurate surplus calculation.

Select the matching entities from your Home Assistant instance and save.

Step 3: Add Your First Load

Click Add Load and provide:

Name — a descriptive label (e.g., “EV Charger”).
Entity — the Home Assistant entity that controls the device.
Load type — Dynamic (adjustable setpoint), Fixed (on/off), or Deferred (user-triggered).
Priority — position in the cascade (1 = highest priority).
Power settings — minimum and maximum power for the load.

For a dynamic load like an EV charger, Hanergy also needs a feedback sensor (the entity reporting actual power consumption) to close the control loop.

Step 4: Verify Operation

With a load configured, Hanergy begins evaluating surplus immediately. The dashboard shows:

Current surplus — available power after household consumption.
Allocated loads — which devices are currently active and at what setpoint.
Decision timeline — a chronological log of every action with the reason it was taken.

Watch the timeline for a few evaluation cycles to confirm Hanergy is reading sensors correctly and making allocation decisions as expected.

What Happens Next

Hanergy evaluates surplus every 10 seconds. When surplus exceeds the minimum threshold for a load, it activates. When surplus drops, loads shed in reverse priority order. The EMA smoothing filter prevents rapid oscillation from cloud transients, and anti-cycling timers protect equipment from frequent switching.

Add more loads as needed. The free tier supports up to 2 devices. Pro and Max tiers support 10 and unlimited devices respectively.