Time¶

The time component allows you to set up real time clock time sources for ESPHome. You can then get the current time in lambdas. Currently only sntp (internet-based) and homeassistant time sources are supported.

Home Assistant Time Source¶

The preferred way to get time in ESPHome is using Home Assistant. With the homeassistant time platform, the native API connection to Home Assistant will be used to periodically synchronize the current time.

# Example configuration entry
time:
  - platform: homeassistant
    id: homeassistant_time

Configuration variables:

id (Optional, ID): Specify the ID of the time for use in lambdas.
timezone (Optional, string): Manually tell ESPHome what timezone to use with this format (warning: the format is quite complicated) or the simpler TZ database name in the form <Region>/<City>. ESPHome tries to automatically infer the timezone string based on the timezone 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.

SNTP Configuration¶

# Example configuration entry
time:
  - platform: sntp
    id: sntp_time

Configuration variables:

id (Optional, ID): Specify the ID of the time for use in lambdas.
timezone (Optional, string): Manually tell ESPHome what timezone to use with this format (warning: the format is quite complicated) or the simpler TZ database name in the form <Region>/<City>. ESPHome tries to automatically infer the timezone string based on the timezone of the computer that is running ESPHome, but this might not always be accurate.
servers (Optional, list of strings): Choose up to 3 NTP servers that are used for the clock source. Defaults to 0.pool.ntp.org, 1.pool.ntp.org and 2.pool.ntp.org
on_time (Optional, Automation): Automation to run at specific intervals using a cron-like syntax. See on_time.

Use In Lambdas¶

To get the current local time with the timezone 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

Name	Meaning	Range (inclusive)	Example
`.second`	Seconds after the minute	[0-60] (generally [0-59], extra range is to accommodate leap seconds.)	42
`.minute`	Minutes after the hour	[0-59]	31
`.hour`	Hours since midnight	[0-23]	16
`.day_of_week`	Day of the week, sunday=1	[1-7]	7 (saturday)
`.day_of_month`	Day of the month	[1-31]	18
`.day_of_year`	Day of the year	[1-366]	231
`.month`	Month, january=1	[1-12]	8 (august)
`.year`	Year since 0 A.C.	[1970-∞[	2018
`.is_dst`	Is daylight savings time	false, true	true
`.time`	Unix epoch time (seconds since UTC Midnight January 1, 1970)	[-2147483648 - 2147483647] (negative values for time past January 19th 2038)	1534606002
`.is_valid()`	Basic check if the time is valid (i.e. not January 1st 1970)	false, true	true

Note

Before the ESP has connected to the internet and can get the current time the date will be January 1st 1970. So make sure to check if .is_valid() evaluates to true before triggering any action.

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.

Directive	Meaning	Example
`%a`	Abbreviated weekday name	Sat
`%A`	Full weekday name	Saturday
`%w`	Weekday as decimal number, where 0 is Sunday and 6 is Saturday	6
`%d`	Day of month as zero-padded decimal number	01, 02, …, 31
`%b`	Abbreviated month name	Aug
`%B`	Full month name	August
`%m`	Month as zero-padded decimal number	01, 02, …, 12
`%y`	Year without century as a zero-padded decimal number	00, 01, …, 99
`%Y`	Year with century as a decimal number	2018
`%H`	Hour (24-hour clock) as a zero-padded decimal number	00, 01, …, 23
`%I`	Hour (12-hour clock) as a zero-padded decimal number	00, 01, …, 12
`%p`	AM or PM designation	AM, PM
`%M`	Minute as a zero-padded decimal number	00, 01, …, 59
`%S`	Second as a zero-padded decimal number	00, 01, …, 59
`%j`	Day of year as a zero-padded decimal number	001, 002, …, 366
`%U`	Week number of year (Sunday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0.	00, 01, …, 53
`%W`	Week number of year (Monday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Monday are considered to be in week 0.	00, 01, …, 53
`%c`	Date and time representation	Sat Aug 18 16:31:42 2018
`%x`	Date representation	08/18/18
`%X`	Time representation	16:31:42
`%%`	A literal `%` character	%

`on_time`¶

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 expression like * /5 * * * *.

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: '* /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 hours). 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 years and some special characters like L, # are currently not supported.
See Automation.

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

```
seconds: 0
```
An integer like 0 or 30 will make the automation only trigger if the current second is exactly 0 or 30, respectively.
```
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.

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.

```
# 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.
```
# Every minute
seconds: 0
minutes: '*'
```
Lastly, the * operator matches every number. In the example above, * could for example be substituted with 0-59.

Warning

Please note the following automation would trigger for each second in the minutes 0,5,10,15 and not once per 5 minutes as the seconds variable is not set:

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

Table of Contents

Time¶

Home Assistant Time Source¶

SNTP Configuration¶

Use In Lambdas¶

strftime¶

`on_time`¶

See Also¶

Time¶

Home Assistant Time Source¶

SNTP Configuration¶

Use In Lambdas¶

strftime¶

on_time¶

See Also¶

`on_time`¶