Configuration Louvered Roof

Louvered Roof

A cover type for a bioclimatic pergola or louvered roof — rotating slats mounted in a horizontal or gently pitched roof plane, turning around a fixed horizontal axis. The integration optimizes the slat angle to cut off direct sun while keeping the roof as open as possible for diffuse light and ventilation, then drives that angle through set_cover_tilt_position.

Choose Louvered roof in the cover-type picker when you add or reconfigure an instance.

A louvered roof is a tilt-only cover type. It commands a slat tilt percentage exactly like a venetian tilt blind — same slat geometry, same tilt modes, same position calibration — but the sun geometry behind that angle is computed against a roof plane instead of a vertical facade.

---

Why not a venetian or a roof window?

The two halves of this problem already existed in the integration, but never combined:

• A venetian / tilt blind optimizes the slat cut-off angle, but assumes the slats hang in a vertical window. The profile angle is measured against a vertical facade and the "window azimuth" has no meaningful equivalent for a roof, so the computed angles come out physically wrong.
• A roof window gets the tilted-plane sun geometry right (roof_pitch, angle-of-incidence illumination), but it is a position-only cover — it models a shade sliding over pitched glass, with no slat-angle output.

The louvered-roof type is the cross-product: the venetian cut-off solver, driven by a profile angle taken against the roof plane and the slat-axis orientation.

---

Geometry options

The louvered roof reuses the venetian slat settings and adds one roof setting on top of the usual sun acceptance angles:

Setting	Range	Default	Meaning
Slat Depth	0.1–15 cm	3 cm	Depth of one lamella, front to back.
Slat Distance	0.1–15 cm	2 cm	Center-to-center spacing between slats.
Tilt Mode	Mode1 / Mode2	Mode2 (0–180°)	Mode1 = 0–90° travel, Mode2 = 0–180°. Match your drive's physical range.
Maximum Tilt	0–100	100	Upper clamp on the tilt percentage the integration will command.
Minimum Tilt	0–100	0	Lower clamp on the tilt percentage.
Roof Pitch	0–90°	0°	The slope of the roof plane, measured from horizontal. 0° is a flat pergola roof (slat angle driven purely by solar elevation, independent of sun direction). A pitched pergola sits a few degrees up; 90° reduces exactly to a vertical venetian blind.
Maximum Slat Angle	0–180°	0 (use tilt mode)	The physical travel of your drive, in degrees, when it is neither exactly 90° nor 180°. Leave at 0 to use the tilt mode's range (90° for Mode1, 180° for Mode2). Set it to your drive's real maximum — e.g. 160 for a pergola that rotates through the vertical turnover and 70° beyond — and the integration maps the computed geometric angle against that range and clamps anything above it, instead of relying on your controller's own percentage mapping.

The azimuth field is the slat-plane facing direction. The standard Azimuth on the sun-tracking screen is reused as the compass direction the slats "tilt toward" (perpendicular to the horizontal rotation axis). On a flat roof (pitch 0°) it has little effect because a flat roof is lit from every direction; on a pitched roof it orients the plane the way the roof window's azimuth does. The sun acceptance angle angles behave as usual and can restrict tracking to a slice of the sky.

The slat measurement diagram and calibration are identical to the Tilt page — measure one slat front-to-back for depth and center-to-center for spacing.

---

How the slat-angle model works

The cut-off geometry is a 2-D cross-section taken in the plane perpendicular to the rotation axis: given slats of depth d spaced s, find the tilt that just blocks a ray arriving at profile angle β. That solver is orientation-agnostic — only β changes between a vertical venetian and a roof plane. The louvered-roof type takes β against the roof plane (using the same slope trigonometry as the roof window) and feeds it into the shared cut-off solver.

Two limits anchor the model and are verified in the test suite:

• Flat roof (0°), sun due-azimuth → the cut-off is a pure solar-elevation function: |β| = 90° − elevation. Overhead midday sun closes the slats flat; low morning/evening sun opens them. This is the complement of the vertical case — the profile is measured against the horizontal plane, not a vertical facade.
• Vertical (90°) → the model reduces to the venetian/tilt engine bit-for-bit, so a louvered roof set vertical and a real venetian blind compute the same slat angle.

Illumination gate. Because a flat roof is lit from any azimuth once the sun clears the horizon, the vertical sun acceptance angle hemisphere test would be wrong. The louvered-roof type uses the same angle-of-incidence test as the roof window: direct sun is only considered when it strikes the working face of the roof plane. At pitch 0° that reduces to "the sun is above the horizon," independent of direction; on a pitched roof it behaves like the roof-window gate.

---

The sun acceptance angle is measured in the roof plane, not on a compass

The most common surprise with this cover type: on a flat or shallow-pitched roof, solar tracking goes active well before the sun's compass bearing enters the acceptance arc you configured. That is by design, not a bug.

Both the illumination gate and the acceptance-angle test are evaluated in the roof plane. The integration projects the sun into that plane first, then compares the projected angle against your left and right acceptance angles. As the sun drops toward the horizon that projection compresses toward zero, so the effective arc widens — the acceptance angle "breathes" with sun height instead of holding a fixed compass window.

A worked example. A pergola at azimuth 265° with a 90°/90° acceptance angle looks like it should track only while the sun sits between 175° and 355°. At roof pitch 0°, with the sun due east (90°) and 20° above the horizon, the projected angle works out to roughly 13° — comfortably inside ±90°, so tracking is active hours before the sun is anywhere near west. At pitch 0° the illumination gate reduces to "the sun is above the horizon" outright, because a flat roof genuinely has no front hemisphere to exclude.

This is the physically correct model. A flat pergola really is lit by an eastern sun, and the slats really do need to tilt for it. It only reads as wrong if you interpret the acceptance angle as a compass window, which is how it behaves on a vertical facade but not here.

If you want to restrict tracking anyway, three knobs work:

• Minimum elevation — usually the right one. The arc widens exactly when the sun is low, so an elevation floor cuts off the early-morning and late-evening tracking that most people are reacting to when they notice this.
• A blind spot wedge — blind spots on a tilted-plane cover are evaluated in the same roof-plane frame as the acceptance angle, so set the wedge against the projected angle in the diagnostic trace rather than against a raw compass bearing. Setting it from compass headings will not land where you expect.
• Roof pitch — if your roof genuinely is pitched, entering the real value tightens the arc. As pitch approaches 90° the behavior converges on a vertical blind's compass-like window.

---

Sun on either side of the axis

A flat roof is lit all day, and the sun crosses from one side of the slat rotation axis to the other as it moves across the sky. A vertical blind never has this problem — it only sees the sun on its front hemisphere — but a roof does, and the slats have to tilt toward whichever side the sun is on to block it.

The engine handles both sides. When the sun is on the facing side of the axis it realizes the cut-off angle as θ; once the sun crosses to the far side it realizes it as 180° − θ — the flipped slat face, past the horizontal (90°) turnover. This matters most in the evening: at a mid-latitude site in summer the sun can sit on the far side of the axis for hours of prime terrace time, and without the flip the slats would tilt the wrong way and let that sun straight through.

Your tilt mode and maximum slat angle decide how much of the far side the hardware can actually serve:

• Mode2 (0–180°) — the drive can rotate through the turnover, so it reaches the flipped face and blocks sun on both sides.
• Mode1 (0–90°) — the drive stops at horizontal and cannot reach the far branch, so it falls back to fully open on that side (it simply can't shade it).
• A drive with an in-between range (e.g. 0–160°) reaches most of the far side; set Maximum Slat Angle to its real travel so angles beyond it are clamped correctly.

At a roof pitch of 90° (a vertical installation) the far side is never lit — the angle-of-incidence gate excludes it — so the flip never triggers and the behavior is identical to a vertical venetian blind.

The diagnostic trace exposes which branch is active (louvered_far_side_branch) alongside the computed slat angle, so you can confirm the choice against your encoder feedback.

---

What it supports

Capability	Louvered roof
Slat tilt optimization	✅
Tilt modes (0–90° / 0–180°)	✅
Min / max tilt clamps + position calibration	✅
Return to default when disabled	✅
Roof pitch (horizontal → pitched)	✅
Position (open/close) tracking	❌ — tilt-only
Glare zones	❌

A louvered roof requires a cover that advertises set_cover_tilt_position; if none of the bound covers support it the integration warns during setup. The full decision pipeline — weather safety, manual override, motion, climate, custom positions, and defaults — applies unchanged, since the slat angle flows through the standard tilt axis.

---

Tips

• Start flat. For a standard bioclimatic pergola with a level roof, leave Roof Pitch at 0°. You only need to change it if the whole roof plane is tilted.
• Use Mode2 if your slats rotate past horizontal. Most pergola drives travel through the vertical turnover (Mode2, 0–180°) so they can shade the sun on both sides of the axis. A drive that only rotates a quarter turn is Mode1 (0–90°) and can only shade the facing side.
• Set Maximum Slat Angle for anything other than 90° or 180°. If your drive's real travel is, say, 0–160°, enter 160 rather than leaving it at 0. Otherwise the tilt percentage is scaled against the mode's 90°/180° and lands on the wrong physical angle. Leave it at 0 when the drive genuinely matches the mode.
• Slat depth and spacing matter most for the cut-off point. They set how far the slats must close before a ray is fully blocked — measure them rather than guessing.
• Encoder feedback helps verify. If your controller reports current_tilt_position reliably, compare the commanded slat angle in the diagnostic trace — including the louvered_far_side_branch flag — against the physical angle to confirm the geometry for your latitude, on both the morning and evening sides of the axis.

---

Related

• Cover Types — the full cover-type comparison
• Tilt — the shared slat geometry and tilt-mode calibration
• Roof / Skylight Window — the tilted-plane sun geometry this type reuses
• Sun Tracking — azimuth, sun acceptance angle, and elevation limits
• Diagnostic Sensors — the solar_calculation trace exposes the roof-plane and slat-angle intermediates