Troubleshooting¶

Common issues and their solutions.

Voice Commands¶

"Timers are not supported on this device"¶

Cause: The Home Assistant Voice Assistant integration requires timer event handlers on satellite devices.

Solution: Add timer event stubs to your satellite device config:

voice_assistant:
  on_timer_started:
    - logger.log: "Timer started (handled by HA)"
  on_timer_finished:
    - logger.log: "Timer finished (handled by HA)"
  on_timer_cancelled:
    - logger.log: "Timer cancelled (handled by HA)"
  on_timer_updated:
    - logger.log: "Timer updated (handled by HA)"
  on_timer_tick:
    - lambda: return;

"I couldn't determine which timer to start"¶

Cause: Device not assigned to an area, or preferred_area_id not passed.

Solutions: 1. Assign device to an area in HA 2. Check that the area ID matches your timer entity name 3. Verify intent_scripts.yaml is loaded

Timer starts but nothing happens¶

Cause: Timer entity doesn't exist or name mismatch.

Verify:

# Developer Tools → States
# Search for: timer.
# Should see: timer.kitchen, timer.bedroom, etc.

"Sorry, I couldn't understand that"¶

Cause: Wake word or speech recognition issue.

Solutions: 1. Speak clearly after wake word trigger sound 2. Wait for the "listening" state indicator 3. Check microphone gain settings 4. Try rephrasing the command

Display Issues¶

Display doesn't show timer progress¶

Cause: Sensor subscription not working.

Check ESPHome logs:

[homeassistant.sensor:INFO]: 'sensor.kitchen_timer_remaining_seconds': Got state 300.00

Solutions: 1. Verify template sensor exists in HA 2. Check entity_id matches in ESPHome config 3. Ensure draw_display script is called on sensor change

Display shows 0 when timer is running¶

Cause: Sensor not updating or wrong attribute.

Verify in HA:

# Developer Tools → States
# Entity: sensor.kitchen_timer_remaining_seconds
# State: Should show remaining seconds
# Attributes: duration_seconds, timer_state, progress_percent

Display stuck on previous state¶

Cause: draw_display not triggered.

Solutions: 1. Check interval sync is running 2. Verify voice_assistant_phase is updating 3. Check for display update errors in logs

Alarm Issues¶

Alarm doesn't sound when timer finishes¶

Cause: Automation not triggering or API service name wrong.

Check automation: 1. Go to Settings → Automations 2. Find "Timer: Kitchen Timer Finished" 3. Check "Last triggered" timestamp 4. View execution trace

Verify service name:

# The service name must match your ESPHome device
service: esphome.kitchen_voice_assistant_timer_finished
# Format: esphome.<device_name>_timer_finished

Alarm plays but won't stop¶

Cause: timer_ringing switch not turning off.

Solutions: 1. Touch the screen 2. Say "Stop" or "Cancel" 3. Call esphome.<device>_stop_alarm service 4. Toggle the switch in HA UI

Alarm sound is distorted or quiet¶

Cause: Audio settings or file format issue.

Solutions: 1. Check volume_min/volume_max settings 2. Verify speaker enable GPIO is on 3. Try different audio file format (FLAC recommended)

Connection Issues¶

Device disconnects frequently¶

Cause: WiFi or API connection unstable.

Solutions: 1. Check WiFi signal strength (sensor.wifi_signal_db) 2. Use static IP or DHCP reservation 3. Move closer to access point 4. Check for interference

Timer state lost after disconnect¶

Cause: Timer state is in HA, not device. This is expected behavior.

Note: When device reconnects, it subscribes to HA sensor and display updates.

"Entity not available"¶

Cause: HA or satellite device not fully loaded.

Solutions: 1. Wait for HA to finish starting 2. Check satellite device is online 3. Verify API connection

Template Sensor Issues¶

Sensor shows "unavailable"¶

Cause: Timer entity doesn't exist or template error.

Debug:

# Developer Tools → Template
{% set timer = states.timer.kitchen %}
{{ timer.state }}
{{ timer.attributes.finishes_at }}

Remaining time shows negative¶

Cause: Clock sync issue between HA and device.

Solutions: 1. Verify NTP is configured 2. Check timezone settings 3. Restart HA time component

Progress shows 0% or 100% only¶

Cause: Duration not calculated correctly.

Check template:

# Verify duration_seconds attribute is populated
{{ state_attr('sensor.kitchen_timer_remaining_seconds', 'duration_seconds') }}

Intent Script Issues¶

Intent not matching¶

Cause: Custom sentences not loaded or syntax error.

Verify:

# Check for YAML errors
yamllint custom_sentences/en/*.yaml

Check HA logs for intent loading errors.

Speech response is empty¶

Cause: Template error in speech block.

Debug:

# Developer Tools → Template
{% set area_id = 'kitchen' %}
{% set timer = states.timer[area_id] %}
{{ timer.state }}

Wrong timer controlled¶

Cause: Area routing mismatch.

Verify: 1. Device is in correct area in HA 2. preferred_area_id matches timer entity name 3. No typos in area_id substitution

Satellite Device Build Issues¶

"Package not found"¶

Cause: Package path incorrect.

Check:

packages:
  timer_base: !include packages/timer_base.yaml
  # Path relative to your device config file

"Undefined substitution"¶

Cause: Missing required substitution.

Add required values:

substitutions:
  timer_area: "kitchen"
  voice_assist_idle_phase_id: "1"
  # etc.

Compile errors¶

Cause: Syntax or component configuration error.

Run validation:

esphome config your-device.yaml

Getting More Help¶

Enable Debug Logging¶

ESPHome:

logger:
  level: DEBUG

Home Assistant:

# configuration.yaml
logger:
  default: info
  logs:
    homeassistant.components.intent_script: debug
    homeassistant.components.timer: debug

Collect Information¶

When reporting issues, include:

Satellite device logs (around the error)
Home Assistant logs
Device and HA versions
Timer entity state
Sensor attribute values

Report Issues¶

File issues at the project repository with: - Steps to reproduce - Expected vs actual behavior - Log excerpts - Configuration snippets (without secrets)