From 86d503c589a352ed79c0135406803087e9672d58 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 01:39:36 -0700 Subject: [PATCH 1/5] Add BM8563 time component documentation Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> --- content/components/_index.md | 1 + content/components/time/bm8563.md | 110 ++++++++++++++++++++++++++++++ static/images/bm8563.svg | 1 + 3 files changed, 112 insertions(+) create mode 100644 content/components/time/bm8563.md create mode 100644 static/images/bm8563.svg diff --git a/content/components/_index.md b/content/components/_index.md index 796409e6b8..5c2da985ed 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -995,6 +995,7 @@ at the {{< docref "light/fastled" "FastLED Light" >}}. {{< imgtable >}} "Time Core","components/time/index","clock-outline.svg","dark-invert" +"BM8563 RTC","components/time/bm8563","bm8563","" "DS1307 RTC","components/time/ds1307","clock-outline.svg","dark-invert" "GPS Time","components/time/gps","crosshairs-gps.svg","dark-invert" "Home Assistant Time","components/time/homeassistant","home-assistant.svg","dark-invert" diff --git a/content/components/time/bm8563.md b/content/components/time/bm8563.md new file mode 100644 index 0000000000..e60b22467d --- /dev/null +++ b/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" >}} diff --git a/static/images/bm8563.svg b/static/images/bm8563.svg new file mode 100644 index 0000000000..f1a11651f8 --- /dev/null +++ b/static/images/bm8563.svg @@ -0,0 +1 @@ + \ No newline at end of file From b7af2eaa6233ee1fa06130afcc38ef128c840442 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 31 Oct 2025 00:35:44 +0000 Subject: [PATCH 2/5] Update BM8563 docs to use timer_value instead of sleep_duration Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> --- content/components/time/bm8563.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/components/time/bm8563.md b/content/components/time/bm8563.md index e60b22467d..94e782b23e 100644 --- a/content/components/time/bm8563.md +++ b/content/components/time/bm8563.md @@ -15,7 +15,7 @@ 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. +- **timer_value** (*Optional*, [Time](#config-time)): Configure a timer value for devices that support it. - All other options from [Base Time Configuration](#base_time_config). {{< anchor "bm8563-write_time_action" >}} @@ -56,21 +56,21 @@ on_...: id: bm8563_time ``` -{{< anchor "bm8563-apply_sleep_duration_action" >}} +{{< anchor "bm8563-start_timer_action" >}} -## `bm8563.apply_sleep_duration` Action +## `bm8563.start_timer` Action -This [Action](#config-action) configures the RTC alarm for deep sleep functionality. +This [Action](#config-action) starts the RTC timer. ```yaml on_...: - - bm8563.apply_sleep_duration: - sleep_duration: 60s + - bm8563.start_timer: + timer_value: 60s # in case you need to specify the BM8563 id - - bm8563.apply_sleep_duration: + - bm8563.start_timer: id: bm8563_time - sleep_duration: 60s + timer_value: 60s ``` {{< anchor "bm8563-config_example" >}} From 6e077904d8b2e840797121cd8c2bac85a6dad360 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 31 Oct 2025 00:48:58 +0000 Subject: [PATCH 3/5] Fix BM8563 icon by adding .svg extension Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> --- content/components/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/components/_index.md b/content/components/_index.md index 5c2da985ed..f13172c3b8 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -995,7 +995,7 @@ at the {{< docref "light/fastled" "FastLED Light" >}}. {{< imgtable >}} "Time Core","components/time/index","clock-outline.svg","dark-invert" -"BM8563 RTC","components/time/bm8563","bm8563","" +"BM8563 RTC","components/time/bm8563","bm8563.svg","" "DS1307 RTC","components/time/ds1307","clock-outline.svg","dark-invert" "GPS Time","components/time/gps","crosshairs-gps.svg","dark-invert" "Home Assistant Time","components/time/homeassistant","home-assistant.svg","dark-invert" From 56f12fd992a548afb2ff66ffc91712e0c11b9eb0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 31 Oct 2025 01:07:57 +0000 Subject: [PATCH 4/5] Add configuration options for bm8563.start_timer action Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> --- content/components/time/bm8563.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/components/time/bm8563.md b/content/components/time/bm8563.md index 94e782b23e..1c086fd5e2 100644 --- a/content/components/time/bm8563.md +++ b/content/components/time/bm8563.md @@ -73,6 +73,11 @@ on_...: timer_value: 60s ``` +Configuration options: + +- **timer_value** (**Required**, [Time](#config-time)): The time duration for the timer. +- **id** (*Optional*, [ID](#config-id)): Manually specify the ID of the BM8563 component if you have multiple components. + {{< anchor "bm8563-config_example" >}} ## Full Configuration Example From 30024ea7180f9e51b06d809f7c5a94e4c1ed286e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 31 Oct 2025 01:11:07 +0000 Subject: [PATCH 5/5] Remove timer_value from component configuration Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> --- content/components/time/bm8563.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/components/time/bm8563.md b/content/components/time/bm8563.md index 1c086fd5e2..08b78ea8d4 100644 --- a/content/components/time/bm8563.md +++ b/content/components/time/bm8563.md @@ -15,7 +15,6 @@ time: ## Configuration variables - **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to `0x51`. -- **timer_value** (*Optional*, [Time](#config-time)): Configure a timer value for devices that support it. - All other options from [Base Time Configuration](#base_time_config). {{< anchor "bm8563-write_time_action" >}}