📖 CCA Handbook › Blueprint section: Sun Shading / Sun Protection
Settings if the feature ‘🥵 - Sun Protection / Shading — Partially close when sun shines on window’ has been activated above.
All these settings are optional / The attributes of default sun sensor (configured above) is used.
Phase 1 — Pending (trigger): When ANY configured shading trigger fires (sun azimuth, elevation, brightness, temperature, forecast), the automation arms a “pending” timer. This sets the status to t_shading_start_pending and starts the waiting time.
Phase 2 — Execution (after waiting time): After the waiting time expires, the automation re-evaluates ALL configured conditions. Only if they are still valid at this point, the cover actually moves to the shading position.
Common reasons why shading stays stuck at “pending”:
"pnd":"beg" and verify that "ts.due" is a valid future timestamp.Debugging tip: Enable the Logbook option and check the automation trace after the waiting time expires. Look for the t_shading_start_execution trigger — if it doesn’t appear, the template trigger may not be evaluating correctly. If it appears but the trace shows “conditions not met”, check which specific condition fails using Developer Tools → Template.
On this page:
🧩 Input:
shading_conditions_start_and· Default:['cond_azimuth', 'cond_elevation', 'cond_brightness', 'cond_temp1', 'cond_temp2', 'cond_forecast_temp', 'cond_forecast_weather']
Conditions that MUST ALL be met to START shading
Required (AND) conditions for START:
ALL selected conditions must be valid
If ANY fails, shading will NOT start
Use for critical conditions
Example - Conservative approach:
Select ALL: Azimuth, Elevation, Brightness, Temperature
Result: Shading only when everything is perfect
Example - Flexible approach:
Select: Azimuth, Elevation (sun position)
Leave others for OR list
Result: Sun must be in range, plus other criteria
Important: Conditions without a configured sensor are automatically satisfied (skipped). You can safely leave all conditions selected — only those with a matching sensor configured below will actually be evaluated. However, if a sensor IS configured but returns “unavailable” or “unknown”, the condition will FAIL — sun shading then does not start, but the rest of the automation (opening, closing, ventilation) keeps working normally. Once the sensor reports again, the sun shading conditions are re-evaluated, so a shading that was missed while the sensor was down is not lost.
🧩 Input:
shading_conditions_start_or
Conditions where AT LEAST ONE must be met to START shading
Optional (OR) conditions for START:
Example - Redundant temperature sensors:
Combined logic:
🧩 Input:
shading_conditions_end_and
Conditions that MUST ALL become invalid to END shading
Required (AND) conditions for END:
Example - Quick response:
Example - Stable shading:
Tip: Usually END should be MORE permissive than START
🧩 Input:
shading_conditions_end_or· Default:['cond_azimuth', 'cond_elevation', 'cond_brightness', 'cond_temp1', 'cond_temp2', 'cond_forecast_temp', 'cond_forecast_weather']
Conditions where AT LEAST ONE must become invalid to END shading
Optional (OR) conditions for END:
Recommended: Quick sun position response
Combining AND + OR groups (both combined with OR):
Keep shading longer (require multiple conditions):
Combined logic:
🧩 Input:
shading_custom_sensor· Default: (empty)
Optional binary sensor (or toggle helper) evaluated as an additional shading condition.
Override an unreliable forecast (hybrid OR setup):
input_boolean helper (“shade anyway”)Your own periodic condition logic:
on later in the day, shading starts; when it flips to off, shading endsDifference to the “Additional Condition When Activating Sun Shading”: the additional condition (in the Conditions section) is a pure gate — it is only checked when something else triggers, and it can only block, never trigger. The Custom Condition Sensor is a full condition: it participates in the AND/OR logic and fires the shading evaluation on its own.
Difference to the “Force Sun Shading” switch: the force function bypasses ALL conditions. The Custom Condition Sensor is combined with the other configured conditions — sun position, brightness etc. still apply.
Note: If the sensor reports “unavailable” or “unknown”, the condition behaves like the other conditions: the START condition fails (shading does not start because of it) and the END condition does not fire (shading does not end because of it). The rest of the automation keeps working normally.
🧩 Input:
shading_azimuth_start· Default:95
What is the minimum azimuth at which the sun hits the window? (Shading will start)
🧩 Input:
shading_azimuth_end· Default:265
What is the maximum azimuth at which the sun hits the window? (Shading will stop)
🧩 Input:
shading_elevation_min· Default:25
Starting from which elevation of the sun should the window be shaded? (Here it makes sense to consider surrounding buildings, trees, etc.).
🧩 Input:
shading_elevation_max· Default:90
What is the maximal elevation for elevation? (In most cases, 90 degrees is probably the most reasonable value. However, this can also be different due to surrounding buildings, etc.).
🧩 Input:
shading_brightness_sensor
This sensor is only used for shading.
🧩 Input:
shading_sun_brightness_start· Default:35000
The minimum brightness value from which shading should start. (Must be above the value of brightness end!)
🧩 Input:
shading_sun_brightness_end· Default:25000
The brightness value from which shading is no longer necessary. (Must be below the value of brightness start!).
🧩 Input:
shading_sun_brightness_hysteresis· Default:0
Hysteresis value to prevent flickering. The brightness must exceed (start + hysteresis) to activate shading and fall below (end - hysteresis) to deactivate it. See: FAQ: How does hysteresis work?
🧩 Input:
shading_temperatur_sensor1
This is the first temperature sensor used for sun shading logic.
For example, you can use the current indoor temperature as a condition to trigger shading.
🧩 Input:
shading_min_temperatur1· Default:18
Minimum temperature for sensor 1 above which shading should occur.
🧩 Input:
shading_temperature_hysteresis1· Default:0.2
Shading will end only when temperature drops below (minimum - hysteresis value) to prevent frequent open/close cycles. See: FAQ: How does hysteresis work?
🧩 Input:
shading_temperatur_sensor2
This is an optional secondary temperature sensor, typically used for outdoor temperature.
It can serve as an additional condition for sun shading logic.
This sensor also plays a role in the calculation of the Sun Shading - Forecast Temperature Value. Please refer to that section for more details.
🧩 Input:
shading_min_temperatur2· Default:18
Minimum temperature for sensor 2 above which shading should occur.
🧩 Input:
shading_temperature_hysteresis2· Default:0.2
Shading will end only when temperature drops below (minimum - hysteresis value) to prevent frequent open/close cycles. See: FAQ: How does hysteresis work?
🧩 Input:
shading_forecast_sensor
Weather entity for forecast data (temperature & conditions). This is the primary and recommended method for forecast-based shading.
Select a weather entity (e.g., weather.home, weather.openweathermap).
The system will:
Query forecast temperature for comparison
Check weather conditions if configured
Use daily or hourly forecast based on your selection below
Most users should use this field.
The idea is that it can happen, especially in spring, that the value of the Forecast Temperature Value is exceeded by strong solar radiation and the shading would be started. However, in spring you may not want shading, but the solar radiation as a welcome, free heating is desired. So you can define via the forecast that shading is only started at an expected daily maximum temperature.
🧩 Input:
shading_forecast_type· Default:daily
Please select whether you want to use the daily or hourly weather forecast. This only works if a weather entity has been configured above.
The first entry in the forecast array will always be used — this corresponds to the current day or current hour.
Note: Your weather entity must support weather.get_forecasts, which was introduced in Home Assistant 2023.9.
Alternatively, you can choose not to use the forecast service at all. In that case, the current weather attributes from the weather entity will be used instead.
Recommendation: Using the daily forecast is generally preferred for sun shading purposes.
Ignored when using temperature sensor below.
🧩 Input:
shading_forecast_temp_sensor
Alternative method: Use a sensor that directly provides forecasted max temperature.
Use this if:
Your weather integration provides dedicated forecast sensors
You want better performance (no forecast service calls)
You have custom template sensors for forecast temperature
Examples:
sensor.pirateweather_daytime_high_apparent_temperature_0d
sensor.met_no_forecast_temperature_max
sensor.openweathermap_forecast_temperature
Priority: If configured, this takes priority over weather entity above.
Limitation: Weather condition checks are not available with sensors.
🧩 Input:
shading_forecast_temp
This setting defines the minimum temperature threshold based on the forecast at which shading should be activated. If the forecasted temperature exceeds this value, the shading system will respond accordingly.
To enhance reliability, the system can compare this threshold against two sources:
The forecasted temperature (this comparison is always active)
Temperature Sensor 2 (e.g. outdoor) (can be enabled via the checkbox in the next configuration field)
Troubleshooting: If this condition is in your AND list, the forecast source (weather entity or temperature sensor above) MUST provide a valid numeric temperature value. Check Developer Tools → States that your weather entity or sensor shows a numeric temperature, not “unavailable” or “unknown”. If the forecast returns no data, this condition will fail and block shading execution.
🧩 Input:
shading_forecast_temp_hysteresis· Default:0
Prevents frequent on/off cycles near threshold.
See: FAQ: How does hysteresis work?
🧩 Input:
shading_weather_conditions
Check the following weather conditions when activating the shading. Be cautious when making your selection, as weather forecasts may not always be accurate and could lead to incorrect shading decisions. And as mentioned above, weather conditions can only be checked if a weather entity has been configured under ‘Forecast Weather Sensor’.
Only works with weather entity, not with temperature sensor.
Be cautious: weather forecasts may not always be accurate.
🧩 Input:
shading_config
These options allow you to fine-tune how the system handles temperature-based shading. <p>Click on the titles to get further help.</p>
Enables shading based solely on temperature — independently of all other conditions like brightness, sun position (azimuth and elevation), or time of day.
If any value exceeds the independent threshold, shading is activated — even if all other shading conditions are false.
⚠️ This bypasses the sun position. With this option enabled, shading can start while the sun azimuth is outside your configured range and the sun elevation is below your threshold — i.e. even when the sun is not on this facade at all. The bypass is not limited to the morning: it applies every time a shading-start trigger fires throughout the day, as long as the temperature stays above the threshold. If you want shading to keep respecting the sun position, leave this option unchecked and rely on the normal AND/OR conditions (which include azimuth and elevation).
Why this exists: it lets the system decide early in the morning — from the forecast alone — that the day will be hot, and move the blinds straight into the shading position instead of first opening them fully, before the sun even reaches the facade.
Additionally, one hour before the earliest possible opening time, the system retrieves the latest weather forecast.
This allows it to compare the updated forecasted temperature with the configured threshold and make an early shading decision based on the most current data.
Note: The independent path uses its own “Independent Temperature Threshold”, which is separate from “Forecast Temperature Value” used in the normal AND/OR conditions. Set the independent threshold lower to allow early shading on hot days without loosening the normal forecast gate.
This activates an extended comparison for the independent shading path. The shading condition will be true if one of the following conditions is met:
This mechanism improves the responsiveness and reliability of the shading system by using real-time sensor input as an optional condition, especially when forecast data is uncertain. Note: This function has nothing to do with normal temperature comparison, but is used exclusively in the context of the forecast function.
🧩 Input:
shading_independent_temp· Default:25
Temperature threshold used exclusively by the “Independent Shading via Temperature Comparison” mode. Shading is activated independently of all other conditions (brightness, sun azimuth and elevation, etc.) when either the forecasted temperature or (if enabled) “Temperature Sensor 2” exceeds this value.
Set this lower than “Forecast Temperature Value” to allow the independent path to trigger on warmer-than-average days without tightening the normal forecast gate.
🧩 Input:
shading_waitingtime_start· Default:300
Waiting time between the initial shading trigger and the actual cover movement. After this time expires, all configured start conditions (AND + OR) are re-checked. The cover only moves if conditions are still valid at execution time. This waiting time is also used for the periodic condition checks within the retry loop.
If shading stays at “pending” and never executes: The conditions were no longer met after the waiting time expired. Check the automation trace for t_shading_start_execution.
🧩 Input:
shading_start_max_duration· Default:7200
Maximum time to keep retrying shading start conditions after initial trigger. The Start Waiting Time is used for the periodic condition checks during this retry loop. If conditions remain unstable for longer than this timeout, the retry loop is stopped. Shading will not start and waits for a new shading start trigger.
Use case: Prevents automation from being stuck in “waiting for stable conditions” when weather is highly unstable (rapidly changing clouds).
0 = disabled (no periodic retry, stops immediately - old “trigger_reset” behavior) Recommended: 3600-7200 seconds (1-2 hours)
🧩 Input:
shading_waitingtime_end· Default:300
To avoid excessive load on the motor, a waiting time can be defined here before the shading is ended. Shading ends if one of the conditions is not fulfilled for the entire waiting time. This waiting time is also used for the periodic condition checks within the retry loop.
🧩 Input:
shading_end_max_duration· Default:7200
Maximum time to keep retrying shading end conditions after initial trigger. The End Waiting Time is used for the periodic condition checks during this retry loop. If conditions remain unstable for longer than this timeout, the retry loop is stopped. Shading remains active and waits for a new shading end trigger.
Use case: Prevents automation from being stuck in “waiting for stable conditions” when weather is highly unstable (rapidly changing clouds).
0 = disabled (no periodic retry, behaves like old version) Recommended: 3600-7200 seconds (1-2 hours)
🧩 Input:
shading_end_immediate_by_sun_position· Default:False
Speeds up the END of shading: once the sun leaves the azimuth or elevation range, shading ends after only a few seconds instead of waiting for the configured end waiting time.
Important: This option only controls the timing of the end — not which conditions actually end the shading. For it to have any effect, “Sun Azimuth” and/or “Sun Elevation” must be part of your END conditions. Put them in the OR group if a single axis leaving its range should already end the shading. If they are in the AND group, shading ends only once all selected AND conditions are out of range at the same time (e.g. azimuth AND elevation together) — a single axis leaving its range is then not enough.
If disabled, the configured end waiting time is always used.
⬅️ Handbook index · Previous: 🚪 Window Contacts & Ventilation · Next: 🪟 Tilt Positions (Venetian Blinds)