Voice Assistant Persistent Timers¶

Welcome to the Voice Assistant Persistent Timers project! This guide helps you set up voice assistant timers that survive device restarts, are visible in Home Assistant, and can be controlled from multiple devices.

The Problem¶

By default, the Home Assistant Voice Assistant integration creates timers that are stored on the satellite device's memory. If your device restarts, loses WiFi, or crashes, your timer is gone. You also can't:

See timer status in Home Assistant
Control timers from other devices
Use timers in automations

The Solution¶

This project moves timer state management to Home Assistant:

flowchart LR
    VA[Voice Assistant<br/>Satellite]
    HA[Home Assistant<br/>Timer Entity<br/>State Store]

    VA -->|Voice Command| HA
    HA -->|Sensor Updates| VA

Benefits:

✅ Persistent - Timers survive device restarts
✅ Visible - See timers in HA dashboards
✅ Multi-device - Control from any voice assistant
✅ Automatable - Use in HA automations and scripts
✅ Visual - Progress bars and countdown displays

Quick Start¶

1. Home Assistant Setup¶

Add timer entities for each voice assistant area:

# timer_entities.yaml
kitchen:
  name: Kitchen Timer
  icon: mdi:timer-outline
  restore: true

2. Satellite Device Configuration¶

Set the timer_area substitution to match your HA area:

substitutions:
  timer_area: "kitchen"

3. Voice Commands¶

Command	Result
"Set a timer for 5 minutes"	Starts timer in current area
"How much time is left?"	Reports remaining time
"Pause the timer"	Pauses countdown
"Cancel the timer"	Stops and resets timer

Tested Hardware Configurations¶

Device	Display	Features
ESP32-S3-BOX-3	320x240 LCD + Touch	Progress bar, countdown widget
ESP32-S3 Touch-LCD 1.83"	240x284 LCD + Touch	Progress bar, orientation detection
ESP32-S3-AUDIO-Board	7 LEDs (Optional LCD)	Progress bar, LED ring progress

Documentation¶

Architecture - How it works under the hood
Prerequisites - What you need before starting
Installation - Step-by-step setup guide
Configuration - Customization options
Cross-Device Control - Multi-device timer commands
Troubleshooting - Common issues and solutions
Contributing - How to help improve this project

Key Concepts¶

Area-Based Routing¶

Timers are routed based on the voice assistant's area in Home Assistant:

flowchart TB
    VA["Voice Assistant in<br/><b>kitchen</b> area"]
    Timer["timer.kitchen"]
    Sensor["sensor.kitchen_timer_remaining_seconds"]

    VA -->|Commands| Timer
    Timer -->|State| Sensor
    Sensor -->|Display| VA

No manual device mapping required!

Entity Naming Convention¶

Area	Timer	Sensor	Helper
`bedroom`	`timer.bedroom`	`sensor.bedroom_timer_remaining_seconds`	`input_text.bedroom_timer_previous_state`
`kitchen`	`timer.kitchen`	`sensor.kitchen_timer_remaining_seconds`	`input_text.kitchen_timer_previous_state`
`playroom`	`timer.playroom`	`sensor.playroom_timer_remaining_seconds`	`input_text.playroom_timer_previous_state`