Skip to content

Device States

At runtime, each managed device is in one of six states. These states are visible on the dashboard and in the decision timeline.

State Reference

State Meaning
Off The load is not consuming surplus. The switch entity is off. This is the default state.
Pending The load is scheduled to activate but is waiting for the startup delay to complete. The delay is the greater of eval_interval_sec * 3 or ramp_time_sec. During this period, the engine verifies that surplus remains sufficient before fully activating the load.
Active The load is currently running and consuming surplus. For dynamic loads, the engine is actively adjusting the parameter setpoint to match available surplus. For fixed loads, the switch is on.
Shedding The load is scheduled to be turned off because surplus has dropped below what is needed. If min_on_time_sec has not elapsed since activation, the load remains in the Shedding state until the guard time passes, then transitions to Off.
Unavailable The Home Assistant entity associated with the load is reporting unavailable. The engine cannot control the load and skips it during evaluation. This typically means the physical device or its HA integration has lost contact.
Error The engine has failed to send commands to the load's switch entity 5 consecutive times. The load is marked as Error and the engine stops attempting to control it. Restarting the add-on resets the error state.

State Transitions

Off ──→ Pending ──→ Active ──→ Shedding ──→ Off
 │                    │            │
 │                    ▼            ▼
 │               Unavailable   Unavailable
 │                    │            │
 └────────────────────┴────────────┴──→ Error

Normal flow

  1. Off to Pending: the engine determines that surplus is sufficient for this load's priority entry. The load enters Pending for the startup delay.
  2. Pending to Active: the startup delay completes and surplus is still sufficient. The load is fully activated.
  3. Active to Shedding: surplus drops and the engine decides to shed this load. If min_on_time_sec has elapsed, the load transitions directly to Off. Otherwise, it remains in Shedding until the guard time passes.
  4. Shedding to Off: the guard time elapses and the load is switched off.

Abnormal states

  • Pending to Off: surplus drops during the startup delay. The load is returned to Off without being activated.
  • Any state to Unavailable: the HA entity stops responding. The engine cannot control the load.
  • Any state to Error: after 5 consecutive command failures, the load is marked as Error. Restart the add-on to clear this state.

Diagnosing State Issues

  • Stuck in Pending: check whether surplus is consistently dropping during the ramp window. See Troubleshooting > Load Issues.
  • Stuck in Error: the underlying HA entity is likely unavailable. Resolve the issue in HA, then restart the Hanergy add-on.
  • Stuck in Shedding: min_on_time_sec has not elapsed. Wait for the guard time to pass or adjust the engine setting.
  • Showing Unavailable: check the entity in HA Developer Tools > States. If it reports unavailable there as well, the issue is upstream of Hanergy.