Add BM8563 time component documentation

Co-authored-by: abmantis <[email protected]>

Author: Aperion

content/components/time/bm8563.md

@@ -0,0 +1,110 @@
+---
+description: "BM8563 Time Source"
+title: "BM8563 Time Source"
+---
+
+You first need to set up the {{< docref "/components/i2c" "I2C" >}} component.
+
+```yaml
+# Example configuration entry
+time:
+  - platform: bm8563
+    id: bm8563_time
+```
+
+## Configuration variables
+
+- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to `0x51`.
+- **sleep_duration** (*Optional*, [Time](#config-time)): Configure a deep sleep duration for devices that support it.
+- All other options from [Base Time Configuration](#base_time_config).
+
+{{< anchor "bm8563-write_time_action" >}}
+
+## `bm8563.write_time` Action
+
+This [Action](#config-action) triggers a synchronization of the current system time to the RTC hardware.
+
+> [!NOTE]
+> The BM8563 component will *not* write the RTC clock if not triggered *explicitly* by this action.
+
+```yaml
+on_...:
+  - bm8563.write_time
+
+  # in case you need to specify the BM8563 id
+  - bm8563.write_time:
+      id: bm8563_time
+```
+
+{{< anchor "bm8563-read_time_action" >}}
+
+## `bm8563.read_time` Action
+
+This [Action](#config-action) triggers a synchronization of the current system time from the RTC hardware.
+
+> [!NOTE]
+> The BM8563 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.
+
+```yaml
+on_...:
+  - bm8563.read_time
+
+  # in case you need to specify the BM8563 id
+  - bm8563.read_time:
+      id: bm8563_time
+```
+
+{{< anchor "bm8563-apply_sleep_duration_action" >}}
+
+## `bm8563.apply_sleep_duration` Action
+
+This [Action](#config-action) configures the RTC alarm for deep sleep functionality.
+
+```yaml
+on_...:
+  - bm8563.apply_sleep_duration:
+      sleep_duration: 60s
+
+  # in case you need to specify the BM8563 id
+  - bm8563.apply_sleep_duration:
+      id: bm8563_time
+      sleep_duration: 60s
+```
+
+{{< anchor "bm8563-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.
+
+```yaml
+esphome:
+  on_boot:
+    then:
+      # read the RTC time once when the system boots
+      bm8563.read_time:
+
+time:
+  - platform: bm8563
+    # 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
+        bm8563.write_time:
+```
+
+## See Also
+
+- {{< docref "/components/i2c" "I2C Bus" >}}
+- {{< docref "/components/time" "Time Component" >}}
+- {{< docref "/components/deep_sleep" "Deep Sleep Component" >}}