Hardware Compatibility

Hardware Compatibility & Required Settings

Adaptive Cover Pro drives a wide range of cover hardware — Shelly, Somfy, KNX, Zigbee shades, Velux/Roto skylights, drop-arm awnings — and most of it works on the defaults. But some motors and controllers have quirks (mechanically coupled axes, cached slat angles, slow position reporting, open/close-only motors) that need a specific, non-default setting to behave correctly.

This page is the single place to find which hardware needs which setting, drawn from the integration's issue history. Each entry gives the symptom, the setting and value to change, and the issue it traces to.

Golden rule: leave every setting at its default unless your hardware misbehaves in one of the ways described below. The defaults are correct for the large majority of covers. To see what your cover actually supports (report position, stop mid-travel, open/close), check the read-only Cover Capabilities summary.

---

Quick reference — settings to change from default

Each row is a knob you change only when your hardware needs it. Defaults are authoritative (from the integration source).

Setting	Default	Change to	When / hardware	Issues
Skip-Tilt Mode (venetian_tilt_skip_mode)	neutral	suppress	Coupled-axis exterior venetian where a tilt command at the open endpoint drags the carriage off rest (Somfy J4 + Shelly 2PM)	#748 · #777
Enforce delta at endpoints (enforce_delta_at_endpoints)	Off	On	Coupled venetian that can't physically reach 0/100 (closest is ~3/100), so ACP keeps chasing it	#679 · #680
Inverse Tilt (inverse_tilt)	Off	On	Venetian whose tilt axis is wired opposite the HA convention (slats shade the wrong way)	#748
Inverse the state (inverse_state)	Off	On	Cover with a reversed 0/100 position mapping (100 % opens instead of closes)	#344
Operating Mode (venetian_mode)	position_and_tilt	tilt_only	Tilt-first hardware, or overcast-day slat-only operation	#357
Skip Tilt Above Position (venetian_tilt_skip_above)	95 %	tune up/down	Slats hidden in the housing near the top — adjust where tilt stops being sent	#357
Drift-reset threshold / direction / scope (venetian_tilt_reset_threshold / _direction / _scope)	0 (off) / open / all_tilt_commands	enable / close / sun_tracking_only	Actuators that accumulate slat-angle drift over many small moves; close if the motor re-zeroes slats on a close; sun_tracking_only if a Custom Position slot also holds the tilt and shouldn't count toward the reset	#663 · #686 · #808 · Drift reset
Post-settle Hold / Wait Mode (venetian_post_settle_hold / _mode)	3.0 s / fixed_delay	raise / entity_state	Firmware that re-asserts a tilt shortly after the carriage stops (KNX FGR223) — the hold lets the tilt command win; entity_state polls the cover's own state instead of always sleeping the fixed hold	#370 · #801 · Venetian Blinds
My Position (my_position_value + sunset_use_my / custom_position_use_my_*)	unset / Off	set	Open/close/stop-only motors with a stored "My" preset (Somfy RTS / io, Hunter Douglas, Bubendorff)	#199
Position match tolerance (position_tolerance)	3 %	raise (e.g. 6)	Motors that settle a few % short of an endpoint, causing relay clicking / constant re-commands	#507
Use open/close at endpoints (endpoint_use_open_close)	On	leave On — except Off for covers whose reported position doesn't follow open/close (Bond RF bridge and other assumed-state hubs)	Default-On; sends open_cover/close_cover for 100/0 for a cleaner mechanical reset. Turn it Off when the cover answers an Open with state: open but leaves current_position at 0 — position matching can never be satisfied and ACP re-commands the endpoint every cycle	#697 · #1026
Enable position matching (enable_position_matching)	Off	On	Covers that stop short of the commanded position and need re-sending to arrive	#591
Min position during sun tracking (min_position_sun_tracking)	falls back to min	set (e.g. 25 %)	Roller shutters with a bottom slat-slack "dead zone" — skip it while tracking but still close fully at night	#467
Transit timeout (transit_timeout)	45 s	raise	Slow Zigbee battery shades flagged as manually overridden before the motor even engages	#433
Command queue (command_queue)	None (blank)	same name on every cover sharing a transmitter	Several covers on one one-way radio (Somfy RTS, RFXtrx) that occasionally fail to move when the sun triggers them together. No acknowledgement means colliding frames are lost silently. Leave blank on acknowledged protocols. See Command Queue	#1189
Cover type selection	Vertical	Venetian / Horizontal / Oscillating Awning / Roof Window	The cover type itself is the first hardware-correct setting — see Cover Types	#33 · #337 · #212
Roof pitch / ridge height (roof_pitch / roof_height_above)	—	set	Velux/Roto skylights set into a sloped roof	#696
Arm length (arm_length)	—	real arm length (up to 6 m)	Drop-arm / oscillating awnings with a 3–4 m arm	#636

---

By hardware family

Shelly (2PM / 2PM Gen4)

Confirmed working for vertical covers and dual-axis venetians. The Shelly publishes current_position frequently (~1 Hz) and fast actuators back-rotate quickly — ACP's settle detection accounts for both.

• Coupled exterior venetian "pumps" at rest (100 ↔ 97): on a blind where the carriage and slats share one motor, any tilt move physically shifts the reported position by ~3 %. When ACP raises the blind to its fully-open default and then sends a tilt at that endpoint, the hardware settles ~3 % short; ACP reads that as "not arrived" and re-commands, and the cover oscillates between 100 % and ~97 %. Set Skip-Tilt Mode → suppress so no tilt is sent once the blind is at/above the Skip Tilt Above Position, and enable Inverse Tilt if your slats shade toward the sun instead of away from it. (#748)
• Cover can't reach 0/100 and keeps chasing it: ACP normally always sends the 0 % and 100 % endpoints (they bypass the minimum-change gate so a full open/close is guaranteed). On a coupled cover the true endpoint is unreachable — commanding 0/100 lands at ~3/100 — so that guarantee turns into an endless re-command loop. Turn Enforce delta at endpoints → On so 0 % and 100 % also respect the minimum-change gate; the coupled cover then parks at its nearest reachable point instead of being re-commanded. (#679)
• Prefers tilt-first operation: set Operating Mode → tilt_only so ACP holds the carriage at 0 % and tracks only the slat angle. Use this when moving the carriage is disruptive (noise, wear, or a coupled axis) and slat tilt alone gives you the shading you want. (#357)

For the rest of the dual-axis options (slat geometry, tilt modes, migration), see Venetian (Dual-Axis) — but the settings above are complete on their own.

Somfy

Three distinct cases depending on the protocol:

• RTS (open/close/stop only): RTS motors have no set_cover_position, so any mid-range target collapses to 0 % or 100 %. Configure a third landing spot with My Position (my_position_value) plus the opt-in sunset_use_my / custom_position_use_my_* flags — ACP reaches it by issuing stop_cover while the cover is stationary, which triggers the motor's stored "My" preset — giving you a third landing spot between fully open and fully closed. For worked setup examples, see My Position Support (Somfy RTS). (#199, #197) RTS covers — and any cover that never reports position (state stuck at unknown) — also no longer receive the same open/close command on every cycle once they've reached the target; see Known Limitations → Open/Close-Only Covers. (#779)
• Several RTS covers that intermittently ignore a command: RTS has no acknowledgement, so two frames keyed at the same moment collide and are both lost, with nothing logged and no retry. Covers on separate ACP entries share sun geometry, so they compute the same trigger time and fire together. Put every cover on that transmitter on the same Command queue (Movement & Schedule) and they take turns instead, holding the air 5 s after each send. Note the Cover Group stagger does not solve this: it spaces only the commands a group dispatches itself, never a member's own sun tracking. Full detail: Command Queue. (#1189)
• IO via Tahoma: these motors close vertically then back-rotate to set tilt, and publish a late current_position burst (~27 s after settling). ACP tolerates the late publish automatically (a publish-lag window); no setting is normally required. (#357, #408)
• J4 exterior venetian (via Shelly 2PM): on this motor the tilt and lift axes are mechanically coupled, so any slat tilt physically shifts the carriage — moving a fully-open blind from 100 % down to ~97 %. Correct daytime shading needs Inverse Tilt on (so the slats tilt away from the sun), but with it on, ACP's default neutral tilt at the open endpoint inverts to a wire tilt of 0, which drags the carriage down and pulls the blind off its resting position. The J4 also runs its own automatic slat re-adjustment, so multiple systems end up fighting over the same axis. Fix: set Skip-Tilt Mode → suppress, which tells ACP to send no tilt command once the blind is at or above the Skip Tilt Above Position — the blind stays put at rest while keeping the inverted daytime shading. Reported in #748.

Bond bridge (Somfy RMS and other RF motors)

A Bond hub speaks one-way RF, so the entity it publishes is assumed_state: true — it reports what it believes it commanded, not what the motor did. Position-capable Bond covers expose set_cover_position and echo the commanded percentage back into current_position correctly. Open and Close are the exception.

• Target says 100 % but Actual Position stays 0 % (Position Mismatch never clears): on a Bond-bridged Somfy RMS12 awning, cover.open_cover sets the entity to state: open / is_closed: false while leaving current_position at 0 — a self-contradictory state, but that's what the entity publishes. ACP's position matching compares its 100 % target against that 0 % and never converges; because 100 % is a mechanical endpoint it also bypasses the minimum-change gate, so ACP re-sends open_cover on every update cycle. The same cover answers set_cover_position(13) with current_position: 13 immediately, which is what makes the diagnosis unambiguous.

  Fix: turn Use open/close at endpoints (endpoint_use_open_close) → Off for that instance. ACP then sends set_cover_position(100) at the endpoint, which the Bond entity does echo back, and the mismatch clears. Disabling Enable position matching instead only silences the alarm — it leaves the per-cycle re-commands in place and hides real faults. (#1026)

• Awnings reach the 100 % endpoint constantly. With Minimize Movements on and Max coverage steps at 1, any amount of required coverage quantizes straight to full coverage — 100 % for an awning. So an awning on a Bond bridge meets the open/close endpoint on most sunny days rather than occasionally. Raising Max coverage steps gives proportional extension and sidesteps the endpoint most of the time, but fix the routing with endpoint_use_open_close rather than relying on that.

• Why HA can't just poll the truth. There's no position feedback to poll. If the awning is physically extended and HA shows 0 %, the entity is the thing that's wrong, not the motor — which is also why raising Position match tolerance doesn't help here. It's a 0-vs-100 disagreement, not a settling-short one.

KNX (including MDT actuators)

Confirmed working as a single cover entity exposing both position and tilt services. KNX actuators commonly cache a slat angle and re-assert it during or after a move.

• Wrong tilt re-appears after the carriage stops (KNX FGR223): some firmware re-applies its cached slat angle for a moment right after the carriage settles. If ACP sends its tilt during that window, the firmware's re-assert overwrites it and the slats end up at the wrong angle. Raise Post-settle Hold (default 3.0 s) so ACP waits past the firmware's re-assert before sending the tilt — increase it in ~1 s steps until the correct tilt sticks. (#370, #504)
• Tilt-only entity (KNX / Z-Wave) sends the wrong service: an entity that exposes only tilt (no set_cover_position) will ignore position commands and retry in a loop. Choose the Tilt cover type so ACP routes set_cover_tilt_position instead of set_cover_position. (#234)
• The default Skip-Tilt Mode → neutral is correct for KNX: above the Skip Tilt Above Position, ACP deliberately sends a neutral fully-open tilt to overwrite the actuator's cached slat angle, which KNX motors otherwise re-assert on a raised blind. Leave it on neutral unless your blind is a mechanically-coupled exterior venetian.

Slow Zigbee battery shades

Battery-powered Zigbee shades can take longer than the 45 s transit timeout to even start moving, and may emit a closing → open → closing ack flap. That can be misread as a manual override on ACP's own command. Raise Transit timeout (transit_timeout) above your shade's worst-case engagement delay. (#433, #271)

Velux / Roto roof windows

A window set into a sloped roof faces the sun at the roof's angle, not vertically, so the default vertical-pane model starts and stops tracking at the wrong times. Choose the Roof window cover type and set roof_pitch (the roof's slope: 0° = flat skylight, 90° = vertical window) and roof_height_above (how far the ridge sits above the window, so ACP knows when the ridge shades it). With those two values ACP computes sun illumination and shade against the tilted plane correctly. For the full tilted-plane model, see Roof / Skylight Window. (#696, #212)

Drop-arm / oscillating awnings

On an awning whose arm sweeps through an arc as it opens (e.g. Somfy PositionableScreen), the fabric angle — and therefore how much sun it blocks — changes with the open percentage, so ACP needs the arm geometry to compute the shade projection. Choose the Oscillating awning (drop-arm) cover type and enter your real arm length (the field accepts up to 6 m, so a 3–4 m arm is fine). For the angle-vs-position model and the other geometry inputs, see Oscillating Awning. (#636, #586)

---

By cover type

If you know your cover type but not the brand quirk, start here.

Cover type	Most likely hardware settings	Details
Venetian (dual-axis)	Skip-Tilt Mode, Enforce delta at endpoints, Inverse Tilt, Operating Mode, Post-settle Hold	Shelly · KNX · Venetian (Dual-Axis)
Vertical / roller shutter	Inverse the state, Min position during sun tracking, Position match tolerance, My Position (RTS)	Somfy · Configuration: Vertical
Tilt-only	Choose the Tilt cover type so tilt services are routed	KNX · Configuration: Tilt
Horizontal / oscillating awning	Cover-type choice (semantics auto-invert), arm length, Use open/close at endpoints (RF bridges)	Drop-arm awnings · Bond
Roof / skylight window	Roof window cover type, roof pitch, ridge height	Velux / Roto

---

Appendix — why some defaults are what they are

Several defaults exist specifically because of hardware behaviour. Understand these before overriding them.

• Neutral tilt cache-overwrite at the open endpoint (venetian_tilt_skip_mode = neutral): above the skip-above threshold, ACP deliberately sends a neutral fully-open tilt to overwrite the actuator's cached slat angle. KNX and many Shelly venetian motors re-assert the previous angle on a raised blind, so this overwrite is needed. It is wrong only for mechanically-coupled exterior blinds, which is why suppress exists as the opt-in alternative. (#33)
• Back-rotate / publish-lag suppression windows (≈45 s publish lag, ≈6 s startup grace): tuned so late or frequent position publishes from Somfy IO/Tahoma, Shelly 2PM, and KNX aren't misread as a user grabbing the wand. (#357, #408)
• 1 % solar floor is kept for open/close-only covers (to avoid a hard slam shut) but switched off automatically for covers that support set_cover_position, so percent-capable covers can reach a true 0 %. (#572)
• Climate intent → position auto-inverts for horizontal awnings: an awning at 100 % is extended (blocking sun), the opposite of a screen, so the climate logic flips the numeric target by cover type. (#337)
• stop_cover is gated on motion: on RTS/io, Hunter Douglas, and Bubendorff motors a stop_cover on a stationary cover triggers the "My" preset, so ACP only stops covers that are actually moving — an emergency_stop won't drive an idle awning out to My. (#197)

---

Hardware not listed here?

If your motor or controller needs a setting that isn't documented above — or works perfectly on defaults and you'd like it confirmed — please open an issue so this page can grow.