Skip to content

Commit 90fd6c3

Browse files
abmantisCopilotswoboda1337
authored
Add BM8563 time component documentation (#5542)
* Add BM8563 time component documentation Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> * Update BM8563 docs to use timer_value instead of sleep_duration Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> * Fix BM8563 icon by adding .svg extension Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> * Add configuration options for bm8563.start_timer action Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> * Remove timer_value from component configuration Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> * Clean up --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: abmantis <974569+abmantis@users.noreply.github.com> Co-authored-by: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
1 parent 8178cb0 commit 90fd6c3

File tree

3 files changed

+116
-0
lines changed

3 files changed

+116
-0
lines changed

‎content/components/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1001,6 +1001,7 @@ at the {{< docref "light/fastled" "FastLED Light" >}}.
10011001

10021002
{{< imgtable >}}
10031003
"Time Core","components/time/index","clock-outline.svg","dark-invert"
1004+
"BM8563 RTC","components/time/bm8563","bm8563.svg",""
10041005
"DS1307 RTC","components/time/ds1307","clock-outline.svg","dark-invert"
10051006
"RX8130 RTC","components/time/rx8130","clock-outline.svg","dark-invert"
10061007
"GPS Time","components/time/gps","crosshairs-gps.svg","dark-invert"

‎content/components/time/bm8563.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
description: "BM8563 Time Source"
3+
title: "BM8563 Time Source"
4+
---
5+
6+
You first need to set up the {{< docref "/components/i2c" "I2C" >}} component.
7+
8+
```yaml
9+
# Example configuration entry
10+
time:
11+
- platform: bm8563
12+
id: bm8563_time
13+
```
14+
15+
## Configuration variables
16+
17+
- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to `0x51`.
18+
- All other options from [Base Time Configuration](#base_time_config).
19+
20+
{{< anchor "bm8563-write_time_action" >}}
21+
22+
## `bm8563.write_time` Action
23+
24+
This [Action](#config-action) triggers a synchronization of the current system time to the RTC hardware.
25+
26+
> [!NOTE]
27+
> The BM8563 component will *not* write the RTC clock if not triggered *explicitly* by this action.
28+
29+
```yaml
30+
on_...:
31+
- bm8563.write_time
32+
33+
# in case you need to specify the BM8563 id
34+
- bm8563.write_time:
35+
id: bm8563_time
36+
```
37+
38+
{{< anchor "bm8563-read_time_action" >}}
39+
40+
## `bm8563.read_time` Action
41+
42+
This [Action](#config-action) triggers a synchronization of the current system time from the RTC hardware.
43+
44+
> [!NOTE]
45+
> The BM8563 component will automatically read the RTC clock every 15 minutes by default and synchronize the
46+
> system clock when a valid timestamp was read from the RTC. (The `update_interval` can be changed.)
47+
> This action can be used to trigger *additional* synchronizations.
48+
49+
```yaml
50+
on_...:
51+
- bm8563.read_time
52+
53+
# in case you need to specify the BM8563 id
54+
- bm8563.read_time:
55+
id: bm8563_time
56+
```
57+
58+
{{< anchor "bm8563-start_timer_action" >}}
59+
60+
## `bm8563.start_timer` Action
61+
62+
This [Action](#config-action) starts the RTC timer.
63+
64+
```yaml
65+
on_...:
66+
- bm8563.start_timer:
67+
duration: 60s
68+
69+
# in case you need to specify the BM8563 id
70+
- bm8563.start_timer:
71+
id: bm8563_time
72+
duration: 60s
73+
```
74+
75+
Configuration options:
76+
77+
- **duration** (**Required**, [Time](#config-time)): The time duration for the timer.
78+
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID of the BM8563 component if you have multiple components.
79+
80+
{{< anchor "bm8563-config_example" >}}
81+
82+
## Full Configuration Example
83+
84+
In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an
85+
external time source might not always be available e.g. due to a limited network connection.
86+
In order to have a valid, reliable system time, the system should read the RTC once at start and then try to
87+
synchronize with an external reliable time source.
88+
When a synchronization to another time source was successful, the RTC can be resynchronized.
89+
90+
```yaml
91+
esphome:
92+
on_boot:
93+
then:
94+
# read the RTC time once when the system boots
95+
bm8563.read_time:
96+
97+
time:
98+
- platform: bm8563
99+
# repeated synchronization is not necessary unless the external RTC
100+
# is much more accurate than the internal clock
101+
update_interval: never
102+
- platform: homeassistant
103+
# instead try to synchronize via network repeatedly ...
104+
on_time_sync:
105+
then:
106+
# ... and update the RTC when the synchronization was successful
107+
bm8563.write_time:
108+
```
109+
110+
## See Also
111+
112+
- {{< docref "/components/i2c" "I2C Bus" >}}
113+
- {{< docref "/components/time" "Time Component" >}}
114+
- {{< docref "/components/deep_sleep" "Deep Sleep Component" >}}

‎static/images/bm8563.svg‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)