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).

Upgrading from an earlier version

The off-by-default behaviour applies to newly added covers only. Covers that already existed before this feature shipped are migrated with Enable position matching on, so upgrading does not change how your existing covers behave: they keep the reconcile/chase loop they had before. If you would rather they adopt the new command-once default, turn the toggle off on the Position Settings step. New covers you add after upgrading start with matching off, as described above.

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.

Venetian blinds benefit most

Venetian (dual-axis) setups are the strongest candidates for turning this on:

• Two axes have to settle, not one. Every command sets both the carriage (vertical) position and the slat tilt. Reconciliation watches the carriage position and re-sends it if the cover stops short — with matching off, a carriage that lands short is simply left there (and, past the tolerance, parked as a manual override).
• Vertical motion back-rotates the slats. Venetian motors (KNX, Somfy IO, Shelly 2PM) drag the slats off their commanded angle whenever the carriage moves — that's why the integration sequences the position move first and the tilt correction second. A carriage that didn't reach target leaves the slats at the wrong geometry; re-sending the position is what restores it.
• Slow buses report late. Those same motors publish their position seconds (sometimes tens of seconds) after physically stopping, so the first settle reading is the least reliable. The once-a-minute reconciliation re-check, after the true position has been published, is what catches a genuine shortfall — and that re-check is exactly what matching-off removes.

Because the dual-axis settle is inherently noisier, the matching-off default is also more likely to mis-read a not-yet-converged venetian as a manual override and pause automation when the cover just needed another nudge. If your venetian blinds occasionally end up at the wrong height or slat angle, enable position matching.

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.