Configuration¶

Customize your Voice Assistant Persistent Timers setup.

Adding New Areas¶

To add a voice assistant in a new area:

1. Create Timer Entity¶

Add to timer_entities.yaml:

living_room:
  name: Living Room Timer
  icon: mdi:timer-outline
  restore: true

2. Add Template Sensor¶

Add to the trigger list in templates.yaml:

- trigger:
    - platform: state
      entity_id:
        - timer.kitchen
        - timer.bedroom
        - timer.living_room # Add this

Then add a new sensor block (copy existing and change area name).

3. Add Input Text Helper¶

Add to input_text_helpers.yaml:

living_room_timer_previous_state:
  name: Living Room Timer Previous State
  max: 16

4. Add Timer Automation¶

Add to automations.yaml:

- alias: "Timer: Living Room Timer Finished"
  id: timer_living_room_finished
  trigger:
    - platform: event
      event_type: timer.finished
      event_data:
        entity_id: timer.living_room
  action:
    - service: esphome.living_room_voice_assistant_timer_finished

5. Update Cross-Device Sentences (Optional)¶

Add to custom_sentences/en/cross_device_timers.yaml:

lists:
  target_location:
    values:
      # ... existing entries ...
      - in: "living room"
        out: "living_room"

And update cross_device_intent_scripts.yaml target_to_area mapping.

Wake Words¶

Wake words allow hands-free activation of your voice assistant. You might want to change the wake word to avoid conflicts with other devices (e.g., if you have an Alexa device), to use something more memorable, or to set up different wake words for different rooms.

For more information, see the Home Assistant Wake Word documentation.

Available Wake Words¶

The following wake word models are available for satellite devices:

Changing Wake Word¶

See the Home Assistant wake word customization guide for detailed instructions. In your satellite device config:

micro_wake_word:
  models:
    - model: hey_jarvis
      id: hey_jarvis

Multiple Wake Words¶

You can configure multiple wake words so different household members can use their preferred phrase, or to provide fallback options if one wake word is less reliable in your environment:

micro_wake_word:
  models:
    - model: okay_nabu
      id: okay_nabu
    - model: hey_jarvis
      id: hey_jarvis

Display Customization¶

Timer Progress Bar Colors¶

Customize the progress bar colors to match your Home Assistant theme, improve visibility for colorblind users, or simply suit your preferences. The default green/blue scheme shows active timers in green and paused timers in blue:

color:
  - id: active_timer_color
    hex: "26ed3a"  # Green - timer counting down

  - id: paused_timer_color
    hex: "3b89e3"  # Blue - timer paused

For a high-contrast scheme:

color:
  - id: active_timer_color
    hex: "FFFF00"  # Yellow - easier to see

  - id: paused_timer_color
    hex: "FF00FF"  # Magenta - distinct from active

Status Messages¶

The LCD display shows time remaining in words (e.g., "Forty-five minutes remaining"). You might want to customize this to show numeric time instead, change the language, or adjust the layout for your display size.

To show numeric countdown instead of words, modify the draw_status_bar script in your device configuration:

script:
  - id: draw_status_bar
    then:
      - lambda: |
          // Numeric format instead of words
          int remaining = (int)id(timer_remaining).state;
          int mins = remaining / 60;
          int secs = remaining % 60;
          char time_str[16];
          snprintf(time_str, sizeof(time_str), "%02d:%02d", mins, secs);
          id(lcd_display).printf(120, 250, id(font_timer), Color::WHITE,
            TextAlign::TOP_CENTER, "%s", time_str);

Images¶

Replace the default casita illustrations with custom images to personalize your device or match your smart home theme. See the Home Assistant customization guide for detailed instructions. The Home Assistant S3 Box Community Illustrations repository contains some sample themed image sets created by the community.

To use custom images, update the substitutions in your device configuration:

substitutions:
  idle_illustration_file: "https://your-server.com/idle.png"
  listening_illustration_file: "https://your-server.com/listening.png"

For faster loading and offline reliability, use local files stored on the device:

substitutions:
  idle_illustration_file: "images/my-idle.png"
  listening_illustration_file: "images/my-listening.png"

Alarm Customization¶

Alarm Sound¶

Replace the default alarm with something more distinctive, gentler for bedrooms, or themed to match your setup (e.g., a kitchen bell for cooking timers). The file must be in FLAC format:

media_player:
  files:
    - id: timer_finished_sound
      file: "https://your-server.com/alarm.flac"

Alarm Duration¶

The alarm rings repeatedly until dismissed or the timeout is reached. Extend the duration if you might be away from the device, or shorten it for environments where prolonged noise is disruptive:

switch:
  - id: timer_ringing
    on_turn_on:
      # ... alarm logic ...
      - delay: 15min  # Default timeout
      - switch.turn_off: timer_ringing

Alarm Volume¶

Control the volume range for announcements and alarms. Lower the maximum for bedrooms or late-night use, or increase the minimum if the alarm needs to be heard over background noise:

media_player:
  volume_min: 0.5  # Minimum volume (50%)
  volume_max: 0.8  # Maximum volume (80%)

Voice Response Customization¶

Custom Speech Responses¶

Customize what the voice assistant says when starting, stopping, or reporting timer status. You might want shorter confirmations, more personality, or responses that match a custom wake word character:

HassStartTimer:
  speech:
    text: >
      {% if not area_id %}
        I couldn't find a timer for this area.
      {% else %}
        Timer set for {{ m }} minute{{ 's' if m != 1 }}.
      {% endif %}

For a more conversational response:

HassStartTimer:
  speech:
    text: >
      {% if not area_id %}
        Sorry, I don't know which timer to use here.
      {% else %}
        Got it! I'll let you know in {{ m }} minute{{ 's' if m != 1 }}.
      {% endif %}

Language¶

For non-English setups, you may need to create custom sentence definitions and speech responses in your language:

1. Create custom sentences in custom_sentences/<lang>/ (e.g., custom_sentences/de/ for German)
2. Define sentence patterns that match your language's grammar
3. Adjust intent script speech responses to use your language

See the Home Assistant custom sentences documentation for detailed instructions on multi-language support.

Advanced Configuration¶

Sync Intervals¶

The device periodically checks Home Assistant sensor state to ensure the display stays synchronized, even if a sensor update is missed. Increase the interval to reduce API traffic, or decrease it for more responsive updates:

interval:
  - interval: 30s  # General sync - catches missed updates
    then:
      # ...

  - interval: 1s   # Fast update in final minute for accuracy
    then:
      # ...

API Services¶

Add custom ESPHome services that can be called from Home Assistant automations. This is useful for integrating timer events with other smart home actions, such as flashing lights when a timer finishes:

api:
  services:
    - service: flash_warning
      then:
        - light.turn_on:
            id: status_ring
            effect: "Pulse Fast"
            red: 100%
        - delay: 5s
        - light.turn_off: status_ring

Performance Tuning¶

Reduce Display Updates¶

If you notice display flickering, excessive log messages, or the device becoming unresponsive during long timers, reduce the sync frequency. This setting is in your ESPHome device configuration file (e.g., esp32-s3-box-3-voice-assistant.yaml), in the interval: section:

interval:
  - interval: 60s  # Less frequent sync checks (default: 30s)
    then:
      - lambda: |-
          // Sync check logic

Sensor Update Frequency¶

Template sensors in Home Assistant update every second by default, which ensures accurate countdown displays. For very long timers (hours) where second-level precision isn't needed, reduce Home Assistant's processing load by updating less frequently.

In your Home Assistant templates.yaml file, modify the trigger:

- trigger:
    - platform: time_pattern
      seconds: "/5"  # Update every 5 seconds instead of every second

Backup and Restore¶

Export Configuration¶

# Backup HA config files
tar -czf timer-backup.tar.gz \
  timer_entities.yaml \
  templates.yaml \
  intent_scripts.yaml \
  automations.yaml \
  custom_sentences/

Timer State Persistence¶

Timer state is stored by HA with restore: true. After HA restart:

• Active timers resume where they left off
• Paused timers remain paused
• Completed timers stay idle

Next Steps¶

• Cross-Device Control - Multi-device timer commands
• Troubleshooting - Fix common issues