Skip to content

Load Control Issues

Troubleshooting problems with devices not activating, cycling rapidly, or getting stuck in unexpected states.

Load Not Activating

If a load is not turning on despite apparent solar surplus, work through this checklist in order:

1. Is the switch entity available?

Confirm the switch entity is present and not unavailable in HA Developer Tools > States. If the entity is unavailable, the underlying device or integration has lost contact -- resolve this in HA first.

2. Is surplus actually sufficient?

The engine requires: smoothed_surplus > min_surplus_w + surplus_buffer_w

Check the actual smoothed surplus value on the dashboard. Remember that surplus_buffer_w (default: 100 W) is subtracted before comparison, so a min_surplus_w of 1400 W requires at least 1500 W of raw surplus.

3. Has the minimum off time elapsed?

If the load was recently turned off, min_off_time_sec must pass before it can be reactivated. The default is 180 seconds (3 minutes). Check the Decision Timeline for a "min off time" skip reason.

4. Is the priority entry enabled?

Go to Settings > Priorities and verify the entry's enabled toggle is on.

5. Is it a deferred load awaiting a trigger?

Deferred loads (washing machine, dishwasher) only activate after a manual user trigger. They will not activate on surplus alone. Check whether the trigger entity has been activated.

6. Check the Decision Timeline

The dashboard shows a rolling log of engine decisions, including the specific reason each load was skipped. This is the fastest way to identify the blocking condition.

Rapid Cycling (Load Switching On and Off Repeatedly)

Rapid cycling indicates that surplus is hovering near the activation threshold. The load activates when surplus briefly exceeds the threshold, then sheds when it drops below.

Solutions:

  • Increase min_on_time_sec -- the default is 120 seconds. Once activated, the load must stay on for at least this duration. For pool pumps and compressor-based equipment, 300-1800 seconds is recommended.

  • Increase min_off_time_sec -- the default is 180 seconds. This prevents rapid reactivation after a turn-off.

  • Lower smoothing_alpha -- a smaller value (e.g., 0.2) gives the EMA more inertia, smoothing out transients. This prevents the smoothed surplus from oscillating around the threshold.

  • Increase surplus_buffer_w -- adds a safety margin above the load's min_surplus_w. A larger buffer means the load only activates when surplus is comfortably above the threshold.

  • Increase min_surplus_w on the priority entry -- raise the threshold so the load only activates when surplus is well above its power draw.

Load Stuck in "Pending" State

When a load transitions to active, it enters a Pending state for a startup delay. The delay is calculated as the greater of eval_interval_sec * 3 or ramp_time_sec. With the default 10-second evaluation interval, this is at least 30 seconds.

If a load appears permanently stuck in Pending:

  • Check ramp_time_sec. If it is set to a high value (e.g., 120 seconds for a heat pump), the pending period is correspondingly long. This is intentional.
  • Check whether surplus is dropping during the ramp window. During the pending period, the engine monitors surplus. If surplus drops below zero within this window, the load may be shed back to inactive before it fully activates.
  • Verify the load is not being shed by a higher-priority constraint. If grid import suddenly spikes during the pending period, the grid import protection may cancel the activation.

Load Stuck in "Error" State

After 5 consecutive failed commands to a Home Assistant switch entity, the engine marks the load as Error and stops attempting to control it.

To recover:

  1. Check the switch entity in HA Developer Tools > States. It is likely unavailable or the underlying integration has lost its device.
  2. Resolve the issue in Home Assistant (restart the integration, check the physical device).
  3. Restart the Hanergy add-on. This resets all error states. Go to Settings > Add-ons > Hanergy > Restart.
  4. After restart, verify the entity is available before the engine begins evaluating again.

Dynamic Load Not Adjusting Its Setpoint

For loads with a controllable parameter (charge amps, temperature setpoint):

  • Verify param_entity is correct. The entity must be a number.* or input_number.* entity that accepts writes. Check in HA Developer Tools > States.

  • Setpoint changes are rate-limited. Only one adjustment is made per setpoint_interval_sec (default: 30 seconds). If the setpoint is not moving, wait for the interval to elapse and check again.

  • Deadband prevents micro-adjustments. The calculated new setpoint must differ from the current setpoint by at least one step size. If surplus change is small, no adjustment is emitted.

  • Check parameter range. The engine clamps the setpoint between param_min and param_max. If both are close together, there is very little room for adjustment.