Configuration Roof Window

Roof / Skylight Window

A cover type for a window set into a sloped roof — a skylight, a Velux-style roof window, or any glazing whose plane is tilted away from vertical. Instead of treating the glass as a vertical pane, the engine computes sun illumination and shade projection against the tilted plane, so tracking starts and ends at the right times for a pitched roof.

Choose Roof window in the cover-type picker when you add or reconfigure an instance.

Roof windows are a position-only cover type (open/close, no slat tilt). They drive the carriage to a coverage percentage exactly like a vertical blind, but the geometry behind that percentage is pitch-aware.

---

Geometry options

Two settings are specific to roof windows, on top of the usual window dimensions and sun acceptance angles:

Setting	Range	Default	Meaning
Roof Pitch	0–90°	40°	The slope of the glass, measured from horizontal. 0° is a flat skylight (sun-direction-independent — lit whenever the sun is above the horizon). 90° is a vertical window (behaves identically to a vertical blind). A typical roof window sits around 30–50°.
Roof Height Above Window	0.0–10.0 m	0.0 m	The along-slope distance from the top of the window to the roof ridge. When greater than 0, it enables the ridge-occlusion gate (see below). Leave it at 0 if the window reaches the ridge with no roof above it.

The standard window settings — height, width, reveal depth, sill height, distance to the floor area, and the sun acceptance angles — work the same as for a vertical window and are entered in your Home Assistant unit system. The Generate sun acceptance angle from measurements button is available here too.

---

How the tilted-plane model works

The glass faces down-slope and is tilted back by the roof pitch. The engine builds the outward-facing normal of that tilted plane and tests the sun against it:

• Illumination — direct sun is only considered when it strikes the outer face of the glass (the angle of incidence is on the lit side). A flat skylight (0°) is lit from any direction once the sun clears the horizon; a steep roof behaves more like a vertical window.
• Shade projection — the patch of floor the sun reaches is projected down the slope of the glass rather than straight down a wall, so the coverage percentage reflects where light actually lands in the room.

At a pitch of 90° the model reduces exactly to the vertical-blind engine, so a roof window set vertical and a real vertical blind compute the same positions.

---

Ridge-occlusion gate

When Roof Height Above Window is greater than 0, the roof above the window can hide the sun once it swings around to the ridge side and drops low in the sky. The gate models the roof above as subtending an elevation angle from the window and suppresses tracking when the sun falls behind it. This only engages on the ridge side of the window and at low sun; with the setting at 0 the gate is off entirely.

---

Field of view and the predicted sun window

The sun acceptance angle gate is tilt-aware: the effective sun angle the gate tests breathes with the sun's elevation rather than using a flat horizontal azimuth, so a pitched roof enters and leaves its tracking window at the geometrically correct times (fixed in #212 / #728). The per-day predicted sun window that the companion Lovelace card draws uses the same tilt-aware angle (#729 / #731), so the forecast strip lines up with when the cover actually starts and stops tracking instead of lagging by an hour or two.

Don't expect a roof window and a vertical cover to share timing. Because the gate is measured in the tilted plane, a roof window's Sun Infront time will not match a vertical cover (an awning or blind) aimed at the same azimuth, even when both carry the same sun acceptance angles. The shallower the pitch, the earlier the roof window opens: at a near-flat 12° pitch the sun lights the glass while it is still well off to the side, so the roof window can enter its window a few hours before a vertical pane at the same orientation would. That gap is expected geometry, not a fault. Each hour of difference is 15° of azimuth, so a clean 2–3 hour offset from a vertical cover usually just reflects the pitch. If a shallow roof window seems to start tracking surprisingly early, confirm its Roof Pitch matches the real slope of the glass before treating the difference as a bug.

---

What it supports

Capability	Roof window
Position (open/close) tracking	✅
Generate sun acceptance angle from measurements	✅
Return to default when disabled	✅
Slat tilt	❌ — position-only
Glare zones	❌ — not available for roof windows

Roof windows prefer a cover that advertises set_cover_position; if none of the bound covers support it the integration falls back to plain open/close and warns during setup.

---

Tips

• Pitch is the most important number. A few degrees off noticeably shifts when tracking starts and stops. Measure the actual roof slope rather than guessing.
• Migrating from the old workaround? Before this cover type existed, people approximated a roof window with a vertical blind plus a low maximum-elevation limit. The roof pitch is the complement of that workaround — a 35° roof corresponds to roughly a 55° max-elevation cap. Switch to the roof type and set the real pitch; you can remove the elevation hack.
• Flat skylight? Set the pitch to 0. The window is then treated as lit whenever the sun is up, with no azimuth dependence.

---

Related

• Cover Types — the full cover-type comparison
• Sun Tracking — sun acceptance angle and elevation limits
• Position — coverage limits and sunset behavior
• Diagnostic Sensors — the solar_calculation trace exposes the roof geometry intermediates