---
title: Schedule
description: Instructions on how to make a weekly schedule in Home Assistant.
ha_category:
- Automation
- Helper
ha_release: 2022.9
ha_quality_scale: internal
ha_codeowners:
- '@home-assistant/core'
ha_domain: schedule
ha_integration_type: helper
---
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 %}
{% 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 %}
After creating schedule blocks, you can press a block to edit the details.
{% 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
brightness: 100
color_temp: 4000
```
## 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 %}
```yaml
schedule:
light_schedule:
name: "Light schedule"
wednesday:
- from: "17:00:00"
to: "21:00:00"
data:
brightness: 100
color_temp: 4000
thursday:
- from: "17:00:00"
to: "23:00:00"
data:
brightness: 90
color_temp: 3500
friday:
- from: "07:00:00"
to: "10:00:00"
data:
brightness: 80
color_temp: 3000
- from: "16:00:00"
to: "23:00:00"
data:
brightness: 60
color_temp: 2500
```
{% configuration %}
schedule:
description: Alias for the schedule. Multiple entries are allowed.
required: true
type: map
keys:
name:
description: Friendly name of the schedule.
required: true
type: string
icon:
description: Icon to display in the frontend for this schedule.
required: false
type: icon
"monday|tuesday|wednesday|thursday|friday|saturday|sunday":
description: A schedule for each day of the week.
required: true
type: list
keys:
from:
description: The start time to mark the schedule as active/on.
required: true
type: time
to:
description: The end time to mark as inactive/off again.
required: true
type: time
data:
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
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
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', '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 %}
## Actions
To interact with schedules from {% term scripts %} and {% term automations %}, the schedule integration provides the following {% term actions %}.
### Action `schedule.reload`
`schedule.reload` reloads the schedule's configuration from YAML without the need of restarting Home Assistant itself.
### Action `schedule.get_schedule`
`schedule.get_schedule` populates [response data](/docs/scripts/perform-actions#use-templates-to-handle-response-data) with the configured time ranges of a schedule.
It can return multiple schedules.
```yaml
action: schedule.get_schedule
target:
entity_id:
- schedule.vacuum_robot
- schedule.air_purifier
response_variable: schedules
```
The response data contains a field for every schedule entity (e.g. `schedule.vacuum_robot` and `schedule.air_purifier` in this case).
Every schedule entity response has 7 fields (one for each day of the week in lowercase), containing a list of the selected time ranges.
Days without any ranges will be returned as an empty list.
```yaml
schedule.vacuum_robot:
monday:
- from: "09:00:00"
to: "15:00:00"
tuesday: []
wednesday: []
thursday:
- from: "09:00:00"
to: "15:00:00"
friday: []
saturday: []
sunday: []
schedule.air_purifier:
monday:
- from: "09:00:00"
to: "18:00:00"
tuesday: []
wednesday: []
thursday:
- from: "09:00:00"
to: "18:00:00"
friday: []
saturday:
- from: "10:30:00"
to: "12:00:00"
- from: "14:00:00"
to: "19:00:00"
sunday: []
```
The example below uses the response data from above in a template for another action.
{% raw %}
```yaml
action: notify.nina
data:
title: Today's schedules
message: >-
Your vacuum robot will run today:
{% for event in schedules["schedule.vacuum_robot"][now().strftime('%A').lower()] %}
- from {{ event.from }} until {{ event.to }}
{% endfor %}
Your air purifier will run today:
{% for event in schedules["schedule.air_purifier"][now().strftime('%A').lower()] %}
- from {{ event.from }} until {{ event.to }}
{% endfor %}
```
{% endraw %}
If you want to run the above action both once per day and whenever one of the schedules changes, you can create an {% term automation %} that combines a time-based {% term trigger %} with an {% term event %} trigger per entity.
{% raw %}
```yaml
triggers:
- trigger: time
at: "07:30:00"
- trigger: event
event_type: entity_registry_updated
event_data:
action: update
entity_id: schedule.vacuum_robot
- trigger: event
event_type: entity_registry_updated
event_data:
action: update
entity_id: schedule.air_purifier
```
{% endraw %}