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–6.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°.

Choosing the right Arm Angle When Fully Open

This is the most important parameter to get right. Set it to the angle where the arm reaches its maximum useful horizontal projection -- not necessarily the arm's full mechanical travel.

For a typical drop-arm awning the arm swings from roughly vertical (0°) outward. Horizontal projection peaks when the arm is at 90° and then decreases as the arm continues past horizontal. At 180° the arm points straight back at the wall and provides no shade at all.

Setting	What it means
max_angle = 90°	100 % open = arm horizontal = maximum shade. Recommended for most drop-arm awnings.
max_angle = 175°	100 % open = arm nearly wall-pointing. Maximum shade occurs around 51 % open.
max_angle = 180°	Same problem: maximum shade at exactly 50 % open; positions above 50 % reduce shade.

Why does this matter? The integration computes the minimum arm extension needed to shade the window and then maps it back to a position percentage. With max_angle=90, that full-extension result maps to positions near 100 %. With max_angle=180, the same full-extension result maps to 50 % because arcsin is bounded at 90 degrees. You will observe the awning seeming to "cap" well below your max_position setting -- this is correct geometry, not a bug.

If your awning's arm physically travels past horizontal (e.g. for ventilation or fabric tension) but the useful shading range ends at horizontal, set Arm Angle When Fully Open = 90. The integration will still command any position from 0-100 % of that range.

max_position is a ceiling, not a target

max_position (under Position Settings) caps how far the integration will command the awning -- it will never send a position above this value. It does not instruct the integration to drive toward that position. The engine computes the geometrically required extension for shade at the current sun angle and then applies the ceiling. Setting max_position = 93 % means "never go above 93 %, but only extend as far as the sun angle requires."

To always drive to a fixed position when the sun is in the window's field of view, use a Custom Position handler.

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.