Configuration Position Matching

Position Matching

Position matching is the background reconciliation loop that re-sends a cover's target position until the cover reports it has arrived. As of v2.28 it is off by default and opt-in: the integration commands each cover once and then trusts where it lands. This page explains what the setting does and when you should turn it on.

The toggle lives on the Position Settings step of the config/options flow (Enable position matching), and can also be changed at runtime through the Runtime Configuration Services (enable_position_matching in the position-limits service).

What it does

When on, after the integration sends a target it keeps re-sending that same target every cycle (up to a few retries) until the cover's reported position is within the Position Match Tolerance. This is the classic behaviour documented in Position Verification: resilient to dropped commands and momentary stalls, at the cost of re-commanding covers that settle short.

When off (the default):

• The cover is commanded once. If it stops short of the target, the integration does not resend.
• If the cover settles more than the Position Match Tolerance away from the commanded position, that is treated as a manual override: automatic control pauses for the configured override duration, exactly as if someone had moved the cover by hand. New sun-driven targets are also held off for that duration.

Setting	Default	Effect
Enable position matching	Off	On: resend until the cover reaches target. Off: command once; a settle past tolerance becomes a manual override.

Note: This setting only governs the reconciliation resend. The initial command, the delta gates, and all the override handlers are unaffected.

Why off is the default

Re-sending until a cover "arrives" sounds harmless, but it fights two common situations:

• Manual remote stops. If you stop a cover with its physical remote (an RF/RTS remote sends nothing back to Home Assistant), the integration only sees "didn't reach target" and drives the cover back toward the computed position. With matching off, the stop sticks.
• Covers that never quite hit the number. Plenty of motors settle a percent or two short, or self-correct on their own. Re-commanding them just produces extra relay clicking and motor wear.

The integration cannot reliably tell "the motor stalled short" from "the user stopped it on purpose" — both look identical. Commanding once and respecting the result is the safer default for most installs.

When to enable it

Turn Enable position matching on if:

• Your cover intermittently drops commands and sometimes ends up well short of where it was told to go, and you want the integration to keep trying until it arrives.
• You have a flaky Z-Wave/Zigbee link where a single command is not reliably delivered.

When to leave it off (the default)

Leave it off if:

• Your covers reliably reach the target on the first command.
• Your covers self-heal (correct their own position over time).
• You stop covers with a physical remote and want that stop to stick instead of being re-driven.

Note: "Settles past tolerance → manual override" uses the Position Match Tolerance as the trigger band and the manual-override duration from your manual-override settings. A cover that lands within tolerance is treated as arrived and does not trigger an override.

Diagnostics

The diagnostics download reports the current state under configuration as enable_position_matching (and the position_tolerance it uses). The per-entity retry counters described in Position Verification only advance while matching is on.