{"id":13585968,"url":"https://github.com/nielsfaber/scheduler-component","last_synced_at":"2025-04-14T06:52:45.226Z","repository":{"id":39604390,"uuid":"286186485","full_name":"nielsfaber/scheduler-component","owner":"nielsfaber","description":"Custom component for HA that enables the creation of scheduler entities","archived":false,"fork":false,"pushed_at":"2024-11-16T06:29:51.000Z","size":354,"stargazers_count":732,"open_issues_count":12,"forks_count":46,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-07T01:06:54.750Z","etag":null,"topics":["custom-component","hacs","homeassistant","integration","python","scheduler"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nielsfaber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-09T07:12:37.000Z","updated_at":"2025-04-06T23:31:37.000Z","dependencies_parsed_at":"2023-01-29T04:15:29.845Z","dependency_job_id":"5eb37c6d-7f73-473c-870f-1eb19081078e","html_url":"https://github.com/nielsfaber/scheduler-component","commit_stats":{"total_commits":272,"total_committers":19,"mean_commits":14.31578947368421,"dds":0.6911764705882353,"last_synced_commit":"9283b87c08da03dcc44c1695d2f9d2bcc70c6347"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nielsfaber%2Fscheduler-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nielsfaber%2Fscheduler-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nielsfaber%2Fscheduler-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nielsfaber%2Fscheduler-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nielsfaber","download_url":"https://codeload.github.com/nielsfaber/scheduler-component/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837274,"owners_count":21169373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-component","hacs","homeassistant","integration","python","scheduler"],"created_at":"2024-08-01T15:05:15.072Z","updated_at":"2025-04-14T06:52:45.191Z","avatar_url":"https://github.com/nielsfaber.png","language":"Python","funding_links":[],"categories":["Python","Custom Integrations"],"sub_categories":["🛠️ Automation tooling"],"readme":"# scheduler-component\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/hacs/integration)\n## Introduction\nThis is a custom component for Home Assistant, that is used for controlling your existing devices based on time.\nIt works nicely together with the [Lovelace scheduler card](https://github.com/nielsfaber/scheduler-card).\n\nA scheduler entity defines an action at a certain time, for example 'turn on my lamp at 21:00 every day'.\nAny entity in HA can be used for making a scheduler entity, together with any service that is available in HA.\n\n## Installation\n\n### Step 1: Download files\n\n#### Option 1: Via HACS\n\nMake sure you have HACS installed. If you don't, run `wget -O - https://get.hacs.xyz | bash -` in HA.  \nChoose Integrations under HACS. Click the '+' button on the bottom of the page, search for \"scheduler component\", choose it, and click install in HACS.\n\n#### Option 2: Manual\nClone 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.\n\n\n### Step 2: Restart HA\nIn order for the newly added integration to be loaded, HA needs to be restarted.\n\n### Step 3: Add integration to HA (\u003c--- this is a step that a lot of people forget)\nIn HA, go to Configuration \u003e Integrations.\nIn the bottom right corner, click on the big button with a '+'.\n\nIf the component is properly installed, you should be able to find 'Scheduler' in the list. You might need to clear you browser cache for the integration to show up.\n\n\nSelect it, and the scheduler integration is ready for use.\n\n### Step 4: Add the scheduler-card\nFollow instructions on [Lovelace scheduler card](https://github.com/nielsfaber/scheduler-card) to setup the card that allows you to configure scheduler entities.\n\n\n## Updating\n1. Update the files:\n   - Using HACS:\n   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.\n   - Manually:\n   Download the [latest release](https://github.com/nielsfaber/scheduler-component/releases/latest) as a zip file and extract it into the custom_components folder in your HA installation, overwriting the previous installation.\n2. Restart HA to load the changes.\n\n**To see which version is installed:**\nIn HA, go to Configuration -\u003e 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.\n\n## Uninstalling\n\n1. Remove scheduler from HA:\nIn HA go to Configuration -\u003e Integrations. Find the card for scheduler integration, click the button with the 3 dots, and click 'Delete'.\n2. Remove the files:\n- When installed with HACS:\nIn the HACS panel go to integrations and look for Scheduler component. Click the button with the 3 dots and click 'Uninstall'.\n- When installed manually:\nIn the custom_components directory, remove the 'scheduler' folder.\n3. Restart HA to make all traces of the component disappear.\n\n## Backup\nThe configuration of your schedules is stored in the `.storage` folder in the HA configuration directory, in a file called `scheduler.storage`.\n\nIf you create a snapshot through HA supervisor, this file should automatically be backed up. Else, make sure to include this file in your backup.\n\nThe entities in HA are created from the `scheduler.storage` file upon (re)starting HA.\n\n## Scheduler entities\nEntities that are part of the scheduler integrations will have entity id following according to pattern `switch.schedule_\u003ctoken\u003e`, where `\u003ctoken\u003e` is a randomly generated 6 digit code.\n\nYou 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. \n\n### States\nA scheduler entity can have the following states:\n\n| State       | Description                                                                                                                                |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `off`       | Schedule is disabled.  A disabled schedule will not keep track of time, and will not execute any actions.                                  |\n| `on`        | Schedule has internal timer running and is waiting for the timer to expire. The attribute `next_trigger` provides the moment of expiration |\n| `triggered` | Timer is finished and the action is executed. Entity will wait for 1 minute and then reset the timer.                                      |\n| `unknown`   | Something went wrong, the schedule is not running.                                                                                         |\n\n\n### Services\nSince schedules follow the `switch` platform, you can use the `switch.turn_on` and `switch.turn_off` services to enable and disable schedules.\n\nIn addition, the following services are available.\nNote that this component is meant to be used together with the [Lovelace scheduler card](https://github.com/nielsfaber/scheduler-card), which handles some of the data validation. \n\n\n#### scheduler.add\nAdd a new scheduler entity.\n\n| field         | Type   | Optional/required | Description                                                           | Remarks                                                                                                                                                                                                                                               |\n| ------------- | ------ | ----------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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`.\u003cbr\u003eDefaults to `daily`.                                                                                                                              |\n| `start_date`  | date   | optional          | Starting date at which the schedule should trigger                    | Valid format is `yyyy-mm-dd`.                                                                                                                                                                                                                         |\n| `end_date`    | date   | optional          | Final date for which the schedule should trigger                      | Valid format is `yyyy-mm-dd`.\u003cbr\u003eIf `end_date` is in the past, schedule will not trigger again.                                                                                                                                                       |\n| `timeslots`   | list   | required          | List of times/time intervals with the actions that should be executed | See [Timeslot](#timeslot) for more info.                                                                                                                                                                                                              |\n| `repeat_type` | string | optional          | Control repeat behaviour after triggering.                            | Valid values are: \u003cul\u003e\u003cli\u003e`repeat`: (default value) schedule will loop after triggering\u003c/li\u003e\u003cli\u003e`single`: schedule will delete itself after triggering\u003c/li\u003e\u003cli\u003e`pause`: schedule will turn off after triggering, can be reset by turning on\u003c/li\u003e\u003c/ul\u003e |\n| `name`        | string | optional          | Friendly name for the schedule entity.                                | The name will also be used for the entity_id of the schedule.\u003cbr\u003e Default value is `Schedule #abcdef                     ` where `abcdef`=random generated sequence.                                                                                  |\n\n\n#### scheduler.edit\nUpdate the configuration of an existing scheduler entity.\nOverwrites the old value. \n\nThe 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.\n\nNote that only the parameters that should be changed have to be provided, if a parameter is not provided, the previous value will be kept.\n                                                                                                                                                 \n#### scheduler.remove\nRemove a scheduler entity.\n\n| field       | Type   | Optional/required | Description                       | Remarks                       |\n| ----------- | ------ | ----------------- | --------------------------------- | ----------------------------- |\n| `entity_id` | string | required          | Entity ID of the scheduler entity | e.g. `switch.schedule_123456` |\n\n                                                                     \n#### scheduler.copy\nDuplicate a scheduler entity.\n\n| field       | Type   | Optional/required | Description                                    | Remarks                                                                                                                                                              |\n| ----------- | ------ | ----------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `entity_id` | string | required          | Entity ID of the existing scheduler entity     | e.g. `switch.schedule_123456`                                                                                                                                        |\n| `name`      | string | optional          | Friendly name for the created schedule entity. | The name will also be used for the entity_id of the schedule.\u003cbr\u003e Default value is `Schedule #abcdef                     ` where `abcdef`=random generated sequence. |\n\n\n\n#### scheduler.run_action\nManually trigger a schedule.\n\n| field             | Type    | Optional/required | Description                                                      | Remarks                                                                                                                                                                                                                                                                                                                     |\n| ----------------- | ------- | ----------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `entity_id`       | string  | required          | Entity ID of the scheduler entity                                | e.g. `switch.schedule_123456`                                                                                                                                                                                                                                                                                               |\n| `time`            | string  | optional          | Time for which to trigger the schedule.                          | If a schedule only has a single timeslot, this timeslot will always be triggered.\u003cbr\u003eFor schedules with a multiple timeslots: \u003cul\u003e\u003cli\u003eIf no time is provided: the schedule overlapping the current time (now) is triggered.\u003c/li\u003e\u003cli\u003eIf time is provided: the schedule overlapping the provided time is triggered.\u003c/li\u003e\u003c/ul\u003e |\n| `skip_conditions` | boolean | optional          | Whether the conditions of the schedule should be skipped or not. |                                                                                                                                                                                                                                                                                                                             |\n\n### Data format\n\n#### Timeslot\nA 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.\n\n| Name               | Type    | Optional/required | Description                                                                           | Remarks                                                                                                                                                               |\n| ------------------ | ------- | ----------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `start`            | string  | required          | Time (in 24 hours format) on which the schedule should trigger                        | Should be in the range 00:00-23:59.\u003cbr\u003eEach timeslot should have a unique value.\u003cbr\u003e Input may also be relative to sun: e.g. `sunrise+01:00` or `sunset-00:00`.       |\n| `stop`             | string  | optional          | Time (in 24 hours format) on which the timeslot ends                                  | Only required when defining timeslots.\u003cbr\u003e Should be in the range 00:01-00:00 (start of next day).\u003cbr\u003eThe `stop` time must be at least one minute after `start` time. |\n| `conditions`       | list    | optional          | Conditions that should be validated before the action(s) may be executed              | See [Condition](#condition) for more info.                                                                                                                            |\n| `condition_type`   | string  | optional          | Logic to apply when validating multiple conditions                                    | Valid values are:\u003cul\u003e\u003cli\u003e`and`: All conditions must be met\u003c/li\u003e\u003cli\u003e`or`: One or more of the conditions must be met\u003c/li\u003e\u003c/ul\u003e                                          |\n| `track_conditions` | boolean | optional          | Watch condition entities for changes, repeat the actions once conditions become valid |                                                                                                                                                                       |\n| `actions`          | list    | required          | Actions to execute when the `start` time is reached.                                  | See [Action](#action) for more info.                                                                                                                                  |\n\n**Note**:\n\nTo guarantee compatibility with the scheduler-card, the following conditions need to be met:\n1. A schedule must exist of either: \n  \u003cul\u003e\n    \u003cli\u003eA single timeslot with only \u003ccode\u003estart\u003c/code\u003e time\u003c/li\u003e\n    \u003cli\u003eA list timeslots which ALL have \u003ccode\u003estart\u003c/code\u003e  and \u003ccode\u003estop\u003c/code\u003e time, which are non overlapping and are not relative to sun.\u003c/li\u003e\n  \u003c/ul\u003e\n\n2. Conditions must be the same for all timeslots.\n\n\n3. Actions list may only consist of a single service/service_data combination (multiple actions may only have different entity_id).\n  \n\n### Condition\n\nA condition is used for defining a rule that needs to be validated, before the scheduled action(s) may be executed.\nConditions are currently limited to checking the state of entities.\n\n| Name         | Type   | Optional/required | Description                           | Remarks                                                                                                                                                                                                                                                                                                          |\n| ------------ | ------ | ----------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `entity_id`  | string | required          | Entity to which the condition applies | e.g. `binary_sensor.my_window`                                                                                                                                                                                                                                                                                   |\n| `value`      | string | required          | Value to compare the entity state to  | e.g. `on`                                                                                                                                                                                                                                                                                                        |\n| `match_type` | string | required          | Logic to apply for the comparison     | Valid values are: \u003cul\u003e\u003cli\u003e`is`: entity state must match `value`\u003c/li\u003e\u003cli\u003e`not`: entity state must not match `value`\u003c/li\u003e\u003cli\u003e`below`: entity state must be below `value` (applicable to numerical values only)\u003c/li\u003e\u003cli\u003e`above`: entity state must be above `value` (applicable to numerical values only)\u003c/li\u003e\u003c/ul\u003e |\n\n### Action\n\nAn action is a combination of a HA service with entity_id. \nSee Developer Tools -\u003e Services in HA for available actions and info on valid parameters.\n\n| Name           | Type   | Optional/required | Description                                        | Remarks                   |\n| -------------- | ------ | ----------------- | -------------------------------------------------- | ------------------------- |\n| `entity_id`    | string | required          | Entity to which the action needs to be executed    | e.g.: `light.my_lamp`     |\n| `service`      | string | required          | HA service that needs to be executed on the entity | e.g.: `light.turn_on`     |\n| `service_data` | dict   | optional          | Extra parameters to use in the service call.       | e.g.: `{brightness: 200}` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnielsfaber%2Fscheduler-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnielsfaber%2Fscheduler-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnielsfaber%2Fscheduler-component/lists"}