home-assistant.io/source/_integrations/schedule.markdown

title	description	ha_category	ha_release	ha_quality_scale	ha_codeowners	ha_domain	ha_integration_type
Schedule	Instructions on how to make a weekly schedule in Home Assistant.	Automation Helper	2022.9	internal	@home-assistant/core	schedule	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:

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 %}

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 %}

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 %}

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 with the configured time ranges of a schedule. It can return multiple schedules.

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.

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 %}

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 }}<br>
    {% endfor %}
    Your air purifier will run today:
    {% for event in schedules["schedule.air_purifier"][now().strftime('%A').lower()] %}
    - from {{ event.from }} until {{ event.to }}<br>
    {% 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 %}

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 %}