From a317a8dc700edf7f72492edc1b035330f06ad108 Mon Sep 17 00:00:00 2001 From: Robert Meijers Date: Tue, 26 Oct 2021 15:52:54 +0200 Subject: [PATCH] Add documentation for supplying offset to time trigger (#19536) --- source/_docs/automation/trigger.markdown | 25 ++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index ebee59a7a14..c59d0395e8e 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -651,6 +651,31 @@ automation: - "18:30:00" ``` +### Specifying an offset + +When the time is provided using an Input Datetime or a sensor of the timestamp device class an offset can be provided. This offset will be added to (or subtracted from, when negative) the Input Datetime or sensor value. + +For example, this trigger fires 5 minutes before the phone alarm goes off. + +```yaml +automation: + - trigger: + - platform: time + at: + entity_id: sensor.phone_next_alarm + offset: -00:05:00 + action: + - service: light.turn_on + target: + entity_id: light.bedroom +``` + +
+ +When using a positive offset the trigger might never fire. This due the Input Datetime or sensor changing before the offset is reached. For example when using a phone alarm as trigger the sensor value will change to the new alarm time when the alarm goes off which means this trigger will change to the new time as well. + +
+ ## Time pattern trigger With the time pattern trigger, you can match if the hour, minute or second of the current time matches a specific value. You can prefix the value with a `/` to match whenever the value is divisible by that number. You can specify `*` to match any value (when using the web interface this is required, the fields cannot be left empty).