Prerequisites¶

Before setting up persistent timers, ensure your environment meets these requirements.

Home Assistant¶

Version¶

Home Assistant 2024.1.0 or newer
Recommended: Latest stable release

Required Components¶

Assist pipeline configured and working
ESPHome integration installed
Areas configured for each voice assistant location

Area Setup¶

Each voice assistant device must be assigned to an area. The area ID becomes the basis for all entity names.

Go to Settings → Devices & Services → ESPHome
Select your voice assistant device
Click Device info
Assign to an area (e.g., "Kitchen", "Bedroom", "Playroom")

Important: Area IDs are lowercase with underscores. "My Bedroom" becomes my_bedroom.

Naming Conventions¶

For this system to work, entity names must follow this pattern:

Component	Pattern	Example
Timer	`timer.<area_id>`	`timer.kitchen`
Remaining Sensor	`sensor.<area_id>_timer_remaining_seconds`	`sensor.kitchen_timer_remaining_seconds`
State Helper	`input_text.<area_id>_timer_previous_state`	`input_text.kitchen_timer_previous_state`
Ringing Switch	`switch.<area_id>_voice_assistant_timer_ringing`	`switch.kitchen_voice_assistant_timer_ringing`

Satellite Devices¶

ESPHome Version¶

ESPHome 2025.5.0 or newer
ESP-IDF framework required for ESP32-S3 devices

Device Requirements¶

ESP32-S3 with PSRAM (for wake word detection)
Audio: Microphone + Speaker
Display: LCD or LED ring (optional but recommended)
Alternative display options:
WLED progress bar: wled-timer-progress.md
HUB75 LED matrix: hub75-timer-display.md
LCD Timer Panel: lcd-touch-timer-panel.md

Network¶

WiFi¶

Stable 2.4GHz WiFi connection
Device must reach Home Assistant API
Recommended: Static IP or DHCP reservation

API Connection¶

ESPHome API must be enabled (default)
API encryption recommended for security

File Structure¶

Your Home Assistant config directory should support these files:

config/
├── configuration.yaml      # Main config (add includes)
├── timer_entities.yaml     # Timer definitions
├── templates.yaml          # Sensor templates
├── input_text_helpers.yaml # State helpers
├── intent_scripts.yaml     # Voice command routing
├── automations.yaml        # Timer event automations
└── custom_sentences/
    └── en/
        ├── local_timer_overrides.yaml
        └── cross_device_timers.yaml

Verification Checklist¶

Before proceeding to installation:

Home Assistant is running and accessible
ESPHome integration is installed
Voice assistant device is connected to HA
Device is assigned to an area
Assist pipeline is configured
You can say "What time is it?" and get a response
You have file access to HA config directory

Common Issues¶

"Device not assigned to an area"¶

The preferred_area_id variable won't be set if the device isn't in an area.

Fix: Assign the device to an area in Home Assistant.

"Entity not found"¶

Entity names must match exactly. Check for:

Correct area ID spelling
Underscores instead of spaces
Lowercase letters

"Timers not supported on this device"¶

The satellite device config needs voice_assistant timer event stubs.

Fix: Add the timer event handlers (see Installation guide).

Next Steps¶

Once prerequisites are met, proceed to Installation.