From e83d466a632eef2c08dce03adf59137805d3ac9a Mon Sep 17 00:00:00 2001 From: akasma74 Date: Mon, 2 Mar 2020 14:20:59 +0000 Subject: [PATCH] add note about sun.before and after (#12236) * add note about sun.before and after Based on this topic - https://community.home-assistant.io/t/automation-with-sun-condition-doesnt-works/175394/3 It's not obvious how to combine these keys. And it looks like the examples should show it as well. Comments moved out of the code. * :pencil: Tweaks * :pencil2: Tweak Co-authored-by: Franck Nijhof --- source/_docs/scripts/conditions.markdown | 26 ++++++++++++++---------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index deace93861bc..561b59a4eb1e 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -157,7 +157,9 @@ condition: #### 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]. +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]. When both keys are used, the result is a logical `and` of separate conditions. + +Note that if only `before` key is used, the condition will be `true` _from midnight_ until sunrise/sunset. If only `after` key is used, the condition will be `true` from sunset/sunrise _until midnight_. Therefore, to cover time between sunset and sunrise one need to use `after: sunset` and `before: sunrise` as 2 separate conditions and combine them using `or`. [sun_trigger]: /docs/automation/trigger/#sun-trigger @@ -171,28 +173,30 @@ In those cases it is advised to use conditions evaluating the solar elevation in condition: condition: sun after: sunset - # Optional offset value - in this case it must from -1 hours relative to sunset, or after after_offset: "-01:00:00" ``` +This is 'when light' - equivalent to a state condition on `sun.sun` of `above_horizon`. + ```yaml condition: - condition: or # 'when dark' condition: either after sunset or before sunrise - equivalent to a state condition on `sun.sun` of `below_horizon` - conditions: - - condition: sun - after: sunset - - condition: sun - before: sunrise + - condition: sun + after: sunrise + before: sunset ``` +This is 'when dark' - equivalent to a state condition on `sun.sun` of `below_horizon`. + +We cannot use both keys in this case as it will always be `false`. + ```yaml condition: - condition: and # 'when light' condition: before sunset and after sunrise - equivalent to a state condition on `sun.sun` of `above_horizon` + condition: or conditions: - condition: sun - before: sunset + after: sunset - condition: sun - after: sunrise + before: sunrise ``` A visual timeline is provided below showing an example of when these conditions are true. In this chart, sunrise is at 6:00, and sunset is at 18:00 (6:00 PM). The green areas of the chart indicate when the specified conditions are true.