mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-27 19:26:50 +00:00
Improve schedule documentation (#37104)
This commit is contained in:
Richard Kroegel
GitHub
parent
181e1cb426
commit
cec6d7c4c9
@ -12,64 +12,58 @@ ha_domain: schedule
|
||||
ha_integration_type: helper
|
||||
---
|
||||
|
||||
The schedule integration provides a way to create a weekly schedule in
|
||||
Home Assistant that can be used to trigger or make decisions in your
|
||||
automations and scripts.
|
||||
|
||||
The preferred way to configure a schedule is via the user interface at
|
||||
**{% my helpers title="Settings > Devices & services > Helpers." %}** Click the add button
|
||||
and then choose the **{% my config_flow_start domain=schedule title="Schedule" %}** option, or click the My button below.
|
||||
The **Schedule** {% term integration %} provides a way to create a weekly schedule {% term entity %} in Home Assistant, consisting of time blocks with defined start and end times. The schedule is active when a time block starts and becomes inactive when it ends, allowing it to be used for triggering or making decisions in automations and scripts.
|
||||
|
||||
{% include integrations/config_flow.md %}
|
||||
|
||||
To be able to add **{% my helpers title="Helpers" %}** via the user interface you should
|
||||
have `default_config:` in your {% term "`configuration.yaml`" %}, it should already
|
||||
be there by default unless you removed it.
|
||||
{% configuration_basic %}
|
||||
Name:
|
||||
description: Friendly name of the schedule.
|
||||
Icon:
|
||||
description: Icon to display in the frontend for this schedule.
|
||||
Schedule blocks:
|
||||
description: >
|
||||
Press and drag to select time blocks for each day of the week.
|
||||
It is not possible to create overlapping time blocks on the same day.
|
||||
{% endconfiguration_basic %}
|
||||
|
||||
If you removed `default_config:` from your configuration,
|
||||
you must add it back or, alternatively, `schedule:` to your
|
||||
`configuration.yaml` first, before you can create them via the UI.
|
||||
After creating schedule blocks, you can press a block to edit the details.
|
||||
|
||||
Alternatively, a schedule can also be created and configured via YAML
|
||||
configuration. For example:
|
||||
{% configuration_basic %}
|
||||
Start:
|
||||
required: true
|
||||
type: time
|
||||
description: The start time to mark the schedule as active/on.
|
||||
End:
|
||||
required: true
|
||||
type: time
|
||||
description: The end time to mark as inactive/off again.
|
||||
Additional data:
|
||||
required: false
|
||||
type: map
|
||||
description: A mapping of attribute names to values, which will be added to the entity's attributes when the block is active.
|
||||
{% endconfiguration_basic %}
|
||||
|
||||
### Adding additional data
|
||||
|
||||
Adding the following as `Additional data` will show `brightness` and `color_temp` as {% term entity %} attributes when the block is active:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
schedule:
|
||||
thermostat_schedule:
|
||||
name: "Thermostat schedule"
|
||||
monday:
|
||||
- from: "17:00:00"
|
||||
to: "21:00:00"
|
||||
tuesday:
|
||||
- from: "17:00:00"
|
||||
to: "21:00:00"
|
||||
wednesday:
|
||||
- from: "17:00:00"
|
||||
to: "21:00:00"
|
||||
thursday:
|
||||
- from: "17:00:00"
|
||||
to: "21:00:00"
|
||||
friday:
|
||||
- from: "17:00:00"
|
||||
to: "23:00:00"
|
||||
saturday:
|
||||
- from: "07:00:00"
|
||||
to: "10:00:00"
|
||||
- from: "16:00:00"
|
||||
to: "23:00:00"
|
||||
sunday:
|
||||
- from: "07:00:00"
|
||||
to: "21:00:00"
|
||||
brightness: 100
|
||||
color_temp: 4000
|
||||
```
|
||||
|
||||
Defining the schedule in YAML also allows adding extra data to each block, which will
|
||||
appear as attributes on the schedule helper entity when that block is active. This can
|
||||
be used to easily build schedule-based automations.
|
||||
## YAML configuration
|
||||
|
||||
Alternatively, this {% term integration %} can be configured and set up manually via YAML instead.
|
||||
To enable the Integration sensor in your installation, add the following to your {% term "`configuration.yaml`" %} file.
|
||||
|
||||
{% note %}
|
||||
|
||||
The `data` field follows the same logic as described above in *Adding additional data*.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
The `data` key of each block should be a mapping of attribute names to values. In this example,
|
||||
the schedule helper entity will have "Brightness" and "Color temp" attributes when
|
||||
the blocks are active:
|
||||
|
||||
```yaml
|
||||
schedule:
|
||||
@ -116,7 +110,6 @@ schedule:
|
||||
type: icon
|
||||
"monday|tuesday|wednesday|thursday|friday|saturday|sunday":
|
||||
description: A schedule for each day of the week.
|
||||
required: false
|
||||
required: true
|
||||
type: list
|
||||
keys:
|
||||
@ -129,54 +122,59 @@ schedule:
|
||||
required: true
|
||||
type: time
|
||||
data:
|
||||
description: Additional data to add to the entity's attributes when this block is active.
|
||||
description: A mapping of attribute names to values, which will be added to the entity's attributes when the block is active.
|
||||
required: false
|
||||
type: map
|
||||
default: {}
|
||||
{% endconfiguration %}
|
||||
|
||||
### Attributes
|
||||
## Attributes
|
||||
|
||||
A schedule entity's state exports attributes that can be useful in
|
||||
automations and templates.
|
||||
A schedule entity exports state attributes that can be useful in automations and templates.
|
||||
|
||||
| Attribute | Description |
|
||||
| ----- | ----- |
|
||||
| `next_event` | A datetime object containing the next time the schedule is going to change state. |
|
||||
| `key_1`, `key_2`, ... | The mapping values from **Additional data** / `data` settings of a time block when the respective block is active. |
|
||||
|
||||
### Automation example
|
||||
## Automation example
|
||||
|
||||
A schedule creates an on/off (schedule) sensor within the times set. Using the thermostat schedule example above, you can turn on your thermostat:
|
||||
|
||||
```yaml
|
||||
triggers:
|
||||
- trigger: state
|
||||
entity_id:
|
||||
- schedule.thermostat_schedule
|
||||
to: "on"
|
||||
actions:
|
||||
- action: climate.turn_on
|
||||
target:
|
||||
entity_id: climate.thermostat
|
||||
```
|
||||
|
||||
Using the `light_schedule` example from above in an automation might look like this:
|
||||
A schedule creates an on/off (schedule) sensor within the times set.
|
||||
By incorporating the `light_schedule` example from above in an automation, we can turn on a light when the schedule is active.
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
triggers:
|
||||
- trigger: state
|
||||
entity_id:
|
||||
- schedule.light_schedule
|
||||
to: "on"
|
||||
actions:
|
||||
- action: light.turn_on
|
||||
target:
|
||||
entity_id: light.kitchen
|
||||
data:
|
||||
brightness_pct: "{{ state_attr('schedule.light_schedule', 'brightness') }}"
|
||||
kelvin: "{{ state_attr('schedule.light_schedule, 'temperature') }}"
|
||||
- trigger: state
|
||||
entity_id:
|
||||
- schedule.light_schedule
|
||||
to: "on"
|
||||
actions:
|
||||
- action: light.turn_on
|
||||
target:
|
||||
entity_id: light.kitchen
|
||||
data:
|
||||
brightness_pct: "{{ state_attr('schedule.light_schedule', 'brightness') }}"
|
||||
kelvin: "{{ state_attr('schedule.light_schedule', 'color_temp') }}"
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Another automation can be added to turn the lights off once the schedule is inactive:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
triggers:
|
||||
- trigger: state
|
||||
entity_id:
|
||||
- schedule.light_schedule
|
||||
to: "off"
|
||||
actions:
|
||||
- action: light.turn_off
|
||||
target:
|
||||
entity_id: light.kitchen
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user