Timer

The timer extension works with the python time library to offer a sensor and trigger interface around elapsed time. This extension uses the perf_counter() in particular to provide more accurate results when using shorter durations and better estimations of actual elapsed time.

This extension does not take an extension level config and is focused on interfaces.

Trigger Interface

The timer extension provides a trigger that will fire actions after a set duration. The timer needs to be started and then will call any actions assigned to it once it has reached the set duration.

Trigger Actions

There are several actions that have been made available in order to interact with trigger timers. To make a timer trigger active you need to call the start action. This is commonly done from another trigger or by an event call. Below are the actions available:

Trigger Subscribed Events

The other way to interact with the timer is through events. The timer listens for events that correspond to its available actions so you can also interact with timers through the event system. The timer will listen for TimerStart, TimerStop, TimerPause, TimerReset and TimerRestart events.

The timer listens for these events on the configured topic. The topic by default is based on the key and follows the format: timer/{key}.

Using Timer Triggers

A timer trigger is a little different from other triggers. A timer needs to be started by being set to active before it will begin a count. You can do this by using the actions described above or by sending one of the events it is listening for. The most common method is to use another trigger that will start a timer trigger.

Timer triggers are useful when you want a trigger that would fire an action but after a delay before it fires. There are a variety of use cases for timer based triggers and its up to you to choose what fits your needs best. It is important to note similar functionality can also be achieved with automation sequences if you begin to accumulate large trigger chains.

Config Examples

Here is a config of a timer trigger that gets started by a state trigger.

"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"
    ]
}]

The configuration above would turn_on a toggle with a key of example_toggle after a duration of 10 seconds. This timer only starts after the state trigger fires and calls the .trigger_timer_1.start action. This state trigger is just checking an example value for demo purposes.

Sensor Interface

The timer extension also provides a sensor interface that is useful in case you want to work with the elapsed time data. The timer sensor works very similar to the trigger and will track time until a set duration once it has been started. The main difference between the trigger and sensor is the sensor focuses on the time data for you to work with. Sensors also do not fire actions.

Timer Sensor Data

The state available from the timer sensor contains a dict with the following keys:

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

When active is set to True the timer will count up from 0 until it hits the duration set in configuration. If invert_count is set to True the timer will start at the max duration and count down to 0.

Sensor Actions

There are several actions that have been made available in order to interact with sensor timers. To make a timer sensor active you need to call the start action. This is commonly done from a trigger or by an event call. Below are the actions available:

Config Examples

Here is a config of a timer sensor counts from 0 to 10 when started.

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