Configuration Oscillating Awning

Oscillating (Drop-Arm) Awning

An oscillating awning — also called a drop-arm or pivoting-arm awning — differs from the standard Horizontal awning in one important way: the arm sweeps through an arc as it opens, so the fabric's angle and horizontal reach change with the open percentage rather than staying at one configured angle.

If your awning is mounted on the wall above the window and the arm rotates outward/downward as it extends (e.g. a Somfy PositionableScreen via Overkiz), this is the type to choose.

Choose Oscillating awning (drop-arm) in the cover-type picker during setup.

How it works

The pivot arm of length Arm Length swings from a closed angle to a fully-open angle. The integration models the sweep as linear in the open percentage:

arm_angle(p%) = min_angle + (max_angle − min_angle) × p / 100

The fabric tip's horizontal reach at angle θ is arm_length × sin(θ). To shade the window at your configured shaded distance, the integration computes the horizontal reach it needs and then finds the open percentage whose arm angle projects that far.

Because the angle is derived from position, the fixed Awning Angle field used by the standard horizontal awning is not shown for this cover type.

Geometry parameters

Field	Default	Range	Meaning
Window Height	2.1 m	0.1–50 m	Height of the glazing the awning shades.
Window Depth (Reveal)	0.0 m	0.0–5 m	Optional recess depth for angled-sun accuracy.
Window Sill Height	0.0 m	0.0–50 m	Optional height of the sill above the floor.
Arm Length	0.8 m	0.1–3.0 m	Length of the pivot arm from the wall pivot to the fabric edge. The maximum horizontal reach.
Arm Angle When Closed	0°	0–180°	Arm angle at 0 % open. Typically 0° = arm vertical against the wall.
Arm Angle When Fully Open	175°	0–180°	Arm angle at 100 % open.
Housing Offset Above Window	0.0 m	0.0–1 m	Vertical offset of the pivot above the window top. Set 0 when the housing sits flush with the window top.

Lengths are shown in the unit Home Assistant is configured for (metric or US-customary).

The bound cover entity should support set_cover_position so intermediate positions across the arc can be commanded. If no bound cover advertises set_position, only open/close is issued and the awning can't track the sun smoothly — a warning is shown during setup.

Worked example

From the reporter's measurements (#412):

• Arm length 0.8 m, mounted 0.8 m above the bottom edge of the window.
• Housing 11 × 11 cm, flush with the window top.
• Total sweep 175° — so the arm opens 1.75° per 1 % of position.

Enter Arm Length 0.8, Arm Angle When Closed 0, Arm Angle When Fully Open 175, and your window height. At 50 % open the arm sits at ≈ 87.5°.

Notes & limitations

• This is a first-order geometric model (linear arm sweep, arc projection). It captures the essential angle-vs-extension behaviour; if your hardware's angle curve is non-linear, the closed/open angles still bound the sweep correctly.
• Everything else — sun tracking, position limits, climate, weather safety, overrides — works exactly as it does for other cover types.

See also: Cover Types · Horizontal awning.