Time Component

The time component allows you to set up real time clock time sources for ESPHome. You can then get the current time in lambdas.

Base Time Configuration

All time configuration schemas inherit these options.

Configuration variables:

• id (Optional, ID): Specify the ID of the time for use in lambdas.
• timezone (Optional, string): Manually tell ESPHome what time zone to use with this format (warning: the format is quite complicated, see examples) or the simpler TZ database name in the form :code:<Region>/<City>. ESPHome tries to automatically infer the time zone string based on the time zone of the computer that is running ESPHome, but this might not always be accurate.
• on_time (Optional, Automation): Automation to run at specific intervals using a cron-like syntax. See on_time Trigger.
• on_time_sync (Optional, Automation): Automation to run when the time source could be (re-)synchronized.. See on_time_sync Trigger.

time.has_time Condition

This Condition checks if time has been set and is valid.

# Example configuration
on_...:
  if:
    condition:
      time.has_time:
    then:
      - logger.log: Time has been set and is valid!

# Example lambda
lambda: |-
    if (id(my_time).now().is_valid()) {
      //do something here
    }

on_time Trigger

This powerful automation can be used to run automations at specific intervals at specific times of day. The syntax is a subset of the crontab syntax.

There are two ways to specify time intervals: Either with using the seconds:, minutes:, … keys as seen below or using a cron alike expression like * /5 * * * *.

Be aware normal cron implementations does not know about seconds like this esphome implementation, therefore you got 6 fields (seconds,minutes,hours,dayofmonth,month,dayofweek).

Basically, the automation engine looks at your configured time schedule every second and evaluates if the automation should run.

time:
  - platform: sntp
    # ...
    on_time:
      # Every 5 minutes
      - seconds: 0
        minutes: /5
        then:
          - switch.toggle: my_switch

      # Every morning on weekdays
      - seconds: 0
        minutes: 30
        hours: 7
        days_of_week: MON-FRI
        then:
          - light.turn_on: my_light

      # Cron syntax, trigger every 5 minutes
      - cron: '00 /5 * * * *'
        then:
          - switch.toggle: my_switch

Configuration variables:

• seconds (Optional, string): Specify for which seconds of the minute the automation will trigger. Defaults to * (all seconds). Range is from 0 to 59.

• minutes (Optional, string): Specify for which minutes of the hour the automation will trigger. Defaults to * (all minutes). Range is from 0 to 59.

• hours (Optional, string): Specify for which hours of the day the automation will trigger. Defaults to * (all hours). Range is from 0 to 23.

• days_of_month (Optional, string): Specify for which days of the month the automation will trigger. Defaults to * (all days). Range is from 1 to 31.

• months (Optional, string): Specify for which months of the year to trigger. Defaults to * (all months). The month names JAN to DEC are automatically substituted. Range is from 1 (January) to 12 (December).

• days_of_week (Optional, string): Specify for which days of the week to trigger. Defaults to * (all days). The names SUN to SAT are automatically substituted. Range is from 1 (Sunday) to 7 (Saturday).

• cron (Optional, string): Alternatively, you can specify a whole cron expression like * /5 * * * *. Please note that years and some special characters like L, # are currently not supported. Also, the day of week field is interpreted like the days_of_week variable (range from 1 (Sunday) to 7 (Saturday)) and not like other cron implementations would do it (range from 0 (Sunday) to 7 (Sunday)).

• See Automation.

In the seconds:, minutes:, … fields you can use the following operators:

• .. code-block:: yaml

  seconds: 0
  

  An integer like 0 or 30 will make the automation only trigger if the current second is exactly 0 or 30, respectively.

• .. code-block:: yaml

  seconds: 0,30,45

  You can combine multiple expressions with the , operator. This operator makes it so that if either one of the expressions separated by a comma holds true, the automation will trigger. For example 0,30,45 will trigger if the current second is either 0 or 30 or 45.

• .. code-block:: yaml

  days_of_week: 2-6
  # same as
  days_of_week: MON-FRI
  # same as
  days_of_week: 2,3,4,5,6
  # same as
  days_of_week: MON,TUE,WED,THU,FRI
  

  The - (hyphen) operator can be used to create a range of values and is shorthand for listing all values with the , operator.

• .. code-block:: yaml

  # every 5 minutes
  seconds: 0
  minutes: /5
  
  # every timestamp where the minute is 5,15,25,...
  seconds: 0
  minutes: 5/10
  

  The / operator can be used to create a step value. For example /5 for minutes: makes an automation trigger only when the minute of the hour is 0, or 5, 10, 15, … The value in front of the / specifies the offset with which the step is applied.

• .. code-block:: yaml

  # Every minute
  seconds: 0
  minutes: '*'
  

  Lastly, the * operator matches every number. In the example above, * could for example be substituted with 0-59.

time:
  - platform: sntp
    # ...
    on_time:
      - minutes: /5
        then:
          - switch.toggle: my_switch

Note

on_time does not re-schedule events for times that are skipped or duplicated due to local Daylight Saving Time or other local time-adjustments like leap seconds. In regions with Daylight Saving Time, this means that events located between 01:00 - 02:00 may trigger twice, and events scheduled between 02:00 - 03:00 may be skipped once a year. This differs from cron behavior despite allowing the use of similar crontab syntax. Similarly, triggers on days of the month that do not exist (“every 31st of the month”) will be skipped when those dates do not exist.

on_time_sync Trigger

This automation is triggered after a time source successfully retrieves the current time. See the DS1307 configuration example for a scenario where a network time synchronization from a home assistant server trigger a write to an external hardware real time clock chip.

```yaml
on_time_sync:
  then:
    - logger.log: "Synchronized system clock"

```

Use In Lambdas

To get the current local time with the time zone applied in lambdas, just call the .now() method like so:

auto time = id(sntp_time).now();

Alternatively, you can use .utcnow() to get the current UTC time.

The returned object can either be used directly to get the current minute, hour, … as numbers or a string can be created based on a given format. If you want to get the current time attributes, you have these fields

strftime

The second way to use the time object is to directly transform it into a string like 2018-08-16 16:31. This is directly done using C’s strftime function which allows for a lot of flexibility.

// For example, in a display object
it.strftime(0, 0, id(font), "%Y-%m-%d %H:%M", id(time).now());

The strftime will parse the format string (here "%Y-%m-%d %H:%M") and match anything beginning with a percent sign % and a letter corresponding to one of the below formatting options and replace it with the current time representation of that format option.

See Also

• API Reference