Diagnostic Sensors

Diagnostic Sensors

Every decision the integration makes is visible in a diagnostic sensor. This page is the per-sensor / per-attribute reference. For a symptom-driven walkthrough, see Troubleshooting.

Entity IDs follow the pattern sensor.{device_name}_{suffix} (or binary_sensor.…), where {device_name} is the slug of the device name you chose at setup.

Where to start

Most "why did it do that?" questions are answered by four sensors:

Sensor	What it tells you
sensor.{device}_decision_trace	The winning pipeline handler (state) plus every handler that was evaluated (attribute).
sensor.{device}_cover_position	The target position, with reason, control_method, and position_explanation attributes explaining how it was chosen.
sensor.{device}_last_skipped_action	Why the most recent commanded move was suppressed (delta-position / delta-time / dry-run / disabled).
sensor.{device}_control_status	The current operational state and why automatic control isn't running, when it isn't.

If you're not sure where to look, start with decision_trace.

Pipeline & decisions

sensor.{device}_decision_trace

State: the winning pipeline handler's identifier — one of solar, default, manual_override, force_override, weather_override, cloud_suppression, custom_position, glare_zone, motion_timeout, summer, winter. unknown until the first pipeline run.

Attribute	Meaning
trace	List of every handler evaluated in priority order. Each entry has handler, matched (true/false), reason (why it matched or was skipped), position (what it would have proposed), and optionally tilt.
reason	One-line explanation of why the winning handler won.
enabled_handlers	Which handlers are configured for this entry (the rest are skipped before the pipeline even runs).
bypass_auto_control	True when the winning handler bypasses the Automatic Control switch (Force Override and Weather Override do; safety handlers must always fire).
default_position, configured_default, configured_sunset_pos, is_sunset_active	The fallback the pipeline would use absent any override, plus whether the sunset window is currently active.
in_time_window	True when inside the configured operational hours.
sun_azimuth, sun_elevation, gamma	Current solar geometry — see also sun_position.
in_field_of_view, elevation_valid, in_blind_spot, sunset_window_active	Sun-validity flags the solar/default handlers consult.
sun_state	One-word classification of the sun's relationship to the window, derived from the validity primitives: hitting (direct sun is valid and the solar handler is engaging), in_fov_not_valid (sun is within the field of view but not driving the cover — e.g. elevation out of range, blind spot, or sunset window active), or outside_fov (sun is outside the tracking arc). Mirrored into the downloaded diagnostics under sun_validity.
weather_active_conditions, weather_in_clear_delay	Only present when the weather handler is winning.
custom_position_active_slot	Only present when a Custom Position handler wins. 1-based slot number (1–4) identifying which custom position slot is in control. Lets automations and the companion card branch on the active slot without parsing the reason string.
custom_position_minimum_mode	Only present when the winning slot uses minimum mode. true when the configured floor is raising the cover above the raw autonomous calculation (floor is actively constraining); false when the raw calc already meets or exceeds the floor (floor is a no-op). Absent in exact mode or on the use_my path.

Example trace shape:

trace:
  - handler: force_override
    matched: false
    reason: "no configured sensor active"
    position: null
  - handler: weather_override
    matched: false
    reason: "wind 12 km/h below threshold 40"
    position: null
  - handler: solar
    matched: true
    reason: "sun in FOV at gamma -23°"
    position: 67

sensor.{device}_control_method (legacy alias)

Standalone sensor whose state mirrors decision_trace's state. Useful when you want a single string in an automation trigger without parsing attributes. Same value set as above, plus the historical names solar and default for the calculated/idle cases.

sensor.{device}_control_status

State: the operational state of automatic control, summarising why the integration is (or isn't) actively driving the cover. Examples: manual_override, outside_time_window, invalid_elevation, in_blind_spot, plus the winning-handler name during normal operation.

Attribute	Meaning
reason	Human-readable explanation of the current state.
automatic_control_enabled	Mirrors the Automatic Control switch.
time_window_status, after_start_time, before_end_time	Where you are in the operational time window.
sun_validity_status, valid_elevation, in_blind_spot	Why solar tracking is or isn't engaging.
manual_covers	List of cover entity_ids currently in manual-override state (only when state == manual_override).
delta_position_threshold, delta_time_threshold_minutes	The thresholds the command service uses to decide whether to send.
position_delta_from_last_action, seconds_since_last_action	How close the current calculation is to triggering a fresh command.
last_updated	Timestamp of the last full update cycle.

sensor.{device}_last_cover_action

State: short summary of the most recent move, e.g. set_cover_position → living_room_blind at 14:23:07.

Attribute	Meaning
entity_id, service, position, timestamp	What was sent, to which cover, when.
calculated_position, inverse_state_applied	The position before HA's inverse-state convention was applied.
covers_controlled	How many covers the same command targeted.
threshold_used, threshold_comparison	The delta threshold the command had to clear, and the comparison that passed.

sensor.{device}_last_skipped_action

State: the machine-readable reason the most recent commanded move was suppressed. No action skipped when nothing has been suppressed yet.

State	Meaning
delta_too_small	Change less than the configured minimum delta. Check position_delta vs. min_delta_required attributes.
time_delta_too_small	Not enough time since the last move. Check elapsed_minutes vs. time_threshold_minutes attributes.
manual_override	Automatic control is paused because a manual move was detected.
auto_control_off	The Automatic Control switch is off.
no_capable_service	No usable HA service found for this cover entity.
service_call_failed	HA service call was sent but threw an error. Check the HA logs.
integration_disabled	The integration is disabled in HA. Re-enable it under Settings → Devices & Services.
dry_run	Dry-run mode is active; commands are logged but not sent. Disable in the integration options.
cover_unavailable	The underlying cover entity is not yet registered or is reporting unavailable. Common right after HA restart on platforms that load late (e.g. Homematic IP); the integration retries automatically once the entity comes online.

Attribute	Meaning
entity_id, current_position, calculated_position	The candidate move that was skipped.
position_delta, elapsed_minutes	How far below threshold the move was.
min_delta_required, time_threshold_minutes	The thresholds the move had to clear.
trigger	What initiated the attempt (solar, startup, sunset, etc.).
timestamp	When the skip happened.

Geometry & sun

sensor.{device}_sun_position

State: current solar azimuth in degrees.

Attribute	Meaning
elevation	Sun elevation above the horizon.
gamma	Signed angle between the sun and the window normal — the core input to all position calculations.
gamma_interpretation	Plain-English bucket: nearly perpendicular (<10°), oblique angle (<45°), steep angle (<80°), nearly parallel.
gamma_absolute_angle, gamma_direction	Absolute value and left / center / right of the window normal.
window_azimuth, fov_left, fov_right	The configured window orientation and field-of-view spread.
azimuth_min, azimuth_max, in_fov	Computed FOV edges and whether the sun is currently inside them.
min_elevation, max_elevation	Configured elevation cut-offs for solar tracking.
blind_spot_range	When a blind spot is configured, the angular range it covers.

sensor.{device}_start_sun / sensor.{device}_end_sun

State: time of day the sun enters / exits the window's field of view (5-minute resolution). Attributes carry the corresponding azimuth and elevation.

binary_sensor.{device}_sun_infront

on when the sun is geometrically in front of the window inside the configured FOV. The same flag fed into the solar handler.

Override & manual state

sensor.{device}_manual_override_end_time

State: timestamp when the most-recent-expiring manual override will release. unknown when no cover is currently in manual mode.

Attribute	Meaning
per_entity	Dict of cover_entity_id → ISO timestamp for every cover currently in manual override.

sensor.{device}_force_override_triggers

State: count of configured Force Override sensors that are currently on. null when no Force Override sensors are configured.

Attribute	Meaning
per_sensor	Dict of sensor_entity_id → state for every configured Force Override sensor.
total_configured	How many Force Override sensors the entry has configured.

binary_sensor.{device}_manual_override

on when any managed cover is currently in manual-override state. Attribute manual_controlled lists the affected entity_ids.

binary_sensor.{device}_glare_active

on when the Glare Zones handler is currently extending the cover to shield a protected floor zone (vertical blinds only, when Glare Zones is enabled).

Climate & motion

sensor.{device}_climate_status

State: Summer Mode, Winter Mode, or Intermediate. Only present when Climate Mode is configured.

Attribute	Meaning
active_temperature, temperature_unit	The temperature value driving the decision.
indoor_temperature, outdoor_temperature, temp_switch	Both readings and which direction (summer / winter) the comparison is using.
is_presence, is_sunny	Presence-entity state and weather-state-matches-sunny-conditions flag.
lux_active, irradiance_active	True when the corresponding sensor is below its low-light threshold (only present when configured).

sensor.{device}_motion_status

State: motion_detected, timeout_pending, no_motion, holding, waiting_for_data, or not_configured.

Attribute	Meaning
motion_timeout_seconds	The configured timeout.
last_motion_time	ISO timestamp of the last motion event.
motion_timeout_end_time	When the timeout will fire (only present when a timeout is pending or active).

Verification & mismatch

sensor.{device}_position_verification

State: the maximum retry count across all managed covers (0 when everything is at target). Use it to spot covers that aren't honouring their commands.

Attribute	Meaning
max_retries	The configured retry ceiling.
per_entity	Dict of cover_entity_id → {retry_count, last_reconcile_time, …} per-cover diagnostics.
last_reconcile_time	Latest reconcile timestamp across all covers.

See Position Verification for the reconcile loop's full behaviour.

binary_sensor.{device}_position_mismatch

on when any managed cover's reported position diverges from the integration's target by more than the configured tolerance. Disabled by default — enable it in the entity registry when you want a single alert flag.

Position-derivation attributes on cover_position

sensor.{device}_cover_position is a main sensor (not diagnostic), but it carries several attributes that are essential when the number looks wrong even though decision_trace looks right:

Attribute	Meaning
raw_calculated_position	The pure geometric sun-tracking position before min/max limits, climate adjustments, or HA's inverse-state convention are applied. Compare against the published state to see what's modifying it.
edge_case_detected	true when the geometric solver tripped an edge-case branch (very low elevation, near-parallel sun, etc.). Combined with safety_margin > 1, this explains "the position jumped".
safety_margin	Multiplier (≥1.0) applied to the geometric calculation at steep gamma or extreme elevations. Adds conservative coverage.
effective_distance	The distance used by the solver after sill-height offset. Useful when the calculated position seems off for a given window geometry.
actual_positions	Dict of cover_entity_id → current reported position for every managed cover.
all_at_target	true when every cover is within position tolerance of the target. false means at least one cover is still moving or stuck.
reason, control_method, position_explanation	The same fields exposed on decision_trace and control_method — mirrored here for convenience.

Symptom → sensor lookup

For step-by-step diagnosis, start at Troubleshooting. The table below is the quick index when you already know what symptom you're chasing.

Symptom	First sensor to check
Cover moved unexpectedly	decision_trace.state then decision_trace.trace
Cover didn't move when expected	last_skipped_action.state
Target position doesn't match calculation	cover_position.raw_calculated_position + cover_position.safety_margin
Cover is in manual mode and won't release	manual_override_end_time.per_entity
Climate mode isn't switching to summer/winter	climate_status.active_temperature + temp_switch
Motion timeout never fires	motion_status.state + last_motion_time
A Force Override sensor isn't taking effect	force_override_triggers.per_sensor
Calculated position is right but cover isn't moving there	position_verification.per_entity + binary_sensor.{device}_position_mismatch
Solar tracking is paused	control_status.sun_validity_status + sun_position.in_fov
Outside operational hours unexpectedly	control_status.time_window_status

Download Diagnostics (JSON snapshot)

Download path: Settings → Devices & Services → Adaptive Cover Pro → ⋮ → Download Diagnostics. For the Dry Run / Debug Mode workflow around reproducing issues without moving covers, see Debug & Diagnostics.

The JSON contains:

• meta — integration version, cover type, coordinator health
• solar — sun azimuth/elevation, gamma
• position — calculated position, control status, position explanation, delta/time thresholds, geometric calc details
• decision_trace — full per-handler decision chain
• time_window — operational hours state and configured defaults
• sun_validity — elevation, blind-spot, sunset-window flags, plus the derived sun_state (hitting / in_fov_not_valid / outside_fov)
• climate — active temperature, indoor/outdoor, strategy, climate conditions
• last_action, last_skipped_action — most recent command + most recent skip
• covers — live cover entity states and capabilities
• manual_override_state — per-entity manual override state
• configuration — every option value the entry currently uses
• debug_info — event timeline, manual override history, cover-command states

Privacy: the snapshot contains entity IDs and position history but no credentials or location data, so it's safe to attach to public GitHub issues.

See also

• Troubleshooting — symptom-driven walkthrough
• Debug & Diagnostics — Dry Run + log categories
• Entities — every entity the integration exposes, not just diagnostics
• How It Decides — pipeline priority order and what each handler does