Documentation

Timer Extension

The Timer extension provides sensor and trigger interfaces around elapsed time using Python's perf_counter for accuracy.

Overview

The timer extension works with the Python time library to offer a sensor and trigger interface around elapsed time. It uses perf_counter() for more accurate results with shorter durations.

This extension does not require extension-level configuration and is focused on interfaces.

Trigger Interface

The timer trigger fires actions after a set duration. The timer needs to be started first, then it calls any assigned actions once the duration is reached.

Option	Type	Required	Description
`key`	String	Yes	Unique slug identifier for the component
`duration`	Integer	Yes	Time in seconds before actions are fired. Default: `10`
`frequency`	String	No	Set to `once` to prevent restart while active, or `many` to allow reset on multiple start calls. Default: `once`
`name`	String	No	Friendly display name for the component
`actions`	List	No	List of registered actions to fire
`topic`	String	No	Topic to listen for timer events on. Default: `timer/{key}`

Trigger Actions

Available actions for interacting with timer triggers:

Action	Description
`start`	Starts the timer. If already active and `frequency` is `many`, restarts the timer.
`stop`	Immediately stops and resets the timer
`pause`	Pauses the timer without resetting the duration
`reset`	Resets the timer to the beginning without changing the active state
`restart`	Resets the timer and sets it to active

Trigger Events

The timer also listens for events on its configured topic (default: timer/{key}):

Event	Timer Response
`TimerStart`	Starts the timer; restarts if `frequency` is `many`
`TimerStop`	Immediately stops and resets the timer
`TimerPause`	Pauses the timer without resetting duration
`TimerReset`	Resets the timer without changing active state
`TimerRestart`	Resets and sets the timer to active

Timer Trigger Config

{
  "trigger": [
    {
      "interface": "state",
      "source": "example_1",
      "key": "trigger_timer_start",
      "name": "Start Example Timer",
      "frequency": "once",
      "actions": [".trigger_timer_1.start"],
      "thresholds": [
        {
          "comparison": "gte",
          "value": 5
        }
      ]
    },
    {
      "interface": "timer",
      "key": "trigger_timer_1",
      "name": "Example Trigger Timer",
      "frequency": "many",
      "duration": 10,
      "actions": [".example_toggle.turn_on"]
    }
  ]
}

This configuration turns on a toggle after a 10-second timer. The timer starts only after the state trigger fires and calls .trigger_timer_1.start.

Note

Timer triggers are useful when you want a delayed action. Similar functionality can also be achieved with automation sequences if you begin to accumulate large trigger chains.

Sensor Interface

The timer sensor tracks elapsed time data. Unlike the trigger, the sensor focuses on time data for you to work with and does not fire actions.

Option	Type	Required	Description
`key`	String	Yes	Unique slug identifier for the component
`duration`	Integer	Yes	Time in seconds before the sensor stops. Default: `10`
`invert_count`	Boolean	No	Set to `true` to count down from duration to 0 instead of up. Default: `false`
`name`	String	No	Friendly display name for the component
`topic`	String	No	Topic to listen for timer events on. Default: `timer/{key}`

Timer Sensor Data

The state returned by the timer sensor:

Timer Sensor Data

{
  "active": false,
  "duration": 0,
  "duration_remaining": 10
}

Sensor Actions

The timer sensor supports the same actions as the trigger: start, stop, pause, reset, and restart.

Timer Sensor Config

{
  "sensor": [
    {
      "interface": "timer",
      "key": "timer_10s",
      "name": "Example 10s Timer",
      "duration": 10,
      "invert_count": false
    }
  ]
}

Tip

Use invert_count to create countdown timers that display the remaining time, which is useful for UI displays showing how long until an action fires.

Previous ← T9602 Extension Next Extending MudPi →