diff --git a/content/components/_index.md b/content/components/_index.md index 796409e6b8..f13172c3b8 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.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" diff --git a/content/components/time/bm8563.md b/content/components/time/bm8563.md new file mode 100644 index 0000000000..08b78ea8d4 --- /dev/null +++ b/content/components/time/bm8563.md @@ -0,0 +1,114 @@ +--- +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`. +- 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-start_timer_action" >}} + +## `bm8563.start_timer` Action + +This [Action](#config-action) starts the RTC timer. + +```yaml +on_...: + - bm8563.start_timer: + timer_value: 60s + + # in case you need to specify the BM8563 id + - bm8563.start_timer: + id: bm8563_time + 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 + +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