DS1307 real time clock component (#910)

* add DS1307 documentation

* add sync to/from rtc actions

* changed action names

* reformat action documentation

* cleanup lint

* link actions
This commit is contained in:
Florian Mösch 2021-01-08 23:42:58 +01:00 committed by GitHub
parent 14fbfe3b64
commit f848da87b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 75 additions and 1 deletions

View File

@ -88,6 +88,78 @@ Configuration variables:
- **on_time** (*Optional*, :ref:`Automation <automation>`): Automation to run at specific intervals using
a cron-like syntax. See :ref:`time-on_time`.
DS1307 Time Source
------------------
You first need to set up the :doc:`I2C </components/i2c>` component.
.. code-block:: yaml
# Example configuration entry
time:
- platform: ds1307
id: ds1307_time
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`.
DS1307 Actions
--------------
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
***********************
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.
.. code-block:: yaml
on_...:
- ds1307.write
# in case you need to specify the DS1307 id
- ds1307.write:
id: ds1307_time
.. _ds1307-read_action:
``ds1307.read`` Action
**********************
This :ref:`Action <config-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.
.. code-block:: yaml
on_...:
- ds1307.read
# in case you need to specify the DS1307 id
- ds1307.read:
id: ds1307_time
Use In Lambdas
--------------
@ -142,7 +214,7 @@ created based on a given format. If you want to get the current time attributes,
.. _strftime:
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 <http://www.cplusplus.com/reference/ctime/strftime/>`__ function which

View File

@ -374,6 +374,8 @@ 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>`
.. _config-condition: