Pcf85063 rtc (#2347)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/time/pcf85063.rst

@@ -0,0 +1,99 @@
+PCF85063 Time Source
+====================
+
+You first need to set up the :doc:`I2C </components/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 <config-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 <config-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`

guides/automations.rst

@@ -394,6 +394,7 @@ All Actions
 - :ref:`rf_bridge.send_code <rf_bridge-send_code_action>`
 - :ref:`rf_bridge.learn <rf_bridge-learn_action>`
 - :ref:`ds1307.read_time <ds1307-read_time_action>` / :ref:`ds1307.write_time <ds1307-write_time_action>`
+- :ref:`pcf85063.read_time <pcf85063-read_time_action>` / :ref:`pcf85063.write_time <pcf85063-write_time_action>`
 - :ref:`cs5460a.restart <cs5460a-restart_action>`
 - :ref:`pzemac.reset_energy <pzemac-reset_energy_action>`
 - :ref:`number.set <number-set_action>` / :ref:`number.to_min <number-to-min_action>` / :ref:`number.to_max <number-to-max_action>` / :ref:`number.decrement <number-decrement_action>` / :ref:`number.increment <number-increment_action>` / :ref:`number.operation <number-operation_action>`

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
 ---------------