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 actions mentioned below. When calling the start action on a timer that is already running, it resets the duration it will need to finish and restarts 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.

Configuration

The preferred way to configure timer helpers is via the user interface at Settings > Devices & services > Helpers and click the add button; next choose the Timer option.

To be able to add Helpers via the user interface you should have default_config: in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more], it should already be there by default unless you removed it. If you removed default_config: from your configuration, you must add timer: to your configuration.yaml first, then you can use the UI.

Timers can also be configured via configuration.yaml: To add a timer to your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

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

Pick an icon from Material Design Icons to use for your timer and prefix the name with mdi:. For example mdi:car, mdi:ambulance, or mdi:motorbike.

Possible states

Events

Actions

Action 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 duration for the timer until it finishes or is canceled, which then will reset the duration back to the original configured value. 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.

Action timer.change

Change an active timer. This changes the duration of the timer with the duration given. You can also use entity_id: all and all active timers will be changed.

Action timer.pause

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

Action 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.

Action timer.finish

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

Action timer.reload

Reload timer’s configuration without restarting Home Assistant itself. This action takes no data attributes.

Using the action

Navigate to Developer Tools > Actions and select the timer.start action, then click the Fill Example Data button. Now change the entity_id and duration and select Perform action 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.
  triggers:
  - trigger: state
    entity_id: switch.pumprun
    to: "on"
  actions:
  - action: timer.start
    target:
      entity_id: timer.test

# When timer is stopped, the time run out, another message is sent
- alias: "Timerstop"
  id: "Timerstop"
  triggers:
  - trigger: event
    event_type: timer.finished
    event_data:
      entity_id: timer.test
  actions:
  - action: 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:
      - action: timer.start
        target:
          entity_id: timer.test
  pause_timer:
    alias: "Pause timer"
    sequence:
      - action: timer.pause
        target:
          entity_id: timer.test
  cancel_timer:
    alias: "Cancel timer"
    sequence:
      - action: timer.cancel
        target:
          entity_id: timer.test
  finish_timer:
    alias: "Finish timer"
    sequence:
      - action: timer.finish
        target:
          entity_id: timer.test