Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-01-26 22:21:38 +01:00
Code Issues Projects Releases Wiki Activity

update time (sync) documentation (#924)

Browse Source 
* update time documentation

* Heading

* Update components/time.rst

Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>

* rename read/write to read/time/write_time

* clarify SNTP limitation

* typo

Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>
This commit is contained in:
Florian Mösch 2021-01-18 13:35:20 +01:00 committed by Jesse Hills
parent 8ddb39e6b9
commit 4ffcc0d4ec
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
2 changed files with 241 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

432
components/time.rst
View File

@ -10,7 +10,192 @@ Time
The ``time`` component allows you to set up real time clock time sources for ESPHome.
You can then get the current time in :ref:`lambdas <config-lambda>`.
Currently only SNTP (internet-based), Home Assistant and GPS time sources are supported.
.. _base_time_config:
Base Time Configuration
-----------------------
All time configuration schemas inherit these options.
Configuration variables:
************************
- **id** (*Optional*, :ref:`config-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
<https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html>`__ (warning: the format is quite complicated)
or the simpler `TZ database name <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`__ 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*, :ref:`Automation <automation>`): Automation to run at specific intervals using
a cron-like syntax. See :ref:`time-on_time`.
- **on_time_sync** (*Optional*, :ref:`Automation <automation>`): Automation to run when the time source
could be (re-)synchronized.. See :ref:`time-on_time_sync`.
.. _time-has_time_condition:
``time.has_time`` Condition
***************************
This :ref:`Condition <config-condition>` checks if time has been set and is valid.
.. code-block:: yaml
on_...:
if:
condition:
time.has_time:
then:
- logger.log: Time has been set and is valid!
.. _time-on_time:
``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 <https://crontab.guru/>`__ 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.
.. code-block:: yaml
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 like ``L``, ``#`` are currently not supported.
- See :ref:`Automation <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``.
.. 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:
.. code-block:: yaml
time:
- platform: sntp
# ...
on_time:
- minutes: /5
then:
- switch.toggle: my_switch
.. _time-on_time_sync:
``on_time_sync`` Trigger
************************
This automation is triggered after a time source successfully retrieves the current time.
See the :ref:`DS1307 configuration example <ds1307-config_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.
.. code-block:: yaml
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
--------------------------
@ -28,14 +213,7 @@ to Home Assistant will be used to periodically synchronize the current time.
Configuration variables:
- **id** (*Optional*, :ref:`config-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
<https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html>`__ (warning: the format is quite complicated)
or the simpler `TZ database name <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`__ 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*, :ref:`Automation <automation>`): Automation to run at specific intervals using
a cron-like syntax. See :ref:`time-on_time`.
- All other from :ref:`base_time_config`.
SNTP Configuration
------------------
@ -49,22 +227,21 @@ SNTP Configuration
Configuration variables:
- **id** (*Optional*, :ref:`config-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
<https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html>`__ (warning: the
format is quite complicated) or the simpler `TZ database name <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`__
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.
- **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*, :ref:`Automation <automation>`): Automation to run at specific intervals using
a cron-like syntax. See :ref:`time-on_time`.
- All other options from :ref:`base_time_config`.
.. note::
If your are using :ref:`wifi-manual_ip` 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 componnents, where another time source could
update the time before SNTP synchronizes.
GPS Time Source
---------------
@ -79,14 +256,7 @@ You first need to set up the :doc:`GPS </components/gps>` component.
Configuration variables:
- **id** (*Optional*, :ref:`config-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
<https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html>`__ (warning: the format is quite complicated)
or the simpler `TZ database name <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`__ 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*, :ref:`Automation <automation>`): Automation to run at specific intervals using
a cron-like syntax. See :ref:`time-on_time`.
- All other from :ref:`base_time_config`.
DS1307 Time Source
------------------
@ -102,46 +272,33 @@ You first need to set up the :doc:`I2C </components/i2c>` component.
Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Specify the ID of the time for use in lambdas.
- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x68``.
- **timezone** (*Optional*, string): Manually tell ESPHome what time zone to use with `this format
<https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html>`__ (warning: the format is quite complicated)
or the simpler `TZ database name <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`__ 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*, :ref:`Automation <automation>`): Automation to run at specific intervals using
a cron-like syntax. See :ref:`time-on_time`.
- All other options from :ref:`base_time_config`.
DS1307 Actions
--------------
.. _ds1307-write_time_action:
The DS1307 component supports :ref:`actions <config-action>` that can be used to synchronize the RTC hardware and
the system clock.
.. _ds1307-write_action:
``ds1307.write`` Action
***********************
``ds1307.write_time`` Action
****************************
This :ref:`Action <config-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 *explicitely* by this action.
The DS1307 component will *not* write the RTC clock if not triggered *explicitly* by this action.
.. code-block:: yaml
on_...:
- ds1307.write
- ds1307.write_time
# in case you need to specify the DS1307 id
- ds1307.write:
- ds1307.write_time:
id: ds1307_time
.. _ds1307-read_action:
.. _ds1307-read_time_action:
``ds1307.read`` Action
**********************
``ds1307.read_time`` Action
***************************
This :ref:`Action <config-action>` triggers a synchronization of the current system time from the RTC hardware.
@ -154,12 +311,43 @@ This :ref:`Action <config-action>` triggers a synchronization of the current sys
.. code-block:: yaml
on_...:
- ds1307.read
- ds1307.read_time
# in case you need to specify the DS1307 id
- ds1307.read:
- ds1307.read_time:
id: ds1307_time
.. _ds1307-config_example:
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 successfull, the RTC can be resynchronized.
.. code-block:: yaml
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
--------------
@ -280,148 +468,6 @@ with the current time representation of that format option.
``%%`` A literal ``%`` character %
============= ============================================================== =========================
.. _time-on_time:
``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 <https://crontab.guru/>`__ 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.
.. code-block:: yaml
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 like ``L``, ``#`` are currently not supported.
- See :ref:`Automation <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``.
.. 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:
.. code-block:: yaml
time:
- platform: sntp
# ...
on_time:
- minutes: /5
then:
- switch.toggle: my_switch
.. _time-has_time_condition:
``time.has_time`` Condition
----------------------------
This :ref:`Condition <config-condition>` checks if time has been set and is valid.
.. code-block:: yaml
on_...:
if:
condition:
time.has_time:
then:
- logger.log: Time has been set and is valid!
See Also
--------

5
guides/automations.rst
View File

@ -324,7 +324,7 @@ All Triggers
- :ref:`esphome.on_boot <esphome-on_boot>` / :ref:`esphome.on_shutdown <esphome-on_shutdown>` / :ref:`esphome.on_loop <esphome-on_loop>`
- :ref:`light.on_turn_on / light.on_turn_off <light-on_turn_on_off_trigger>`
- :ref:`logger.on_message <logger-on_message>`
- :ref:`time.on_time <time-on_time>`
- :ref:`time.on_time <time-on_time>` / - :ref:`time.on_time_sync <time-on_time_sync>`
- :ref:`mqtt.on_message <mqtt-on_message>` / :ref:`mqtt.on_json_message <mqtt-on_json_message>`
- :ref:`pn532.on_tag <pn532-on_tag>` / :ref:`rdm6300.on_tag <rdm6300-on_tag>`
- :ref:`interval.interval <interval>`
@ -374,8 +374,7 @@ All Actions
- :ref:`http_request.get <http_request-get_action>` / :ref:`http_request.post <http_request-post_action>` / :ref:`http_request.send <http_request-send_action>`
- :ref:`rf_bridge.send_code <rf_bridge-send_code_action>`
- :ref:`rf_bridge.learn <rf_bridge-learn_action>`
- :ref:`ds1307.read <ds1307-read_action>`
- :ref:`ds1307.write <ds1307-write_action>`
- :ref:`ds1307.read_time <ds1307-read_time_action>` / :ref:`ds1307.write_time <ds1307-write_time_action>`
.. _config-condition: