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.
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) or the simpler TZ database name in the form <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.
on_...:
if:
condition:
time.has_time:
then:
- logger.log: Time has been set and is valid!
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 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 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 years and some special characters likeL
,#
are currently not supported.See Automation.
In the seconds:
, minutes:
, … fields you can use the following operators:
seconds: 0
An integer like
0
or30
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 example0,30,45
will trigger if the current second is either0
or30
or45
.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
forminutes:
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 with0-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
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.
on_time_sync: then: - logger.log: "Synchronized system clock"
Note
Components should trigger on_time_sync
when they update the system clock. However, not all real time components
behave exactly the same. Components could e.g. decide to trigger only when a significant time change has been
observed, others could trigger whenever their time sync mechanism runs - even if that didn’t effectively change
the system time. Some (such as SNTP) could even trigger when another real time component is responsible for the
change in time.
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:
All other from Base Time Configuration.
SNTP Time Source¶
# Example configuration entry
time:
- platform: sntp
id: sntp_time
Configuration variables:
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
and2.pool.ntp.org
All other options from Base Time Configuration.
Note
If your are using Manual IPs make sure to configure a DNS Server (dns1, dns2) or use only IP addresses for the NTP servers.
Warning
Due to limitations of the SNTP implementation, this component will trigger on_time_sync
only once when it detects that the
system clock has been set, even if the update was not done by the SNTP implementation!
This must be taken into consideration when SNTP is used together with other real time components, where another time source could
update the time before SNTP synchronizes.
GPS Time Source¶
You first need to set up the GPS component.
# Example configuration entry
time:
- platform: gps
id: gps_time
Configuration variables:
All other from Base Time Configuration.
DS1307 Time Source¶
You first need to set up the I2C component.
# Example configuration entry
time:
- platform: ds1307
id: ds1307_time
Configuration variables:
address (Optional, int): Manually specify the I²C address of the RTC. Defaults to
0x68
.All other options from Base Time Configuration.
ds1307.write_time
Action¶
This Action triggers a synchronization of the current system time to the RTC hardware.
Note
The DS1307 component will not write the RTC clock if not triggered explicitly by this action.
on_...:
- ds1307.write_time
# in case you need to specify the DS1307 id
- ds1307.write_time:
id: ds1307_time
ds1307.read_time
Action¶
This Action triggers a synchronization of the current system time from the RTC hardware.
Note
The DS1307 component will automatically read the RTC clock every 15 minutes by default and synchronize the
system clock when a valid timestamp was read from the RTC. (The update_interval
can be changed.)
This action can be used to trigger additional synchronizations.
on_...:
- ds1307.read_time
# in case you need to specify the DS1307 id
- ds1307.read_time:
id: ds1307_time
Configuration Example¶
In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an external time source might not always be available e.g. due to a limited network connection. In order to have a valid, reliable system time, the system should read the RTC once at start and then try to synchronize with an external reliable time source. When a synchronization to another time source was successful, the RTC can be resynchronized.
esphome:
on_boot:
then:
# read the RTC time once when the system boots
ds1307.read_time:
time:
- platform: ds1307
# repeated synchronization is not necessary unless the external RTC
# is much more accurate than the internal clock
update_interval: never
- platform: homeassistant
# instead try to synchronize via network repeatedly ...
on_time_sync:
then:
# ... and update the RTC when the synchronization was successful
ds1307.write_time:
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
Name |
Meaning |
Range (inclusive) |
Example |
|
Seconds after the minute |
[0-60] (generally [0-59], extra range is to accommodate leap seconds.) |
42 |
|
Minutes after the hour |
[0-59] |
31 |
|
Hours since midnight |
[0-23] |
16 |
|
Day of the week, sunday=1 |
[1-7] |
7 (saturday) |
|
Day of the month |
[1-31] |
18 |
|
Day of the year |
[1-366] |
231 |
|
Month, january=1 |
[1-12] |
8 (august) |
|
Year since 0 A.C. |
[1970-∞[ |
2018 |
|
Is daylight savings time |
false, true |
true |
|
Unix epoch time (seconds since UTC Midnight January 1, 1970) |
[-2147483648 - 2147483647] (negative values for time past January 19th 2038) |
1534606002 |
|
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 |
|
Abbreviated weekday name |
Sat |
|
Full weekday name |
Saturday |
|
Weekday as decimal number, where 0 is Sunday and 6 is Saturday |
6 |
|
Day of month as zero-padded decimal number |
01, 02, …, 31 |
|
Abbreviated month name |
Aug |
|
Full month name |
August |
|
Month as zero-padded decimal number |
01, 02, …, 12 |
|
Year without century as a zero-padded decimal number |
00, 01, …, 99 |
|
Year with century as a decimal number |
2018 |
|
Hour (24-hour clock) as a zero-padded decimal number |
00, 01, …, 23 |
|
Hour (12-hour clock) as a zero-padded decimal number |
00, 01, …, 12 |
|
AM or PM designation |
AM, PM |
|
Minute as a zero-padded decimal number |
00, 01, …, 59 |
|
Second as a zero-padded decimal number |
00, 01, …, 59 |
|
Day of year as a zero-padded decimal number |
001, 002, …, 366 |
|
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 |
|
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 |
|
Date and time representation |
Sat Aug 18 16:31:42 2018 |
|
Date representation |
08/18/18 |
|
Time representation |
16:31:42 |
|
A literal |
% |