home-assistant.io/source/_integrations/timer.markdown

title, description, ha_category, ha_release, ha_quality_scale, ha_domain

title	description	ha_category	ha_release	ha_quality_scale	ha_domain
Timer	Instructions on how to integrate timers into Home Assistant.	Automation	0.57	internal	timer

The timer integration aims to simplify automations based on (dynamic) durations.

When a timer finishes or gets canceled the corresponding events are fired. This allows you to differentiate if a timer has switched from active to idle because the given duration has elapsed or it has been canceled. To control timers in your automations you can use the services mentioned below. When calling the start service on a timer that is already running, it resets the duration it will need to finish and restart the timer without triggering a canceled or finished event. This, for example, makes it easy to create timed lights that get triggered by motion. Starting a timer triggers a started event unless the timer is paused, in that case, it triggers a restarted event.

With the current implementation timers don't persist over restarts. After a restart, they will be idle again, together with their initial configuration.

Configuration

To add a timer to your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
timer:
  laundry:
    duration: "00:01:00"

{% configuration %} "[alias]": description: Alias for the timer. Multiple entries are allowed. required: true type: map keys: name: description: Friendly name of the timer. required: false type: string duration: description: Initial duration in seconds or 00:00:00 when Home Assistant starts. required: false type: [integer, time] default: 0 icon: description: Set a custom icon for the state card. required: false type: icon {% endconfiguration %}

Pick an icon that you can find on materialdesignicons.com to use for your timer and prefix the name with mdi:. For example mdi:car, mdi:ambulance, or mdi:motorbike.

Possible States

State	Description
idle	Timer is idle because the timer finished, was canceled or was never started
active	Timer is currently running because it was (re-)started
paused	Timer is paused because it was paused

Events

Event	Description
timer.cancelled	Fired when a timer has been canceled
timer.finished	Fired when a timer has completed
timer.started	Fired when a timer has been started
timer.restarted	Fired when a timer has been restarted
timer.paused	Fired when a timer has been paused

Services

Service timer.start

Starts or restarts a timer with the provided duration. If no duration is given, it will either restart with its initial value, or continue a paused timer with the remaining duration. If a new duration is provided, this will be the new default for the timer until Home Assistant is restarted (which loads your default values). The duration can be specified as a number of seconds or the easier to read 01:23:45 format.
You can also use entity_id: all and all active timers will be started.

Service data attribute	Optional	Description
entity_id	no	Name of the entity to take action, e.g., timer.timer0.
duration	yes	Duration in seconds or 00:00:00 until the timer finishes.

Service timer.pause

Pause a running timer. This will retain the remaining duration for later continuation. You can also use entity_id: all and all active timers will be paused.

Service data attribute	Optional	Description
entity_id	no	Name of the entity to take action, e.g., timer.timer0.

Service timer.cancel

Cancel an active timer. This resets the duration to the last known initial value without firing the timer.finished event. You can also use entity_id: all and all active timers will be canceled.

Service data attribute	Optional	Description
entity_id	no	Name of the entity to take action, e.g., timer.timer0.

Service timer.finish

Manually finish a running timer earlier than scheduled. You can also use entity_id: all and all active timers will be finished.

Service data attribute	Optional	Description
entity_id	no	Name of the entity to take action, e.g., timer.timer0.

Service timer.reload

Reload timer's configuration without restarting Home Assistant itself. This service takes no service data attributes.

Use the service

Navigate to Developer Tools -> Services and select the timer.start service, then click the Fill Example Data button. Now change the entity_id and duration and click Call Service button.

Examples

Set a timer called test to a duration of 30 seconds.

# Example configuration.yaml entry
timer:
  test:
    duration: "00:00:30"

Control a timer from the frontend

# Example automations.yaml entry
- alias: "Timerswitch"
  id: "Timerstart"
  # Timer is started when the switch pumprun is set to on.
  trigger:
  - platform: state
    entity_id: switch.pumprun
    to: "on"
  action:
  - service: timer.start
    target:
      entity_id: timer.test

# When timer is stopped, the time run out, another message is sent
- alias: "Timerstop"
  id: "Timerstop"
  trigger:
  - platform: event
    event_type: timer.finished
    event_data:
      entity_id: timer.test
  action:
  - service: notify.nma
    data:
      message: "Timer stop"

Control a timer manually

With the script integration you would be able to control a timer (see above for a timer configuration sample) manually.

script:
  start_timer:
    alias: "Start timer"
    sequence:
      - service: timer.start
        target:
          entity_id: timer.test
  pause_timer:
    alias: "Pause timer"
    sequence:
      - service: timer.pause
        target:
          entity_id: timer.test
  cancel_timer:
    alias: "Cancel timer"
    sequence:
      - service: timer.cancel
        target:
          entity_id: timer.test
  finish_timer:
    alias: "Finish timer"
    sequence:
      - service: timer.finish
        target:
          entity_id: timer.test