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 (venetian_tilt_reset_threshold / _direction)	0 (off) / open	enable / close	Actuators that accumulate slat-angle drift over many small moves; close if the motor re-zeroes slats on a close	#663 · #686
Post-settle Hold (venetian_post_settle_hold)	3.0 s	raise	Firmware that re-asserts a tilt shortly after the carriage stops (KNX FGR223) — the hold lets the tilt command win	#370
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	Default-On; sends open_cover/close_cover for 100/0 for a cleaner mechanical reset	#697
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_seconds)	45 s	raise	Slow Zigbee battery shades flagged as manually overridden before the motor even engages	#433
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): the carriage and slats share one motor, so any tilt move shifts position ~3 %. Set Skip-Tilt Mode → suppress so no tilt is sent at the fully-open endpoint, and enable Inverse Tilt if daytime shading is inverted. (#748)
• Cover can't reach 0/100 and keeps chasing it: enable Enforce delta at endpoints so the coupled cover parks at its nearest reachable point (~3/100) instead of being re-commanded. (#679)
• Prefers tilt-first operation: set Operating Mode → tilt_only for hardware that should hold height and only track slat angle. (#357)

See Venetian (Dual-Axis) for the full dual-axis configuration.

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 triggers the stored "My" preset via stop_cover while the cover is stationary. Full details: My Position Support (Somfy RTS). (#199, #197)
• 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): mechanically coupled tilt + lift, so a tilt command at the fully-open endpoint drags the carriage off its resting position (100 → ~97). Set Skip-Tilt Mode → suppress so ACP sends no tilt at the open endpoint, and enable Inverse Tilt if daytime shading is inverted. See the Shelly section above and #748.

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): raise Post-settle Hold so the tilt command is sent after the actuator's re-assert, not before it. (#370, #504)
• Tilt-only KNX/Z-Wave entity under a Vertical config: if the entity exposes only tilt, 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 — see the appendix on why.

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_seconds) above your shade's worst-case engagement delay. (#433, #271)

Velux / Roto roof windows

A window set into a sloped roof needs the tilted-plane sun model, not the vertical-pane one. Choose the Roof window cover type and set roof_pitch (0° = flat skylight, 90° = vertical) and roof_height_above (ridge-occlusion). See Roof / Skylight Window. (#696, #212)

Drop-arm / oscillating awnings

An awning whose arm sweeps through an arc as it opens (e.g. Somfy PositionableScreen) needs the Oscillating awning (drop-arm) cover type and your real arm length (the field accepts up to 6 m). 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	Drop-arm awnings
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 or post on the dual-axis tracking thread #33 so this page can grow.