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.

* 📝 Tweaks

* ✏️ Tweak

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
akasma74 2020-03-02 14:20:59 +00:00 committed by GitHub
parent 2ab1becef8
commit e83d466a63
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -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,13 +173,25 @@ 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`
- 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: or
conditions:
- condition: sun
after: sunset
@ -185,16 +199,6 @@ condition:
before: sunrise
```
```yaml
condition:
condition: and # 'when light' condition: before sunset and after sunrise - equivalent to a state condition on `sun.sun` of `above_horizon`
conditions:
- condition: sun
before: sunset
- condition: sun
after: 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.
<img src='/images/docs/scripts/sun-conditions.svg' alt='Graphic showing an example of sun conditions' />