From e189d6d85c5096a4ca890a9f88aef056bc16f9b2 Mon Sep 17 00:00:00 2001 From: brogon Date: Fri, 23 Dec 2022 00:33:58 +0100 Subject: [PATCH] Pcf85063 rtc (#2347) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/time/pcf85063.rst | 99 ++++++++++++++++++++++++++++++++++++ guides/automations.rst | 11 ++-- index.rst | 1 + 3 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 components/time/pcf85063.rst diff --git a/components/time/pcf85063.rst b/components/time/pcf85063.rst new file mode 100644 index 000000000..31e2bf4be --- /dev/null +++ b/components/time/pcf85063.rst @@ -0,0 +1,99 @@ +PCF85063 Time Source +==================== + +You first need to set up the :doc:`I2C ` component. + +.. code-block:: yaml + + # Example configuration entry + time: + - platform: pcf85063 + id: pcf85063_time + +Configuration variables +----------------------- + +- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x51``. +- All other options from :ref:`base_time_config`. + + +.. _pcf85063-write_time_action: + +``pcf85063.write_time`` Action +------------------------------ + +This :ref:`Action ` triggers a synchronization of the current system time to the RTC hardware. + +.. note:: + + PCFe pcf85063 component will *not* write the RTC clock if not triggered *explicitly* by this action. + +.. code-block:: yaml + + on_...: + - pcf85063.write_time + + # in case you need to specify the DS1307 id + - pcf85063.write_time: + id: pcf85063_time + + +.. _pcf85063-read_time_action: + +``pcf85063.read_time`` Action +----------------------------- + +This :ref:`Action ` triggers a synchronization of the current system time from the RTC hardware. + +.. note:: + + The PCF85063 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_...: + - pcf85063.read_time + + # in case you need to specify the DS1307 id + - pcf85063.read_time: + id: pcf85063_time + + +.. _pcf85063-config_example: + +Full 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. + +.. code-block:: yaml + + esphome: + on_boot: + then: + # read the RTC time once when the system boots + pcf85063.read_time: + + time: + - platform: pcf85063 + # 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 + pcf85063.write_time: + + +See Also +-------- + +- :ghedit:`Edit` diff --git a/guides/automations.rst b/guides/automations.rst index 0d6d93356..eba92ce5d 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -394,6 +394,7 @@ All Actions - :ref:`rf_bridge.send_code ` - :ref:`rf_bridge.learn ` - :ref:`ds1307.read_time ` / :ref:`ds1307.write_time ` +- :ref:`pcf85063.read_time ` / :ref:`pcf85063.write_time ` - :ref:`cs5460a.restart ` - :ref:`pzemac.reset_energy ` - :ref:`number.set ` / :ref:`number.to_min ` / :ref:`number.to_max ` / :ref:`number.decrement ` / :ref:`number.increment ` / :ref:`number.operation ` @@ -712,8 +713,8 @@ Configuration variables: - **max_runs** (*Optional*, int): Allows limiting the maxiumun number of runs when using script modes ``queued`` and ``parallel``, use value ``0`` for unlimited runs. Defaults to ``0``. -- **parameters** (*Optional*, :ref:`Script Parameters `): A script can define one - or more parameters that must be provided in order to execute. All parameters defined here are +- **parameters** (*Optional*, :ref:`Script Parameters `): A script can define one + or more parameters that must be provided in order to execute. All parameters defined here are mandatory and must be given when calling the script. - **then** (**Required**, :ref:`Action `): The action to perform. @@ -723,7 +724,7 @@ Configuration variables: ``Script Parameters`` --------------------- -Scripts can be defined with parameters. The arguments given when calling the script can be used within +Scripts can be defined with parameters. The arguments given when calling the script can be used within the script's lambda actions. To define the parameters, add the parameter names under `parameters:` key and specify the data type for that parameter. @@ -765,7 +766,7 @@ script was already running. on_...: then: - script.execute: my_script - + # Calling a non-parameterised script in a lambda - lambda: id(my_script).execute(); @@ -806,7 +807,7 @@ will not be executed. or as lambda -.. code-block:: yaml +.. code-block:: yaml lambda: 'id(my_script).stop();' diff --git a/index.rst b/index.rst index 78c04166b..a2ead2651 100644 --- a/index.rst +++ b/index.rst @@ -659,6 +659,7 @@ Time Components SNTP, components/time/sntp, clock-outline.svg GPS Time, components/time/gps, crosshairs-gps.svg DS1307 RTC, components/time/ds1307, clock-outline.svg + PCF85063 RTC, components/time/pcf85063, clock-outline.svg Misc Components ---------------