Home Assistant custom integration for schedule management. For the Lovelace UI you need Homie Scheduler Cards.
- Schedule management for switch, input_boolean, light, fan, cover, climate, and water_heater entities
- Multiple entities in one instance; time, duration (optional), weekdays
- Custom service_start/service_end per item; conflict protection; overlapping schedules
- Per-entity max run time (optional): set in the integration options for multiple entities. When set, the integration turns the entity off after that many minutes whenever the device is on and Home Assistant is running—regardless of how it was turned on (schedule, button, or manually). Supported domains include switch, climate, water_heater, and others the scheduler controls.
The integration schedules turn-on/turn-off by setting deferred callbacks in code via async_call_later(). It does not use automations or timer entities. After an HA restart, it rebuilds the schedule from config, enforces the current schedule state once per entity (so devices recover if HA was down), then reschedules timers.
- Copy the folder
custom_components/homie_schedulerinto your Home Assistant config directory so you haveconfig/custom_components/homie_scheduler/with all integration files inside. - Restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration → search for Homie Scheduler and add it.
- Homie Scheduler Cards for the Lovelace UI (install from the repository)
- Home Assistant 2025.9 or newer
| Entity | Entity ID | Type | Description |
|---|---|---|---|
| Scheduler Info | sensor.homie_scheduler_info |
sensor | Bridge sensor used by Lovelace cards. Attributes: entry_id, items, entity_next_runs (next slot start + duration), entity_next_transitions (next event start or end, fallback), entity_last_runs, active_buttons, max_runtime_turn_off_times, entity_max_runtime. Per-entity data for all cards. |
| Schedule Enabled | switch.homie_scheduler_enabled |
switch | Toggle to enable or disable the scheduler. |
| Service | Description | Main fields |
|---|---|---|
| set_items | Replace all schedule items at once. | entry_id, items |
| add_item | Add a new schedule slot. | entry_id, entity_id, time, weekdays, duration, service_start, service_end, enabled |
| update_item | Update an existing slot. | entry_id, item_id, plus optional entity_id, time, weekdays, duration, enabled, service_start, service_end |
| delete_item | Remove a schedule slot. | entry_id, item_id |
| set_enabled | Enable or disable the scheduler (master switch: when off, no slots run). Example: turn off the schedule while on vacation without deleting slots. | entry_id, enabled |
| toggle_enabled | Toggle scheduler on/off. Example: single button or scene to start or pause the schedule. | entry_id |
| set_active_button | Mark a "RUN FOR" button as active (used by button card). | entry_id, entity_id, button_id, timer_end, duration |
| clear_active_button | Clear active button when entity turns off. | entry_id, entity_id |
| register_entity_for_last_run | Register an entity for “latest activity” tracking (used by status card). | entry_id, entity_id |
| enable_all_slots | Set every schedule slot to enabled in one call (slots keep their time/weekdays; only the enabled flag is set to true). Example: scene that turns the scheduler on and re-enables all slots after you had disabled some. | entry_id |
| set_entity_max_runtime | Set per-entity max run time in minutes (entity is turned off after that time whenever it is on, regardless of how it was turned on). Example: automation or options UI to cap run time for a boiler or climate entity. | entry_id, entities (list of { entity_id, max_minutes }) |
All services are in domain homie_scheduler. Cards use these services internally; manual calls are rarely needed.
Weekdays: In add_item and update_item, weekdays is a list of integers 0–6: 0 = Monday, 1 = Tuesday, …, 6 = Sunday (ISO weekday). Example: [0, 1, 2, 3, 4] = weekdays only.
How to find entry_id: Open Developer Tools → States, find the sensor named Scheduler Info (entity ID like sensor.<your_device_slug>_info), and read the entry_id attribute.
The integration does not create automations or timer entities in Home Assistant. Everything runs inside the integration. It uses internal timers (async_call_later). When a slot starts, it calls service_start (e.g. switch.turn_on). When the slot ends or the duration is over, it calls service_end (e.g. switch.turn_off). The schedule is stored in the integration config. After an HA restart it reads the config and sets all timers again. Max runtime (auto turn-off) and “run for X minutes” from the button card work the same way: a timer in code that turns the entity off when the time is up.
Entity turned on from outside (manual, physical button, another automation): the integration does not cancel that. It only listens to state changes on the Home Assistant server. If max runtime is set for that entity, it starts a timer and turns the entity off after that many minutes. This works even if the app or browser is closed, because the integration runs on the server. The status card can show “will be off in X” . If there is also an active schedule slot, the entity is turned off at the slot end (or at max runtime, whichever is earlier). When the entity is turned off (by anyone), the integration clears the “active button” state so the UI updates.
In the integration config screen (Options) you can set entity max run time: add multiple entities and a max run time in minutes for each. The integration does not register an OptionsUpdateListener (entry.add_update_listener). When you save options, the flow calls async_schedule_reload(), so the integration reloads and the new options take effect. When a service updates options (e.g. set_items, set_active_button, update_item), it calls coordinator.async_reload() so the coordinator picks up the new values.
Supported domains (schedule control and max run time): switch, input_boolean, light, fan, cover, climate, water_heater.
The integration includes several mechanisms to recover gracefully from Home Assistant restarts, power outages, and temporary device unavailability.
Startup recovery for max run time. When the integration starts, it checks every entity that has a max run time configured. If the entity is already on, a max-runtime monitor is started immediately using state.last_changed as the run start so that elapsed time is accounted for. Because some entities may not have their correct state right away (e.g. Zigbee devices reconnecting), the check is retried after 5 seconds and again after 30 seconds.
State change triggers reschedule. On every state_changed event for a tracked entity, the integration runs a full reschedule and enforce cycle for that entity (_async_reschedule_entity). This ensures that max_runtime_turn_off_times and per-entity timers are always up to date — for example, when an entity transitions from unknown to on after a network reconnect, the enforce step immediately sets the correct turn-off time so cards can display "will be off in …".
Unknown → off: confirm turn-off on the device. When a device goes through unknown or unavailable (e.g. Zigbee bridge reconnect) and then reports off, the integration sends an explicit turn_off command to the device as a safety measure. This guards against stale state where the device might physically still be on but the integration received off as the default power-on state.
Expired button timers after downtime. The "RUN FOR" button sets a server-side turn-off timer that is persisted in active_buttons. When the integration restarts, _restore_button_turn_off_timers reschedules all button timers. If a timer has already expired during downtime (e.g. HA was off for longer than the button duration), the turn-off fires immediately with zero delay so the device is switched off as soon as the integration is back.
Button duration preserved in display. When the max-runtime monitor starts for an entity that was turned on via a button (e.g. "Run for 20 min"), the integration checks active_buttons and writes the earlier of the two deadlines (button end vs. max run time) into max_runtime_turn_off_times. This prevents the card from briefly showing the button duration and then switching to the longer max run time.
MIT – see LICENSE.