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.

OptionTypeRequiredDescription
key[String]YesUnique slug id for the component
duration[Integer]YesThe time in seconds before actions are fired. Default: 10
frequency[String]NoIf set to once the trigger will not restart when start is called while already active. Set to many to enable trigger reset on multiple start calls. Options: once, many. Default: once
name[String]NoFriendly display name of component. Useful for UI.
actions[List]NoList of registered actions to fire.
topic[String]NoTopic to listen for timer events on. Default: timer/{key}

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:

ActionDescription
startStarts the timer if it is not active. If the timer is already active then it does nothing unless frequency is set to many in which case it restarts the timer.
stopWill immediately stop the timer and reset it
pausePauses the timer by setting active to false. It does not reset the duration.
resetResets the timer to the beginning without changing the active state
restartResets the timer to the beginning and sets trigger to active.

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

EventTimer Response
TimerStartStarts the timer if it is not active. If the timer is already active then it does nothing unless frequency is set to many in which case it restarts the timer.
TimerStopWill immediately stop the timer and reset it
TimerPausePauses the timer by setting active to false. It does not reset the duration.
TimerResetResets the timer to the beginning without changing the active state
TimerRestartResets the timer to the beginning and sets trigger to active.

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.

OptionTypeRequiredDescription
key[String]YesUnique slug id for the component
duration[Integer]YesThe time in seconds before sensor stops Default: 10
invert_count[Boolean]NoIf set to true the sensor will count down to 0 rather than up from 0. Default: false
name[String]NoFriendly display name of component. Useful for UI.
topic[String]NoTopic to listen for timer events on. Default: timer/{key}

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:

ActionDescription
startStarts the timer if it is not active. If the timer is already active then it does nothing unless frequency is set to many in which case it restarts the timer.
stopWill immediately stop the timer and reset it
pausePauses the timer by setting active to false. It does not reset the duration.
resetResets the timer to the beginning without changing the active state
restartResets the timer to the beginning and sets trigger to active.

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