Skip to content

Latest commit

 

History

History
187 lines (128 loc) · 17.9 KB

README.md

File metadata and controls

187 lines (128 loc) · 17.9 KB
Raw

scheduler-component

hacs_badge

Introduction

This is a custom component for Home Assistant, that is used for controlling your existing devices based on time. It works nicely together with the Lovelace scheduler card.

A scheduler entity defines an action at a certain time, for example 'turn on my lamp at 21:00 every day'. Any entity in HA can be used for making a scheduler entity, together with any service that is available in HA.

Installation

Step 1: Download files

Option 1: Via HACS

Make sure you have HACS installed. If you don't, run curl -sfSL https://hacs.xyz/install | bash - in HA.
Choose Integrations under HACS. Click the '+' button on the bottom of the page, serch for "scheduler component", choose it, and click install in HACS.

Option 2: Manual

Clone this repository or download the source code as a zip file and add/merge the custom_components/ folder with its contents in your configuration directory.

Step 2: Restart HA

In order for the newly added integration to be loaded, HA needs to be restarted.

Step 3: Add integration to HA (<--- this is a step that a lot of people forget)

In HA, go to Configuration > Integrations. In the bottom right corner, click on the big button with a '+'.

If the component is properly installed, you should be able to find the 'Scheduler integration' in the list. You might need to clear you browser cache for the integration to show up.

Select it, and the scheduler integration is ready for use.

Step 4: Add the scheduler-card

Follow instructions on Lovelace scheduler card to setup the card that allows you to configure scheduler entities.

Updating

  1. Update the files:
    • Using HACS: In the HACS panel, there should be an notification when a new version is available. Follow the instructions within HACS to update the installation files.
    • Manually: Download the latest release as a zip file and extract it into the custom_components folder in your HA installation, overwriting the previous installation.
  2. Restart HA to load the changes.

To see which version is installed: In HA, go to Configuration -> Integrations. In the Scheduler integration card, you should see a link with '1 device', click it. In the table click the 'Scheduler' device, and you should see the Device info. The 'firmware version' represents the installed version number.

Uninstalling

  1. Remove scheduler from HA: In HA go to Configuration -> Integrations. Find the card for scheduler integration, click the button with the 3 dots, and click 'Delete'.
  2. Remove the files:
  • When installed with HACS: In the HACS panel go to integrations and look for Scheduler component. Click the button with the 3 dots and click 'Uninstall'.
  • When installed manually: In the custom_components directory, remove the 'scheduler' folder.
  1. Restart HA to make all traces of the component disappear.

Backup

The configuration of your schedules is stored in the .storage folder in the HA configuration directory, in a file called scheduler.storage.

If you create a snapshot through HA supervisor, this file should automatically be backed up. Else, make sure to include this file in your backup.

The entities in HA are created from the scheduler.storage file upon (re)starting HA.

Scheduler entities

Entities that are part of the scheduler integrations will have entity id following according to pattern switch.schedule_<token>, where <token> is a randomly generated 6 digit code.

You can treat these entities in the same way as other switch entities in HA, meaning that you could place them in any Lovelace card for quick access.

States

A scheduler entity can have the following states:

State Description
off Schedule is disabled. A disabled schedule will not keep track of time, and will not execute any actions.
on Schedule has internal timer running and is waiting for the timer to expire. The attribute next_trigger provides the moment of expiration
triggered Timer is finished and the action is executed. Entity will wait for 1 minute and then reset the timer.
unknown Something went wrong, the schedule is not running.

Services

Since schedules follow the switch platform, you can use the switch.turn_on and switch.turn_off services to enable and disable schedules.

In addition, the following services are available. Note that this component is meant to be used together with the Lovelace scheduler card, which handles some of the data validation.

scheduler.add

Add a new scheduler entity.

field Type Optional/required Description Remarks
weekdays list optional Days (of the week) on which the schedule should be executed Valid values are: mon, tue, wed, thu, fri, sat, sun, daily, workday weekend.
Defaults to daily.
start_date date optional Starting date at which the schedule should trigger Valid format is yyyy-mm-dd.
end_date date optional Final date for which the schedule should trigger Valid format is yyyy-mm-dd.
If end_date is in the past, schedule will not trigger again.
timeslots list required List of times/time intervals with the actions that should be executed See Timeslot for more info.
repeat_type string optional Control repeat behaviour after triggering. Valid values are:
  • repeat: (default value) schedule will loop after triggering
  • single: schedule will delete itself after triggering
  • pause: schedule will turn off after triggering, can be reset by turning on
name string optional Friendly name for the schedule entity. The name will also be used for the entity_id of the schedule.
Default value is Schedule #abcdef where abcdef=random generated sequence.

scheduler.edit

Update the configuration of an existing scheduler entity. Overwrites the old value.

The service parameters are the same as for scheduler.add, except that the entity_id needs to be provided of the schedule which needs to be modified.

Note that only the parameters that should be changed have to be provided, if a parameter is not provided, the previous value will be kept.

scheduler.remove

Remove a scheduler entity.

field Type Optional/required Description Remarks
entity_id string required Entity ID of the scheduler entity e.g. switch.schedule_123456

scheduler.copy

Duplicate a scheduler entity.

field Type Optional/required Description Remarks
entity_id string required Entity ID of the existing scheduler entity e.g. switch.schedule_123456
name string optional Friendly name for the created schedule entity. The name will also be used for the entity_id of the schedule.
Default value is Schedule #abcdef where abcdef=random generated sequence.

scheduler.run_action

Manually trigger a schedule.

field Type Optional/required Description Remarks
entity_id string required Entity ID of the scheduler entity e.g. switch.schedule_123456
time string optional Time for which to trigger the schedule. If a schedule only has a single timeslot, this timeslot will always be triggered.
For schedules with a multiple timeslots:
  • If no time is provided: the schedule overlapping the current time (now) is triggered.
  • If time is provided: the schedule overlapping the provided time is triggered.

Data format

Timeslot

A timeslot defines the timepoints on which a schedule is triggered, together with the actions that need to be executed. Optionally also conditions can be specified that need to be validated before the actions may be fired.

Name Type Optional/required Description Remarks
start string required Time (in 24 hours format) on which the schedule should trigger Should be in the range 00:00-23:59.
Each timeslot should have a unique value.
Input may also be relative to sun: e.g. sunrise+01:00 or sunset-00:00.
stop string optional Time (in 24 hours format) on which the timeslot ends Only required when defining timeslots.
Should be in the range 00:01-00:00 (start of next day).
The stop time must be at least one minute after start time.
conditions list optional Conditions that should be validated before the action(s) may be executed See Condition for more info.
condition_type string optional Logic to apply when validating multiple conditions Valid values are:
  • and: All conditions must be met
  • or: One or more of the conditions must be met
track_conditions boolean optional Watch condition entities for changes, repeat the actions once conditions become valid
actions list required Actions to execute when the start time is reached. See Action for more info.

Note:

To guarantee compatibility with the scheduler-card, the following conditions need to be met:

  1. A schedule must exist of either:
  • A single timeslot with only start time
  • A list timeslots which ALL have start and stop time, which are non overlapping and are not relative to sun.

  1. Conditions must be the same for all timeslots.

  2. Actions list may only consist of a single service/service_data combination (multiple actions may only have different entity_id).

Condition

A condition is used for defining a rule that needs to be validated, before the scheduled action(s) may be executed. Conditions are currently limited to checking the state of entities.

Name Type Optional/required Description Remarks
entity_id string required Entity to which the condition applies e.g. binary_sensor.my_window
value string required Value to compare the entity state to e.g. on
match_type string required Logic to apply for the comparison Valid values are:
  • is: entity state must match value
  • not: entity state must not match value
  • below: entity state must be below value (applicable to numerical values only)
  • above: entity state must be above value (applicable to numerical values only)

Action

An action is a combination of a HA service with entity_id. See Developer Tools -> Services in HA for available actions and info on valid parameters.

Name Type Optional/required Description Remarks
entity_id string required Entity to which the action needs to be executed e.g.: light.my_lamp
service string required HA service that needs to be executed on the entity e.g.: light.turn_on
service_data dict optional Extra parameters to use in the service call. e.g.: {brightness: 200}