Schedule

The Schedule integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you create a weekly schedule entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] in Home Assistant from time blocks with defined start and end times. The schedule is active when a time block starts and becomes inactive when it ends, so you can use it as a trigger or condition in automations and scripts.

Configuration

To add the Schedule helper to your Home Assistant instance, use this My button:

After creating schedule blocks, you can press a block to edit the details.

Adding additional data

Adding the following as Additional data will show brightness and color_temp as entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] attributes when the block is active:

brightness: 100
color_temp: 4000

YAML configuration

Alternatively, you can configure and set up this integration manually via YAML. To enable the Schedule integration in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.

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

Attributes

A schedule entity exports state attributes that can be useful in automations and templates.

• 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 or data settings of a time block when that block is active.

Behavior at block boundaries

Time blocks use an inclusive start and an exclusive end. A block from 09:00 to 12:00 is active from 09:00:00.000 up to but not including 12:00:00.000.

When two time blocks on the same day touch (for example, one block from 07:00 to 10:00 and another from 10:00 to 12:00), the schedule transitions cleanly from one to the other:

• The schedule’s state stays on across the boundary. It does not briefly flip to off between two touching blocks.
• The data attributes are replaced with the new block’s data at the moment of the transition.
• An automation triggering on the state changing to off does not fire at a boundary between two touching blocks.
• An automation triggering on an attribute change (for example, a new setpoint) fires once, with the new block’s data.

Overlapping time blocks on the same day are not allowed and are rejected during configuration validation.

List of triggers

The Schedule integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following triggers. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

• Schedule block ended (schedule.turned_off) Triggers when a schedule block ends.

• Schedule block started (schedule.turned_on) Triggers when a schedule block starts.

For an overview of every trigger across all integrations, see the triggers reference.

List of conditions

The Schedule integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following conditions. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

• Schedule is off (schedule.is_off) Tests if one or more schedule blocks are currently not active.

• Schedule is on (schedule.is_on) Tests if one or more schedule blocks are currently active.

For an overview of every condition across all integrations, see the conditions reference.

Actions

To interact with schedules from scriptsScripts are components that allow you to specify a sequence of actions to be executed by Home Assistant when turned on. [Learn more] and automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more], the schedule integration provides the following actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more].

Action: Reload

The schedule.reload action reloads the schedule’s configuration from YAML without the need to restart Home Assistant itself.

Action: Get schedule

The schedule.get_schedule action 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 (for example, schedule.vacuum_robot and schedule.air_purifier in this case).

Every schedule entity response has seven 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.

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

If you want to run the above action once per day, you can create an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] with a time-based triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [Learn more].

triggers:
  - trigger: time
    at: "07:30:00"

Schedule automation examples

You can use a schedule to decide when an automation should start, or to check whether a routine is currently active. Here are two examples you can adapt to your own schedules.

Automation: turn on the porch light when the evening schedule starts

If you use a schedule to define when your porch light should be active, you can start the light automatically when that schedule block begins.

• Trigger: Schedule block started
  • Target: Evening porch light schedule
• Action: Turn on light
  • Target: Porch light

alias: "Turn on the porch light when the evening schedule starts"
triggers:
  - trigger: schedule.turned_on
    target:
      entity_id: schedule.evening_porch_light
actions:
  - action: light.turn_on
    target:
      entity_id: light.porch

Automation: start the robot vacuum only when both quiet-time schedules are off

If you use schedules to keep certain times interruption-free, you can start your robot vacuum only when both of those schedules are no longer active.

• Trigger: Time: 14:00
• Condition: Schedule is off
  • Target: Quiet time schedule, Meeting schedule
  • Condition passes if: All
• Action: Start vacuum cleaner
  • Target: Living room vacuum

alias: "Start the robot vacuum when both quiet-time schedules are off"
triggers:
  - trigger: time
    at: "14:00:00"
conditions:
  - condition: schedule.is_off
    target:
      entity_id:
        - schedule.quiet_time
        - schedule.meeting_time
    options:
      behavior: all
actions:
  - action: vacuum.start
    target:
      entity_id: vacuum.living_room