Skip to content

timers.md

Latest commit

 

History

History
126 lines (95 loc) · 8.01 KB

timers.md

File metadata and controls

126 lines (95 loc) · 8.01 KB
Raw

Timers

Voice Satellite hooks into Home Assistant's standard timer intent system, so timers behave the same whether they're started by voice, by a dashboard button, or from an automation. The countdown pill, alert chime, and cancel paths are all shared.

Contents

How timers work

Each satellite registers itself with Home Assistant's timer manager when it loads. Anything that creates a timer with that satellite's device_id as context (the voice pipeline, the voice_satellite.start_timer action, an LLM tool that targets the device, or any future caller of HA's TimerManager.start_timer) gets routed to that satellite's overlay.

What you see on the satellite:

  1. Countdown pill appears at the top of the overlay as soon as the timer is created. The pill shows the remaining time and animates a progress bar. Pausing a timer freezes its countdown until it is resumed. Multiple timers stack independently.
  2. Alert fires when the timer reaches zero: a centered alert pill flashes, the alert chime loops (silent while Mute timers is on), and the timer name (if any) is shown below the pill in the skin's assistant text style. The wake-word stop interrupter is enabled while the alert is active so you can say the stop keyword to dismiss it ("stop" on microWakeWord and openWakeWord, "ok stop" on vsWakeWord - see Stop Word Interruption).
  3. Optional spoken alert phrase can be enabled from the side panel. When enabled, the alert repeats as chime -> chime -> phrase -> short pause until dismissed. The next chime pair starts about 500 ms after the phrase ends. The phrase is synthesized with the same Assist pipeline that created the timer, so dual-pipeline setups keep the expected language and voice.
  4. Cleanup happens only when dismissed (double-tap or the stop keyword). Timer alerts do not auto-dismiss; the alert chime keeps looping until you dismiss it.

Pill appearance is controlled by the active skin. Both pill rendering and the timer-name label can be hidden in the side panel without affecting timer behavior, see Side panel options.

Voice control

These all work out of the box with the built-in Home Assistant conversation agent (and most LLM agents, since HassStartTimer / HassCancelTimer are standard HA intents):

Sentence Effect
"Set a 5 minute timer" Starts an unnamed 5 minute timer
"Set a pizza timer for 10 minutes" Starts a 10 minute timer named pizza
"Start a 1 hour 30 minute timer" Combined hours + minutes
"How much time is left on the pizza timer?" Reads the remaining time
"Add 5 minutes to the pizza timer" Extends the timer
"Cancel the pizza timer" Cancels by name
"Cancel all timers" Clears every active timer
"stop" or "ok stop" (during alert) Dismisses the alert (requires Stop word interruption switch on the device). The exact phrase depends on the active wake-word engine - see Stop Word Interruption

Starting a timer from an automation

The voice_satellite.start_timer action creates a timer on a satellite without a voice command. The result is identical to a voice-created timer.

action: voice_satellite.start_timer
target:
  entity_id: assist_satellite.kitchen_tablet
data:
  name: Stir the sauce
  minutes: 5
Field Required Description
name yes Label saved on the timer. Used by voice cancellation ("cancel the stir the sauce timer") and by automations reading active_timers. Hidden from the on-screen pill by design, shown below the alert when the timer fires
hours no Hours portion of the duration (0-168)
minutes no Minutes portion (0-59)
seconds no Seconds portion (0-59)

At least one of hours / minutes / seconds must be non-zero.

Example: cooking reminders

A common pattern: stage several reminders for a recipe.

alias: Sauce reminders
sequence:
  - action: voice_satellite.start_timer
    target:
      entity_id: assist_satellite.kitchen_tablet
    data:
      name: Stir the sauce
      minutes: 5
  - action: voice_satellite.start_timer
    target:
      entity_id: assist_satellite.kitchen_tablet
    data:
      name: Add herbs
      minutes: 12
  - action: voice_satellite.start_timer
    target:
      entity_id: assist_satellite.kitchen_tablet
    data:
      name: Sauce ready
      minutes: 25

All three pills appear immediately and tick down independently.

Cancelling and reading state

  • From the satellite UI: double-tap the countdown pill (or the alert pill once it fires).
  • By voice: "Cancel the X timer" or "Cancel all timers".

The satellite entity exposes timer state for templates and triggers:

Attribute Type Description
active_timers list Running and paused timer objects, each with id, name, total_seconds, started_at, is_active, start_hours, start_minutes, start_seconds, and pipeline_id
last_timer_event string Last event type: started, updated, cancelled, or finished

Each timer's is_active is true while running and false while paused. For a running timer, calculate remaining seconds as max(0, total_seconds - (now - started_at)), where now and started_at are Unix timestamps in seconds. For a paused timer, use total_seconds directly without subtracting elapsed time. Pause, resume, and duration changes all produce an updated event and refresh total_seconds and started_at; the start_* fields retain the original requested duration. Consumers supporting older integration versions can treat a missing is_active as true.

Example template, true when the kitchen tablet has at least one running or paused timer:

{{ state_attr('assist_satellite.kitchen_tablet', 'active_timers') | length > 0 }}

Side panel options

Per-browser toggles under Advanced > Timers in the sidebar panel:

Setting Default Effect
Hide on-screen countdown Off Suppresses the countdown pill while the timer is running. The timer still fires and the alert still plays at zero. Useful for tablets that double as a wall display where pills feel intrusive
Show timer name inside pill On Renders the timer name alongside the countdown, e.g. ⏱ Stir the sauce | 15:30. Names longer than 25 characters are truncated with .... Unnamed timers always render as time-only
Hide timer name on alert Off When a timer finishes, hides the timer name shown below the alert. The icon, time, and chime still appear
Mute timers Off Silences the looping alert chime and the spoken alert phrase. The alert still appears and still waits to be dismissed. This toggle mirrors the device's Mute timers switch, which is the source of truth: flipping either one updates the other, and changing it during a ringing alert silences or restores the sound immediately. Useful for bedrooms and nurseries, where the whole device shouldn't be muted
Speak timer alert phrase Off Adds a spoken phrase after every two alert chimes, then starts the next chime pair after a short pause. Enabling this reveals the phrase fields below
Timer alert phrase Your timer is up. Phrase for unnamed timers. Translate this to the language you use with this satellite
Named timer alert phrase Your %%TIMER_NAME%% timer is up. Phrase for named timers. %%TIMER_NAME%% is replaced with the timer name when the alert fires

These settings are stored in the selected satellite's panel profile, except Mute timers, which lives on the device as a switch entity so automations can drive it (see integration.md). Toggling any of them takes effect live without restarting the engine.