From 3f1fd2a25137fb97bfffa7d64cabc2fdd4cfccad Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 9 May 2019 16:43:41 +0200 Subject: [PATCH 1/9] Update trigger.markdown --- source/_docs/automation/trigger.markdown | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index b892651b895..bd42db25035 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -130,9 +130,10 @@ automation: ### {% linkable_title Sun trigger %} -Triggers when the sun is setting or rising. An optional time offset can be given to have it trigger a set time before or after the sun event (i.e. 45 minutes before sunset, when dusk is setting in). +#### Sunset / Sunrise trigger +Triggers when the sun is setting or rising, i.e. when the sun elevation reaches 0°. -Sunrise as a trigger may need special attention as explained in time triggers below. This is due to the date changing at midnight and sunrise is at an earlier time on the following day. +An optional time offset can be given to have it trigger a set time before or after the sun event (e.g. 45 minutes before sunset). Since the duration of twilight is different throughout the year, it is recommended to use sun elevation triggers instead of `sunset` or `sunrise` with a time offset to trigger automations at the start of dusk or dawn. ```yaml automation: @@ -140,11 +141,12 @@ automation: platform: sun # Possible values: sunset, sunrise event: sunset - # Optional time offset. This example is 45 minutes. + # Optional time offset. This example will trigger 45 minutes before sunrise. offset: '-00:45:00' ``` -Sometimes you may want more granular control over an automation based on the elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the "sunset" event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most things, a general number like -4 degrees is suitable and is used in this example: +#### Sun elevation trigger +Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the "sunset" event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most things intended to trigger during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example: {% raw %} ```yaml @@ -162,11 +164,15 @@ automation: ``` {% endraw %} -If you want to get more precise, start with the US Naval Observatory [tool](http://aa.usno.navy.mil/data/docs/AltAz.php) that will help you estimate what the solar angle will be at any specific time. Then from this, you can select from the defined twilight numbers. Although the actual amount of light depends on weather, topography and land cover, they are defined as: +If you want to get more precise, start with the US Naval Observatory [tool](http://aa.usno.navy.mil/data/docs/AltAz.php) which will help you estimate what the solar elevation will be at any specific time. Then from this, you can select from the defined twilight numbers. -- Civil twilight: Solar angle > -6° -- Nautical twilight: Solar angle > -12° -- Astronomical twilight: Solar angle > -18° +Although the actual amount of light depends on weather, topography and land cover, they are defined as: + +- Civil twilight: 0° > Solar angle > -6° + + This is what is meant by twilight for the average person: Under clear weather conditions, civil twilight approximates the limit at which solar illumination suffices for the human eye to clearly distinguish terrestrial objects. Enough illumination renders artificial sources unnecessary for most outdoor activities. +- Nautical twilight: 6° > Solar angle > -12° +- Astronomical twilight: 12° > Solar angle > -18° A very thorough explanation of this is available in the Wikipedia article about the [Twilight](https://en.wikipedia.org/wiki/Twilight). From ab4e93af8b0322a142412642302c1da137600e47 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 9 May 2019 17:17:22 +0200 Subject: [PATCH 2/9] Update conditions.markdown --- source/_docs/scripts/conditions.markdown | 44 +++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index ed261f6c874..c34a5b9ba62 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -119,11 +119,53 @@ condition: ``` ### {% linkable_title Sun condition %} +#### Sun state condition +The sun state can be used to test if the sun has set or risen. -The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger]. +```yaml +condition: + condition: state # 'day' condition: from sunrise until sunset + entity_id: sun.sun + state: 'above_horizon' +``` +```yaml +condition: + condition: state # from sunset until sunrise + entity_id: sun.sun + state: 'below_horizon' +``` + +#### Sun elevation condition +The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night etc. when a trigger occurs. +For an in depth explanation of sun elevation see [sun trigger][sun_trigger]. + +```yaml +condition: + condition: and # 'twilight' condition: dusk and dawn, in typical locations + conditions: + - condition: template + value_template: '{{ states.sun.sun.attributes.elevation < 0 }}' + - condition: template + value_template: '{{ states.sun.sun.attributes.elevation > -6 }}' +``` + +```yaml +condition: + condition: template # 'night' condition: from dusk to dawn, in typical locations + value_template: '{{ states.sun.sun.attributes.elevation < -6 }}' +``` + +#### Sunset/sunrise condition +The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger]. [sun_trigger]: /docs/automation/trigger/#sun-trigger +

+The sunset/sunrise conditions do not work in locations inside the polar circles, and also not in locations with highly skewed local time zone. + +It is advised to use conditions evaluating the solar elevation instead of the before/after sunset/sunrise conditions. +

+ ```yaml condition: condition: sun From 3c2026d68362600219dff15cf1b15c09c082aba4 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 9 May 2019 19:03:32 +0200 Subject: [PATCH 3/9] Update conditions.markdown --- source/_docs/scripts/conditions.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index c34a5b9ba62..db552067b5d 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -145,15 +145,15 @@ condition: condition: and # 'twilight' condition: dusk and dawn, in typical locations conditions: - condition: template - value_template: '{{ states.sun.sun.attributes.elevation < 0 }}' + value_template: {% raw %}'{{ states.sun.sun.attributes.elevation < 0 }}'{% endraw %} - condition: template - value_template: '{{ states.sun.sun.attributes.elevation > -6 }}' + value_template: {% raw %}'{{ states.sun.sun.attributes.elevation > -6 }}'{% endraw %} ``` ```yaml condition: condition: template # 'night' condition: from dusk to dawn, in typical locations - value_template: '{{ states.sun.sun.attributes.elevation < -6 }}' + value_template: {% raw %}'{{ states.sun.sun.attributes.elevation < -6 }}'{% endraw %} ``` #### Sunset/sunrise condition From 4ae0644122c4bca89670e4daace4d0c6c2d6ba5f Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 10 May 2019 15:10:13 +0200 Subject: [PATCH 4/9] Update trigger.markdown --- source/_docs/automation/trigger.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index bd42db25035..7fa85f880d7 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -130,7 +130,7 @@ automation: ### {% linkable_title Sun trigger %} -#### Sunset / Sunrise trigger +#### {% linkable_title Sunset / Sunrise trigger %} Triggers when the sun is setting or rising, i.e. when the sun elevation reaches 0°. An optional time offset can be given to have it trigger a set time before or after the sun event (e.g. 45 minutes before sunset). Since the duration of twilight is different throughout the year, it is recommended to use sun elevation triggers instead of `sunset` or `sunrise` with a time offset to trigger automations at the start of dusk or dawn. @@ -145,7 +145,7 @@ automation: offset: '-00:45:00' ``` -#### Sun elevation trigger +#### {% linkable_title Sun elevation trigger %} Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the "sunset" event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most things intended to trigger during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example: {% raw %} From 147513b7c7c947ddb543af01dc4821fedcb48129 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 10 May 2019 15:13:02 +0200 Subject: [PATCH 5/9] Update conditions.markdown --- source/_docs/scripts/conditions.markdown | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index db552067b5d..5f9848af2de 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -119,7 +119,7 @@ condition: ``` ### {% linkable_title Sun condition %} -#### Sun state condition +#### {% linkable_title Sun state condition %} The sun state can be used to test if the sun has set or risen. ```yaml @@ -136,9 +136,10 @@ condition: state: 'below_horizon' ``` -#### Sun elevation condition +#### {% linkable_title Sun elevation condition %} The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night etc. when a trigger occurs. -For an in depth explanation of sun elevation see [sun trigger][sun_trigger]. +For an in depth explanation of sun elevation see [sun elevation trigger][sun_elevation_trigger]. +[sun_elevation_trigger]: /docs/automation/trigger/#sun-elevation-trigger ```yaml condition: @@ -156,7 +157,7 @@ condition: value_template: {% raw %}'{{ states.sun.sun.attributes.elevation < -6 }}'{% endraw %} ``` -#### Sunset/sunrise condition +#### {% linkable_title Sunset/sunrise condition %} The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger]. [sun_trigger]: /docs/automation/trigger/#sun-trigger From 60a7ead71a5a05807601dd15e00b93b2ba132224 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 10 May 2019 17:21:23 +0200 Subject: [PATCH 6/9] Fix links. --- source/_docs/scripts/conditions.markdown | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index 5f9848af2de..f44b97ebebf 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -139,6 +139,7 @@ condition: #### {% linkable_title Sun elevation condition %} The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night etc. when a trigger occurs. For an in depth explanation of sun elevation see [sun elevation trigger][sun_elevation_trigger]. + [sun_elevation_trigger]: /docs/automation/trigger/#sun-elevation-trigger ```yaml @@ -159,6 +160,7 @@ condition: #### {% linkable_title Sunset/sunrise condition %} The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger]. + [sun_trigger]: /docs/automation/trigger/#sun-trigger

From 29f5b7f94775345512aefd511658a079e0fc8aa7 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 10 May 2019 17:36:49 +0200 Subject: [PATCH 7/9] Update trigger.markdown --- source/_docs/automation/trigger.markdown | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index 7fa85f880d7..b75ee3db9c5 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -133,7 +133,13 @@ automation: #### {% linkable_title Sunset / Sunrise trigger %} Triggers when the sun is setting or rising, i.e. when the sun elevation reaches 0°. -An optional time offset can be given to have it trigger a set time before or after the sun event (e.g. 45 minutes before sunset). Since the duration of twilight is different throughout the year, it is recommended to use sun elevation triggers instead of `sunset` or `sunrise` with a time offset to trigger automations at the start of dusk or dawn. +An optional time offset can be given to have it trigger a set time before or after the sun event (e.g. 45 minutes before sunset). + +

+Since the duration of twilight is different throughout the year, it is recommended to use [sun elevation triggers][sun_elevation_trigger] instead of `sunset` or `sunrise` with a time offset to trigger automations during dusk or dawn. +

+ +[sun_elevation_trigger]: /docs/automation/trigger/#sun-elevation-trigger ```yaml automation: From aec551668fe6ec52c136d0d8562e6c490e45cb91 Mon Sep 17 00:00:00 2001 From: Klaas Schoute Date: Thu, 30 May 2019 00:09:16 +0200 Subject: [PATCH 8/9] :pencil2: Tweak --- source/_docs/automation/trigger.markdown | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index b75ee3db9c5..0fc3d9991d6 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -131,6 +131,7 @@ automation: ### {% linkable_title Sun trigger %} #### {% linkable_title Sunset / Sunrise trigger %} + Triggers when the sun is setting or rising, i.e. when the sun elevation reaches 0°. An optional time offset can be given to have it trigger a set time before or after the sun event (e.g. 45 minutes before sunset). @@ -152,6 +153,7 @@ automation: ``` #### {% linkable_title Sun elevation trigger %} + Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the "sunset" event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most things intended to trigger during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example: {% raw %} From a3b76fb3ed47f29217b46942bb8ef74ebe71611d Mon Sep 17 00:00:00 2001 From: Klaas Schoute Date: Thu, 30 May 2019 00:10:30 +0200 Subject: [PATCH 9/9] :pencil2: Tweak --- source/_docs/scripts/conditions.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index f44b97ebebf..26968f97601 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -119,7 +119,9 @@ condition: ``` ### {% linkable_title Sun condition %} + #### {% linkable_title Sun state condition %} + The sun state can be used to test if the sun has set or risen. ```yaml @@ -137,6 +139,7 @@ condition: ``` #### {% linkable_title Sun elevation condition %} + The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night etc. when a trigger occurs. For an in depth explanation of sun elevation see [sun elevation trigger][sun_elevation_trigger]. @@ -159,6 +162,7 @@ condition: ``` #### {% linkable_title Sunset/sunrise condition %} + The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger]. [sun_trigger]: /docs/automation/trigger/#sun-trigger