Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DS1307 real time clock component #910

Merged
merged 6 commits into from
Jan 8, 2021
Merged

DS1307 real time clock component #910

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5fb85e7
add DS1307 documentation
badbadc0ffee Jan 3, 2021
689ea6a
add sync to/from rtc actions
badbadc0ffee Jan 3, 2021
9dd4cfb
changed action names
badbadc0ffee Jan 3, 2021
47ed346
reformat action documentation
badbadc0ffee Jan 3, 2021
2ffa8ca
cleanup lint
badbadc0ffee Jan 3, 2021
32fad10
link actions
badbadc0ffee Jan 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 73 additions & 1 deletion components/time.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
badbadc0ffee marked this conversation as resolved.
Show resolved Hide resolved
***********************

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expected to read more, like how to use this in conjuntion with another time source so this source is used as a fallback mostly.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to elaborate a bit more on this once the PR esphome/esphome#1442 has settled: I'd rather give a more complete example once there are elegant ways to synchronize clocks instead of the - kind of improvised - possibilities that now exist in more or less bulky lambda expression.

That would then look similar to this:

esphome:
  on_boot:
    then:
      ds1307.read:

time:
  - platform: ds1307
    update_interval: never
  - platform: homeassistant
    on_time_sync:
      then:
        ds1307.write:

Use In Lambdas
--------------

Expand Down Expand Up @@ -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
Expand Down