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.

How to measure traverse time:

1. Enable Dry Run (above) so no automatic commands fire.
2. Note the current time and manually close the cover fully.
3. Note when it stops and calculate the elapsed seconds.
4. Set Transit Timeout to that value plus a 20–30 s buffer, then disable Dry Run.

---

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.

Privacy: what's in the file

The diagnostics file is a JSON snapshot of your configuration, the current sun and cover math, and a short rolling buffer of recent events. It does not carry credentials, location coordinates, account info, IP addresses, or anything else that identifies you or your home outside of Home Assistant.

The realistic concern most users have is that entity IDs can leak room names if entities are named after rooms or people (cover.master_bedroom_blinds, binary_sensor.kids_room_motion). Those names appear in several places in the file. You can redact them in any text editor before attaching to an issue, see If you want to redact before attaching below.

What's in the file

Field	What it reveals
config_data.name	The instance name you chose when adding the integration (e.g. "Living Room Blinds").
config_options.group	List of cover entity IDs this instance controls.
config_options.motion_sensors, force_override_sensors, custom_position_sensor_1..4, climate / presence / weather / lux / irradiance / cloud entities	Entity IDs of the sensors wired into the integration.
configuration.* (azimuth, FOV, elevation limits, blind spot, position limits)	Your window geometry and tracking limits.
last_cover_action, last_skipped_action, covers, cover_commands, manual_override_state, primary_axis_suppression_last_24h	Keyed by cover entity ID, same entity-name vector as above.
event_timeline	Recent override, pipeline, and motion events. Each entry has a timestamp and entity ID. Buffer is bounded (10–200 entries, default 50).
sun_azimuth, sun_elevation, gamma	Sun position rounded to 0.1°. Already visible on your HA frontend.
temperature_details.inside_temperature / outside_temperature	A single current-temperature reading at export time.
climate_conditions.is_presence	Boolean snapshot of whether the configured presence entity currently reads "home".
Time-window settings (start_time, end_time, sunrise / sunset offsets)	The hours configured for tracking.

What's NOT in the file

• Home Assistant installation ID, hostname, or URL
• Latitude or longitude
• Account info, user ID, email, or username
• IP addresses
• API keys, access tokens, or other secrets
• Weather location names or external service identifiers

If you want to redact before attaching

The file is plain JSON. The simplest approach:

1. Open it in any text editor.
2. Find-and-replace your entity-ID stems with neutral placeholders, e.g. master_bedroom → room1, kids_room → room2. Use the same replacement consistently so the relationships in the file stay readable.
3. Save and attach.

This keeps the file fully useful for triage while removing the names you'd rather not share.

If you spot a field that you consider personal information and the table above doesn't account for it, please open an issue. I'd rather widen this list than have you hold back diagnostics on a bug we could otherwise close in a single round trip.