Skip to content

Commit 585e119

Browse files
klaudiusz223klaudiusz223
committed
Rewrite documentation for the time_based_tilt cover component
– Fully updated, expanded and clarified all configuration parameter descriptions.
1 parent 22faa44 commit 585e119

File tree

4 files changed

+246
-0
lines changed

4 files changed

+246
-0
lines changed

‎content/components/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -691,6 +691,7 @@ Often known as "tag" or "card" readers within the community.
691691
"Feedback Cover","components/cover/feedback","feedback_cover.svg","dark-invert"
692692
"HE60R Cover","components/cover/he60r","he60r.jpg",""
693693
"Time-Based Cover","components/cover/time_based","timer.svg","dark-invert"
694+
"Time-Based Cover with Tilt Function","components/cover/time_based_tilt","time_based_tilt.svg","dark-invert"
694695
"Tormatic/Novoferm Cover","components/cover/tormatic","tormatic.png",""
695696
"Tuya Cover","components/cover/tuya","tuya.png",""
696697
{{< /imgtable >}}

‎content/components/cover/time_based_tilt.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
description: "Instructions for setting up time-based covers with tilt function (venetian blinds) driven by one motor in ESPHome."
3+
title: "Time Based Cover with Tilt Function"
4+
params:
5+
seo:
6+
description: Instructions for setting up time-based covers with tilt function (venetian blinds) driven by one motor in ESPHome.
7+
image: time_based_tilt.svg
8+
---
9+
10+
The `time_based_tilt` cover platform allows you to control covers with both position and tilt
11+
using a single motor, without any physical position feedback. This type of mechanism is commonly
12+
used in external venetian blinds. Because no sensors are available, the cover state is always
13+
**assumed**, and both position and tilt are estimated based on how long the motor has been running
14+
in each direction.
15+
16+
The platform can also be used for covers **without** a tilt function — in such cases, the tilt
17+
rotation time should be set to `0ms`.
18+
19+
The implementation includes automatic recalibration at the end positions (0% and 100%), and it
20+
respects **interlock wait time**, **actuator activation time**, and **inertia time** when changing
21+
direction. These timings ensure safe motor operation and allow the component to maintain accurate,
22+
time-based tracking of both position and tilt — even for motors that require a minimum power-on
23+
window, exhibit mechanical inertia before movement, or must not reverse direction immediately.
24+
25+
{{< img src="shutter-tilt.png" alt="Image" width="75.0%" class="align-center" >}}
26+
27+
```yaml
28+
# Example configuration entry
29+
cover:
30+
- platform: time_based_tilt
31+
name: "Time-Based Tilt Cover"
32+
open_duration: 58700ms
33+
close_duration: 57700ms
34+
inertia_open_time: 300ms
35+
tilt_open_duration: 930ms
36+
inertia_close_time: 250ms
37+
tilt_close_duration: 900ms
38+
recalibration_close_time: 6500ms
39+
recalibration_open_time: 4500ms
40+
actuator_activation_open_time: 200ms
41+
actuator_activation_close_time: 250ms
42+
close_sets_tilt: false
43+
open_sets_tilt: false
44+
45+
open_action:
46+
- switch.turn_on: open_cover_switch
47+
48+
close_action:
49+
- switch.turn_on: close_cover_switch
50+
51+
stop_action:
52+
- switch.turn_off: open_cover_switch
53+
- switch.turn_off: close_cover_switch
54+
```
55+
56+
## Configuration variables
57+
58+
- **name** (**Required**, string): The name of the cover.
59+
60+
- **open_duration** (**Required**, [Time](/guides/configuration-types#time)): The amount of time it takes the cover
61+
to open up from the fully-closed state.
62+
63+
- **close_duration** (**Required**, [Time](/guides/configuration-types#time)): The amount of time it takes the cover
64+
to close from the fully-open state.
65+
66+
- **open_action** (**Required**, [Action](/automations/actions#all-actions)): The action that should
67+
be performed when the remote requests the cover to be opened.
68+
69+
- **close_action** (**Required**, [Action](/automations/actions#all-actions)): The action that should
70+
be performed when the remote requests the cover to be closed.
71+
72+
- **stop_action** (**Required**, [Action](/automations/actions#all-actions)): The action that should
73+
be performed when the remote requests the cover to be stopped or
74+
when the cover has been opening/closing for the given durations.
75+
76+
- **tilt_open_duration** (*Optional*, [Time](/guides/configuration-types#time)): The amount of time it takes lamellas
77+
to tilt from the fully-closed state. Defaults to `0ms`.
78+
79+
- **tilt_close_duration** (*Optional*, [Time](/guides/configuration-types#time)): The amount of time it takes lamellas
80+
to tilt from the fully-open state. Defaults to `0ms`.
81+
82+
- **inertia_open_time** (*Optional*, [Time](/guides/configuration-types#time)):
83+
The delay before the cover begins to physically open after changing direction.
84+
During this time the motor is already powered and running, but the cover has not yet started to move.
85+
The accumulated “inertia offset” position is **not reset on every motor start** — it is preserved
86+
across movements until the direction changes again, and after the direction change the distance
87+
required to overcome inertia is **equal to the distance previously travelled in the opposite direction**,
88+
not reset to zero.
89+
90+
- **inertia_close_time** (*Optional*, [Time](/guides/configuration-types#time)):
91+
The delay before the cover begins to physically close after changing direction.
92+
During this time the motor is already powered and running, but the cover has not yet started to move.
93+
The accumulated “inertia offset” position is **not reset on every motor start** — it is preserved
94+
across movements until the direction changes again, and after the direction change the distance
95+
required to overcome inertia is **equal to the distance previously travelled in the opposite direction**,
96+
not reset to zero.
97+
Defaults to `0ms`..
98+
99+
- **interlock_wait_time** (*Optional*, [Time](/guides/configuration-types#time)): The waiting time after a direction
100+
change before the motor is allowed to run again. Useful for motors that must not reverse instantly.
101+
This timer is reset on every direction change and it continues to elapse regardless of whether the cover is currently moving or not.
102+
**Important:** If your installation uses switches that also have an `interlock_wait_time` configured, you *must* set
103+
a delay here that is **not lower** than the value used for the switches.
104+
Leaving this value lower than the switch configuration will cause incorrect position calculations.
105+
Defaults to `0ms`.
106+
107+
- **recalibration_open_time** (*Optional*, [Time](/guides/configuration-types#time)): Additional time the motor remains on
108+
after reaching the fully-open position (100%) for calibration. Defaults to `0ms`.
109+
110+
- **recalibration_close_time** (*Optional*, [Time](/guides/configuration-types#time)): Additional time the motor remains on
111+
after reaching the fully-closed position (0%) for calibration. Defaults to `0ms`.
112+
113+
- **actuator_activation_open_time** (*Optional*, [Time](/guides/configuration-types#time)):
114+
Additional activation time applied **before** the cover starts opening.
115+
During this time the motor is already powered, but the mechanism has not yet begun to move.
116+
This value is counted **from the moment power is applied**, and it **resets whenever power is removed**.
117+
Required for motors that must receive power for a minimum duration before movement begins
118+
(e.g. drives specifying requirements such as *“Continuous orders of at least 200 ms must be sent
119+
to ensure proper execution”*).
120+
Defaults to `0ms`.
121+
122+
- **actuator_activation_close_time** (*Optional*, [Time](/guides/configuration-types#time)):
123+
Additional activation time applied **before** the cover starts closing.
124+
During this time the motor is powered but the mechanism has not yet started moving.
125+
The time is **measured from the moment power is applied**, and it **resets when power is removed**.
126+
Use this when motors require a minimum “power-on” window before responding to a closing command
127+
or direction change.
128+
Defaults to `0ms`.
129+
130+
- **close_sets_tilt** (*Optional*, boolean): When set to `true`, issuing a *close* command
131+
(i.e., setting the cover position to `0.0` without specifying any tilt value) will also
132+
set tilt position `0.0`.
133+
Defaults to `false`.
134+
135+
- **open_sets_tilt** (*Optional*, boolean): When set to `true`, issuing an *open* command
136+
(i.e., setting the cover position to `1.0` without specifying any tilt value) will also
137+
set tilt position `1.0`.
138+
Defaults to `false`.
139+
140+
- **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known.
141+
This makes Home Assistant show both OPEN and CLOSE buttons. Defaults to `true`.
142+
143+
- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for code generation.
144+
145+
- All other options from [Cover](/components/cover#config-cover).
146+
147+
148+
### Note on execution order of timing parameters
149+
150+
The cover movement sequences apply timing parameters in a fixed, deterministic order.
151+
Each stage begins **only after** the previous one has fully completed.
152+
153+
#### Order for **opening**:
154+
155+
1. **interlock_wait_time** – waiting time after a direction change before movement is allowed.
156+
2. **actuator_activation_open_time** – initial power-on time required by some actuators before movement begins.
157+
3. **inertia_open_time** – delay before the cover starts moving when changing direction.
158+
4. **tilt_open_duration** – time used to tilt lamellas toward the fully-open position (if applicable).
159+
5. **open_duration** – main travel time of the cover from closed to open.
160+
6. **recalibration_open_time** – extra time the motor remains powered after reaching the open limit.
161+
162+
#### Order for **closing**:
163+
164+
1. **interlock_wait_time** – waiting time after a direction change before movement is allowed.
165+
2. **actuator_activation_close_time** – initial power-on time required by some actuators before movement begins.
166+
3. **inertia_close_time** – delay before the cover starts moving when changing direction.
167+
4. **tilt_close_duration** – time used to tilt lamellas toward the fully-close position (if applicable).
168+
5. **close_duration** – main travel time of the cover from open to closed.
169+
6. **recalibration_close_time** – extra time the motor remains powered after reaching the closed limit.
170+
171+
> [!NOTE]
172+
> The stop button on the UI is always enabled even when the cover is stopped and each press
173+
> on the button will cause the `stop_action` to be performed.
174+
175+
176+
177+
## See Also
178+
179+
- {{< docref "index/" >}}
180+
- [Automation](/automations)
181+
- {{< apiref "time_based/time_based_cover.h" "time_based/time_based_cover.h" >}}

‎static/images/shutter-tilt.png‎

11.7 KB
Loading

‎static/images/time_based_tilt.svg‎

Lines changed: 64 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)