Skip to content

Installation Guide

Step-by-step instructions for setting up Voice Assistant Persistent Timers.

Overview

Installation has three main phases:

  1. Home Assistant Configuration - Timer entities, sensors, intent scripts
  2. ESPHome Configuration - Device config with timer packages
  3. Testing - Verify everything works together

Phase 1: Home Assistant Configuration

Step 1.1: Create Timer Entities

Download timer_entities.yaml to your HA config directory.

Add to configuration.yaml:

timer: !include timer_entities.yaml

Edit timer_entities.yaml to match your areas:

kitchen:
  name: Kitchen Timer
  icon: mdi:timer-outline
  restore: true

bedroom:
  name: Bedroom Timer
  icon: mdi:timer-outline
  restore: true

# Add more areas as needed

Step 1.2: Create Template Sensors

Download templates.yaml to your HA config directory.

Add to configuration.yaml:

template: !include templates.yaml

The template sensors calculate remaining time, progress, and state for each timer.

Important: Update the trigger entity list if you add new areas:

- trigger:
    - platform: state
      entity_id:
        - timer.kitchen
        - timer.bedroom
        - timer.playroom
        # Add your timers here

Step 1.3: Create Input Text Helpers

Download input_text_helpers.yaml to your HA config directory.

Add to configuration.yaml:

input_text: !include input_text_helpers.yaml

These helpers store timer state for the speech response blocks.

Step 1.4: Create Intent Scripts

Download intent_scripts.yaml to your HA config directory.

Add to configuration.yaml:

intent_script: !include intent_scripts.yaml

These scripts intercept standard timer voice commands and route them to HA timer entities.

Step 1.5: Create Automations

Download automations.yaml or add the automations manually.

Required: Timer Finished automation for each area:

- alias: "Timer: Kitchen Timer Finished"
  trigger:
    - platform: event
      event_type: timer.finished
      event_data:
        entity_id: timer.kitchen
  action:
    - service: esphome.kitchen_voice_assistant_timer_finished

Replace kitchen_voice_assistant with your ESPHome device name.

Step 1.6: Add Custom Sentences (Optional)

For restart and cross-device commands, download the custom sentence files to your HA config directory:

Place them in config/custom_sentences/en/ (create the directory if needed).

Step 1.7: Restart Home Assistant

Restart HA to load all new configuration:

# From HA terminal or SSH
ha core restart

Step 1.8: Verify HA Configuration

Check these entities exist:

  • timer.kitchen (or your area)
  • sensor.kitchen_timer_remaining_seconds
  • input_text.kitchen_timer_previous_state

Test timer manually:

# Developer Tools → Services
service: timer.start
data:
  entity_id: timer.kitchen
  duration: "00:01:00"

Phase 2: ESPHome Configuration

Step 2.1: Choose Your Device

Select a configuration from docs/devices/:

Step 2.2: Extract Configuration

If using literate docs, run the extraction script:

cd voice-assistant-persistent-timers
python3 scripts/extract_configs.py

Or copy the configuration sections manually from the device documentation.

Step 2.3: Configure Substitutions

Set the timer_area to match your HA area:

substitutions:
  timer_area: "kitchen"

Step 2.4: Configure Secrets

Ensure your secrets.yaml has the following required values:

wifi_ssid: "YourWiFiNetwork"
wifi_password: "YourWiFiPassword"
ntp_servers:
  - "0.au.pool.ntp.org"
  - "1.au.pool.ntp.org"
  - "2.au.pool.ntp.org"
timezone: "America/New_York" # Your timezone

Step 2.5: Validate Configuration

esphome config esphome/examples/esp32-s3-box-3-voice-assistant.yaml

Step 2.6: Flash Device

esphome run esphome/examples/esp32-s3-box-3-voice-assistant.yaml

Step 2.7: Assign to Area

After the device connects:

  1. Go to Settings → Devices & Services → ESPHome
  2. Find your device
  3. Assign it to the correct area

Phase 3: Testing

Basic Timer Test

  1. Start timer: Say "Okay Nabu, set a timer for 1 minute"
  2. Check display: Progress bar should appear
  3. Query status: Say "How much time is left?"
  4. Wait for completion: Alarm should sound
  5. Dismiss alarm: Touch screen or say "Stop"

Pause/Resume Test

  1. Start a 2-minute timer
  2. Say "Pause the timer"
  3. Verify display shows "paused"
  4. Say "Resume the timer"
  5. Verify countdown continues

Cancel Test

  1. Start a timer
  2. Say "Cancel the timer"
  3. Verify display returns to idle

Persistence Test

  1. Start a 5-minute timer
  2. Restart the ESPHome device (power cycle or click reboot link)
  3. After reconnection, timer should still be running
  4. Display should show current remaining time

Cross-Device Test (Optional)

If you have multiple voice assistants with custom sentences:

  1. From bedroom, say "Start the kitchen timer for 2 minutes"
  2. Verify kitchen timer starts
  3. From bedroom, say "Cancel the kitchen timer"

Troubleshooting

Timer doesn't start

  • Check intent_scripts.yaml is loaded
  • Verify device is assigned to an area
  • Check HA logs for intent errors

Display doesn't update

  • Check sensor subscription in ESPHome logs
  • Verify template sensor exists
  • Check sensor attribute names match

Alarm doesn't sound

  • Check automation is triggered (HA logs)
  • Verify API service name matches device
  • Check media_player component

"Timers not supported"

  • Add voice_assistant timer event stubs
  • Reflash device

See Troubleshooting for more solutions.

Next Steps