Configuration Debug Diagnostics

Debug & Diagnostics

The Debug & Diagnostics screen gives you targeted tools for troubleshooting cover behavior — from promoting specific log messages to INFO level, to running the full automation pipeline without ever moving your covers.

Where to find it

Open a cover's options (Settings → Devices & Services → Adaptive Cover Pro → Configure) and choose Debug & Diagnostics from the menu.

Cover Capabilities

At the top of the screen, the integration displays a read-only summary of what each bound cover entity supports — whether it can report position, stop mid-travel, and receive open/close commands. This is detected directly from Home Assistant's entity registry, not from your configuration. Use it to confirm why a cover behaves differently from others (for example, why one cover can be sent to a specific percentage but another only receives open/close commands).

Settings

Dry Run

Option	Default
dry_run	Off

When enabled, the integration runs the full update cycle — pipeline evaluation, sensor updates, diagnostics — but does not send any movement commands to your covers. Every sensor updates normally: the Decision Trace shows the handler that won, and Last Skipped Action records what would have been sent and why.

Use Dry Run to:

• Validate a new configuration before going live
• Confirm that the right pipeline handler fires for a given sun position or sensor state
• Test automation logic in the middle of the day without disturbing your home

⚠️ All other automations and manual commands still work normally — only the commands from this integration are suppressed.

Debug Mode

Option	Default
debug_mode	Off

When enabled, log messages for the selected categories below are promoted from DEBUG to INFO. This makes them visible in the Home Assistant log without adding custom_components.adaptive_cover_pro: debug to configuration.yaml.

Turn off when you are done troubleshooting. Leaving it on permanently adds noise to your log and can make other issues harder to spot.

Log Categories

Option	Default
debug_categories	None selected

Multi-select. Only active when Debug Mode is on. Selecting a category promotes that subsystem's log messages to INFO; unselected categories remain at DEBUG.

Category	What it traces	When to use it
Manual Override	Override detection decisions, grace period, wait-for-target logic	A cover won't stop detecting manual control, or it clears the override too early
Reconciliation	The 1-minute position retry loop	A cover drifts back to an old position after you move it manually
Pipeline	Priority handler chain — which handler fired, which returned None, what position each proposed	The wrong handler seems to be winning, or a handler isn't firing when expected
Motion	Motion sensor events, timeout countdown, transition to timeout state	Motion-based control isn't triggering, or the cover doesn't return to the solar position after motion clears

Select only the categories relevant to the symptom. Running all four at once produces a lot of output and can make it harder to isolate the issue.

Manual Override Event Buffer Size

Option	Default	Range
debug_event_buffer_size	50 events	10–200 (step 10)

Controls how many recent manual-override detection events are kept in a rolling ring buffer. Each event records:

• Timestamp
• Cover entity ID
• Action taken (override started, cleared, extended, etc.)
• Expected position vs. detected position
• Threshold used for detection
• Reason string explaining the decision

Events appear in the HA Diagnostics download for offline analysis. The buffer resets on integration reload.

Increase this value for intermittent issues that require a longer observation window — for example, an override that incorrectly triggers once or twice per day.

Transit Timeout

Option	Default	Range
transit_timeout	45 s	15–600 s (step 5)

How long the integration waits — without seeing forward progress toward the commanded position — before it considers the cover's transit complete and starts watching for manual-override moves again.

The clock resets each time the cover reports it moved closer to the target. A cover that takes 90 seconds to close but sends position updates every few seconds will be protected for the full transit, because each progress report resets the timer. Only if a cover completely stops reporting movement for longer than this value will the protection window end early.

Increase this value if you see the cover incorrectly enter manual override shortly after an automatic sunset or default-position move. This typically happens with large motorized blinds, heavy awnings, or any cover whose full traverse takes more than 45 seconds. As a rule of thumb, set the value to at least 1.5× your longest full-traverse time.

Covers that don't report intermediate positions (e.g. radio-protocol covers that only signal their final position) fall back to measuring elapsed time from when the command was sent. The transit timeout still protects them — it just uses the send timestamp as the reference instead of the most recent position update.

If you're unsure what value to use, start with 120 s for typical slow shades and adjust up or down based on observed behavior.

---

Quick Reference

Symptom	Setting to use
Cover won't stop detecting manual control	Debug Mode + Manual Override category
Cover keeps clearing manual override too early	Debug Mode + Manual Override category
Cover drifts back to the wrong position	Debug Mode + Reconciliation category
Wrong pipeline handler is winning	Debug Mode + Pipeline category
Motion sensor not triggering or releasing	Debug Mode + Motion category
Validate a new config without moving covers	Dry Run
Intermittent override issue, need more history	Increase Event Buffer Size
Slow cover triggers manual override during transit	Increase Transit Timeout

---

Downloading Diagnostics

To download a full diagnostics snapshot: Settings → Devices & Services → Adaptive Cover Pro → three-dot menu → Download Diagnostics. The resulting JSON includes all Debug & Diagnostics configuration values, the manual override event buffer, and a complete snapshot of the last pipeline result.

For a step-by-step troubleshooting guide, see Troubleshooting.