Timer entity platform

[laupalombi]

((wrote together with @arturpragacz and @synesthesiam ))

Context

Timers are currently implemented as helpers, living under a general-purpose helper infrastructure. This works well for manually configured, automation-friendly timers, but it creates real friction in the context of Voice.

When a user asks Voice to create a timer, the resulting timer exists only within the Voice subsystem and is not exposed as a Home Assistant entity. This significantly limits its usefulness, as it cannot be referenced by automations, dashboards, scripts, or other integrations.

While timer helpers can be used as a workaround, Voice provides no native abstraction for managing them. Users must pre-create helper entities and implement custom allocation, tracking, and cleanup logic through scripts and automations. This effectively requires users to build their own timer management layer on top of Home Assistant.

This approach introduces unnecessary complexity, limits portability of configurations, and places the burden of timer lifecycle management on users rather than the platform. The prevalence of these workarounds highlights the need for a first-class timer architecture that integrates naturally with Home Assistant's entity model.

The natural response to this problem is to introduce a new domain to handle Voice timers. But introducing a second timer domain alongside the existing helper timer would be architecturally inconsistent — there should be one place in Home Assistant where timers live, not two. This proposal defines what that single domain looks like.

Proposal: current timer domain with two entity types

1. Single-item timer

This is the current helper timer, migrated into the new domain. Behaviour, services, and attributes remain identical. Existing automations, scripts, and dashboards continue to work without modification.

2. Multi-item timer

Modeled after the todo entity, a multi-item timer entity holds an arbitrary number of concurrent timer items inside a single entity. This is the type designed for Voice.

Fields per item:

• name — human label set at creation time ("pasta", "cake")
• duration — how long the timer runs
• started_at — timestamp when the timer was started
• status — active / paused / ringing / finished

When a Voice intent fires ("set a 5-minute pasta timer"), it adds a new item to the multi-item timer entity rather than creating a new entity. When the timer finishes or the user cancels it, the item is removed.

Why a single domain matters

Without a dedicated timer domain, solving the Voice problem would require either extending helpers further (the wrong abstraction) or introducing a parallel timer domain alongside the existing one. Both options lead to fragmentation: two different places where timers live, two different service interfaces, and user-facing confusion about which type to use and when.

A single timer domain avoids this. It is the one place in Home Assistant where all timer functionality lives, regardless of whether a timer was created manually by a user or dynamically by Voice.

This is consistent with how todo works: rather than having shopping lists as helpers and a separate domain for calendar-backed to-do lists, everything lives under todo with a shared model.

Why the multi-item model fits HA's architecture

• Consistent with the To-do model. HA already has precedent for multi-item entities. This reuses the same pattern and conceptual contract that integrations and users already understand.
• Entity registry stays clean. The list entity is stable and persistent.
• Voice-friendly. Creating, cancelling, and querying timers via intents becomes straightforward: all operations target items inside one (or a few) well-known entities.
• UI-friendly. A timer list card can show all active timers from a single entity. Individual items can be rendered as progress bars or countdowns without any entity lookup complexity.

Backwards compatibility

Existing helper timers are migrated into the new timer domain as single-item entities. Entity IDs, services, attributes, and behaviour remain unchanged. No automations, scripts, or dashboards require modification. The migration is transparent to the user.

Q&A

• Should there be a single default multi-item timer entity, or one per device/satellite so that "cancel my timer" is scoped to the device that set it?
  -- Yes, there should be a mlti-item timer entity per device/satellite.
• What services does the multi-item timer expose?
  -- Likely timer.start_item, timer.cancel_item, timer.pause_item, timer.get_items — mirroring the To-do service pattern.
• Should finished items auto-remove, or persist briefly for UI acknowledgement (similar to a ringing alarm)?
  -- It should persist archived, like to-do list items
• Should the helper timer migration be automatic and silent, or should users be notified via a repair issue?
  -- I would hope its silent, but that’s a technical issue. Repair is not dramatic.
• How will users automate on multi-item timers?
  -- A dedicated automation trigger that fires whenever one of the timer items changes state
  -- A websocket command that subscribes to timer state changes in a multi-item timer

[TheFes]

Looks like a good proposal.
One remark, how will the timer trigger work with this multi-item timer? (see https://www.home-assistant.io/integrations/timer/#timer-automation-examples)
Do they trigger on every timer of the target entity, or does the trigger needs some adjustments so it can work on a specific timer? And how would that work then, as the timer might not exist when the automation is created.

[laupalombi]

Good question. I see this as a new trigger around timers, the same way we have with Media (Play media or Play a specific media). We can have timer trigger and then you select on which sub-entity of that timer you want to target the action.

[hecktech27]

I really like that this is getting traction and the proposal above looks very promising!
a couple of questions that came to my mind:

• how is confirming timers going to be handled? currently when a timer finishes you confirm with "okay nabu" that you are aware that timer finished and it stops ringing. would it make sense to add a "confirmed" field to each item so all parts of the system are able to know whether a ringing timer has been confirmed by the user? this would allow for further automation like blinking lights while timer is ringing, etc.
• will the per-device-timer-entity be auto-assigned the devices/satellites area?(probably yes if it is auto-created i guess)
• will there be a possibility to control timers in other areas via voice intent(maybe a little bit out of scope of this architecture proposal but maybe something to discuss when planning the details/adjustments of the voice intents)... something like cancel the kitchen timer would be very helpful. think of setting a tea timer in the kitchen and then you go to the living room with your cup of tea and the kitchen timer starts ringing. (i´d like to get rid of my sentence trigger rebooting the kitchen satellite ;) )
• is there any discussion about adding alarm clocks in this or a similar way? as a first step an alarm clock could be a timer with an auto-calculated duration based on the desired alarm time.

Thanks a lot for this!

[TheFes]

My assumptions on this. But feel free to correct where I'm wrong :)

• I would say that will be a status change from ringing to finished (BTW, you can also confirm it with stop)
• I'd expect the ESPHome config for the Voice PE (or other hardware) needs to be adjusted so it will create a device specific multi-item timer entity for that device. So the timer entity will be part of the device.
• This is more related to the voice project, but as soon as there are entities, I would say it would be possible to target them using voice commands as well. Of course this will require changes on the intents side as well.
• An alarm clock is basically a timer but with focus on the end time instead of the duration. But if you have it on your night stand you probably don't want a glowing ring on the Voice PE the whole night, so I'd say an alarm clock should be handled a bit different.

[hecktech27]

status change of the multi-item entity? what would be the status of that entity if there is one timer running, one ringing and one + finished? or am i missing something and items(timers) of that entity have a separate state for themself? i would have assumed that the state of the entity would be a counter for all running timers - same as with the todo lists.

Thanks for your thoughts on my thoughts ;)

[TheFes]

It's the status of the specific item, mentioned here:

2. Multi-item timer

Modeled after the todo entity, a multi-item timer entity holds an arbitrary number of concurrent timer items inside a single entity. This is the type designed for Voice.

Fields per item:

• name — human label set at creation time ("pasta", "cake")
• duration — how long the timer runs
• started_at — timestamp when the timer was started
• status — active / paused / ringing / finished

When a Voice intent fires ("set a 5-minute pasta timer"), it adds a new item to the multi-item timer entity rather than creating a new entity. When the timer finishes or the user cancels it, the item is removed.

[hecktech27]

well i obviously missed that... thanks - i think thats ideal!

[MartinHjelmare]

I don't understand this:

This is the current helper timer, migrated into the new domain.

This entity is already under the "timer" domain, right? What does "migrated into the new domain" mean?

[synesthesiam]

I think this is left over from an earlier version of the proposal.

[MartinHjelmare]

Would be good if the authors can review the text again then and make sure it's current.

[florian-asche]

If I understand the discussion correctly, a large part of the current design is focused on Home Assistant itself, but the perspectives of ESPHome, Assist, voice devices and third-party integrations seem to be missing.

One thing that is definitely needed is a common API/entity model that allows integrations to expose and manage timers, alarms and reminders in a consistent way.

Today we already have several different concepts:

• Assist timers
• Alarm clocks implemented as multiple helper entities
• Vendor-specific alarms and reminders
• ESPHome devices that need local timer/alarm functionality

Without a shared model, every integration has to invent its own representation and automations have no generic way to interact with them.

From my perspective, Home Assistant should provide a common abstraction for:

• Timers
• Alarm clocks (including recurring schedules)
• Reminders

A key requirement should be that timers and alarms continue to work when Home Assistant is unavailable. Devices should be able to execute locally scheduled alarms and timers without requiring a connection to HA.

This also means the architecture should support synchronization in both directions:

If a timer or alarm is created on a device while HA is offline, it should be synchronized back to HA once connectivity is restored.
If a timer or alarm is created in HA while a device is temporarily unavailable, it should be synchronized to the device when it reconnects.

In other words, HA should not necessarily be the only source of truth. The model should support distributed ownership and reconciliation of timers and alarms across devices and Home Assistant.

This would also allow Assist, ESPHome devices, dashboards and automations to interact with timers and alarms through the same API while maintaining offline functionality and resilience.

[omaramin-2000]

If I understand the discussion correctly, a large part of the current design is focused on Home Assistant itself, but the perspectives of ESPHome, Assist, voice devices and third-party integrations seem to be missing.

One thing that is definitely needed is a common API/entity model that allows integrations to expose and manage timers, alarms and reminders in a consistent way.

Today we already have several different concepts:

• Assist timers
• Alarm clocks implemented as multiple helper entities
• Vendor-specific alarms and reminders
• ESPHome devices that need local timer/alarm functionality

Without a shared model, every integration has to invent its own representation and automations have no generic way to interact with them.

From my perspective, Home Assistant should provide a common abstraction for:

• Timers
• Alarm clocks (including recurring schedules)
• Reminders

A key requirement should be that timers and alarms continue to work when Home Assistant is unavailable. Devices should be able to execute locally scheduled alarms and timers without requiring a connection to HA.

This also means the architecture should support synchronization in both directions:

If a timer or alarm is created on a device while HA is offline, it should be synchronized back to HA once connectivity is restored. If a timer or alarm is created in HA while a device is temporarily unavailable, it should be synchronized to the device when it reconnects.

In other words, HA should not necessarily be the only source of truth. The model should support distributed ownership and reconciliation of timers and alarms across devices and Home Assistant.

This would also allow Assist, ESPHome devices, dashboards and automations to interact with timers and alarms through the same API while maintaining offline functionality and resilience.

@florian-asche If you know since long ago, I used to work on this experimental integration for the alarms and reminders implementation. Till now, we can say that it's ready to use in HA dashboard so when you create new items they appear as switches in the device page to enable/disable and they're also editable and can be deleted and so on. All of these functions work just except the satellite announcement and using voice commands so, the activation part that should ring alarms&reminders must be handled by a state until stopped using several methods: on-device stop word or button press, using a sentence for stop/snooze, or from HA dashboard. That functionality is the main point that needs to complete my integration as I am thinking since a while how to implement that until I finally started considering using the integration as something like an MCP server in the native HA core, and the announcement part can be done on ESPHome satellite devices so they can function easily with internal stop word and button press (the same as timers) if that implement which I will try working on it soon hopefully, the only final thing will be adding the alarms/reminders sentences to HA intents. Also, I will try to enable the alarms to ring locally on satellites even if HA is down so they can be just stopped locally (stop word or button press) except the snooze functionality that will rely on HA connection to be done with sentences or manually from the dashboard, and for creating new alarms/reminders as well.