Engine Settings¶
Engine settings control how frequently Hanergy evaluates surplus, how it protects equipment from rapid cycling, and how aggressively it reacts to power fluctuations.
All settings have sensible defaults. Most users will not need to change them during initial setup — but fine-tuning them can improve performance for specific environments.
Settings Reference¶
| Setting | Default | Description |
|---|---|---|
| Evaluation Interval | 10 s | How often the engine checks surplus |
| Min On Time | 120 s | Minimum time a device stays on after activation |
| Min Off Time | 180 s | Minimum time a device stays off before reactivation |
| Grid Import Limit | 0 W (disabled) | Maximum allowed grid draw |
| Surplus Buffer | 100 W | Reserved headroom subtracted from surplus |
| Setpoint Interval | 30 s | Minimum time between setpoint changes |
| Smoothing Alpha | 0.3 | EMA smoothing factor (0 = smooth, 1 = reactive) |
Evaluation Interval¶
Default: 10 seconds
How often the engine's main evaluation loop runs. On each tick the engine reads all sensor values, recalculates surplus, and decides whether to activate, shed, or adjust any devices.
A lower value makes the system more responsive to sudden changes in production (e.g., cloud shadows) but increases the number of Home Assistant API calls. For most residential setups, 10 seconds is a good balance.
When to adjust
- Decrease to 5 s if you have highly variable production (frequent cloud cover) and want faster reactions.
- Increase to 30-60 s if your solar production is very stable or you have a large battery buffer absorbing transients.
Min On Time¶
Default: 120 seconds (2 minutes)
The minimum time a device must remain on after being activated. Even if surplus drops below the required level, the engine will not shed the device until this time has elapsed.
This setting primarily protects compressor-based equipment — air conditioners, heat pumps, refrigeration units — from short-cycling, which causes mechanical wear and can trigger thermal protection faults. For purely resistive loads like water heaters, the protection is less critical but still prevents unnecessary relay chatter.
Do not set too low for compressor equipment
Heat pumps and air conditioners typically require a minimum run time of 2-5 minutes to avoid damage. Check your equipment's documentation for the manufacturer's recommended minimum cycle time.
Min Off Time¶
Default: 180 seconds (3 minutes)
The minimum time a device must remain off before it can be activated again. This is the companion to Min On Time and ensures equipment has time to recover between cycles.
For heat pumps and air conditioners, the off-time allows refrigerant pressure to equalize before the next start. Setting this too low can cause repeated failed starts and compressor damage.
When to adjust
- Increase to 300 s (5 min) for older compressor equipment with strict cycling requirements.
- Decrease to 60 s for resistive loads (water heaters, infrared heaters) where short cycling is not a concern.
Grid Import Limit¶
Default: 0 W (disabled)
A hard ceiling on how much power the engine allows to be drawn from the grid. When grid import approaches this limit, the engine begins shedding devices — even if they have not yet reached their priority thresholds.
Set this to 0 to disable the limit entirely.
When to use a grid import limit
- Your utility tariff has a demand charge above a certain import threshold.
- Your grid connection has a physical capacity constraint.
- You are operating in a microgrid or off-grid scenario with limited grid availability.
Surplus Buffer¶
Default: 100 W
A safety margin subtracted from the calculated surplus before the engine decides whether to activate new devices. If the engine calculates 500 W of surplus and the buffer is 100 W, only 400 W is considered available for new devices.
This buffer exists because sensor readings have measurement lag and the engine runs on a fixed interval. Without a buffer, a device might be activated based on a momentary surplus reading, only for the next tick to reveal that grid import has begun.
When to adjust
- Increase to 200-300 W if devices cycle on and off rapidly in partly-cloudy conditions.
- Decrease to 50 W if you want the system to be more aggressive about using available surplus and your sensors update quickly.
Setpoint Interval¶
Default: 30 seconds
The minimum time between consecutive setpoint changes for dynamic devices. Even if the engine calculates a different optimal setpoint on every tick, it only sends a new command once this interval has elapsed.
This prevents excessive writes to Home Assistant entities and avoids oscillation in the setpoint value. Most modulating loads (EV chargers, inverters) also have their own internal rate-limiting, so sending commands more often than every 30 seconds typically has no practical effect.
When to adjust
- Decrease to 15 s if your dynamic devices respond quickly and you want tighter surplus tracking.
- Increase to 60 s if you observe setpoint hunting (the value bouncing back and forth between two levels).
Smoothing Alpha¶
Default: 0.3
The alpha factor for the Exponential Moving Average (EMA) applied to raw sensor readings before surplus is calculated. The formula is:
| Alpha Range | Behavior | Best For |
|---|---|---|
| 0.1 - 0.2 | Heavily weighted toward history — very stable, slow to react | Noisy sensors, wind turbines, highly variable conditions |
| 0.3 - 0.5 | Moderate — filters spikes without significant lag | Most residential solar setups (default range) |
| 0.7 - 0.9 | Heavily weighted toward current reading — fast reactions | Reliable sensors, stable production, maximum responsiveness |
When to adjust
- Decrease toward 0.1 if your sensors are noisy or your production source is highly variable (e.g., wind, frequent cloud cover). This filters out spikes at the cost of slower reactions.
- Increase toward 0.7 if your sensors are reliable and you want maximum responsiveness. The engine will react faster to real changes but may also react to sensor noise.
Recommended Starting Configuration¶
For most residential solar setups, the defaults work well. Here is a summary of recommended starting values:
| Setting | Value | Rationale |
|---|---|---|
| Evaluation Interval | 10 s | Good balance of responsiveness and API load |
| Min On Time | 120 s | Safe for compressor equipment |
| Min Off Time | 180 s | Allows pressure equalization |
| Grid Import Limit | 0 W | Disabled until needed |
| Surplus Buffer | 100 W | Absorbs measurement lag |
| Setpoint Interval | 30 s | Prevents command flooding |
| Smoothing Alpha | 0.3 | Moderate smoothing |
Iterate after observation
Run with defaults for a few sunny days and review the decision timeline in the History tab. Adjust one setting at a time based on observed behavior — changing multiple settings simultaneously makes it difficult to attribute improvements or regressions.