First Setup¶
When Hanergy opens for the first time, the setup wizard launches automatically. It walks through five steps to get the engine running with a basic configuration.
Verify your sensors first
Before starting the wizard, open Developer Tools > States in Home Assistant and confirm that your solar production, grid import, and grid export sensors are reporting numeric values. This avoids troubleshooting sensor issues mid-wizard.
Step 1 — Welcome¶
The welcome screen gives a brief overview of how the priority cascade works. Read through it, then click Get Started.
Step 2 — Map Energy Sensors¶
Map your Home Assistant energy sensors to the four fields Hanergy needs:
| Field | What to enter | Example entity |
|---|---|---|
| Grid Import | Power being drawn from the grid (W) | sensor.grid_power_import |
| Grid Export | Power being sent to the grid (W) | sensor.grid_power_export |
| Production | Solar or wind generation output (W) | sensor.solar_power |
| Consumption | Total household load (W) — optional | sensor.house_consumption |
The Entities dropdown is populated from your live Home Assistant instance. Start typing the entity name to filter the list.
Signed meters
If your meter reports import and export as a single signed value (positive = import, negative = export), you will need to create a template sensor or an input_number helper in Home Assistant to split it into two separate entities before mapping them here.
Consumption is optional
If you leave the Consumption field empty, Hanergy derives it automatically: consumption = production + grid_import - grid_export. This works correctly in most setups.
Step 3 — Add Your First Device¶
Add a controllable device for the engine to manage. A pool pump makes an excellent first device because it is a simple on/off (fixed) load:
- Enter a Name (e.g., "Pool Pump").
- Select Type: Fixed.
- Set Switch Entity to the switch that controls the pump (e.g.,
switch.pool_pump). - Set Rated Power to the pump's power draw in watts (e.g.,
750). - Click Save Device.
Start simple
Adding a small fixed load first makes it easy to verify the engine is working before introducing more complex dynamic loads like EV chargers or heat pumps.
Step 4 — Create a Priority Entry¶
The priorities screen shows an ordered list. Each entry links a device to a minimum surplus requirement.
Add a priority entry for the pool pump:
- Click Add Priority.
- Select Device: Pool Pump.
- Set Min Surplus to the minimum surplus required before the pump turns on (e.g.,
800W — slightly above the pump's rated power to leave headroom). - Click Save.
The pool pump will now activate whenever surplus solar production exceeds 800 W and deactivate when it drops below that level.
Step 5 — Review and Save¶
The final wizard step shows a summary of your energy sensors, devices, and priorities. Review the configuration and click Save and Start. The engine begins its evaluation loop immediately.
Verifying It Works¶
After completing the wizard, use the main dashboard to confirm that Hanergy is operating correctly.
Check the energy flow display¶
The dashboard shows live values for production, consumption, grid import, grid export, and calculated surplus. If the values match what you see in your Home Assistant energy dashboard, the entity mapping is correct.
Sensor values showing zero or unavailable
If any value shows unavailable or 0 when you expect a real reading, go to Settings > Configuration and verify the entity IDs. Check Developer Tools > States in Home Assistant to confirm the entity exists and is reporting a numeric value.
Check device states¶
Below the energy flow, each configured device shows its current state:
| State | Meaning |
|---|---|
| Off | Device is inactive — insufficient surplus or threshold already met |
| Pending | Engine wants to activate — waiting for hysteresis delay |
| Active | Device is running — current setpoint and estimated power shown |
| Shedding | Engine has issued a turn-off command — waiting for confirmation |
| Unavailable | The Home Assistant entity is not responding |
| Error | The device has exceeded consecutive command failures |
Check the decision timeline¶
The History tab shows a ring buffer of the last 500 evaluation cycles. Each entry includes the timestamp, smoothed surplus at the time of the decision, actions taken with reasons, and remaining surplus after allocation.
Tip
If you see cycles with "skipped: insufficient surplus" during a period of good production, verify that your surplus buffer (Settings > Engine > Surplus Buffer) is not set too high.
Next Steps¶
- Add more devices — configure dynamic loads (EV chargers, heat pumps) and deferred loads (washing machines).
- Fine-tune priorities — set up multi-level priority entries and threshold-based stopping.
- Adjust engine settings — tune the evaluation interval, smoothing, and hysteresis timers.