Outcome
Build a dependable local voice assistant flow with wake, intent handling, and fallback behavior.
Audience and Scope
Audience: Home automation builder with intermediate Home Assistant and Docker experience
Estimated Time: 1-4 hours
Difficulty: intermediate
Before You Start
- Home Assistant updated and reachable on local network.
- Microphone/speaker hardware tested.
- Quiet test location available for baseline tuning.
Hardware and Software
Hardware
- Voice endpoint device (satellite or voice assistant hardware).
- Home Assistant voice pipeline components.
- Optional Wyoming services.
Software
- Voice endpoint device (satellite or voice assistant hardware).
- Home Assistant voice pipeline components.
- Optional Wyoming services.
Step-by-Step
Step 1: Enable voice pipeline
Objective: Configure speech-to-text, intent handling, and text-to-speech providers.
Actions:
- Implement enable voice pipeline according to your environment.
Verification:
- Confirm expected state in Home Assistant and logs.
- Run a manual test to verify expected behavior.
Common failure and fix: If recognition fails: reduce ambient noise and retune microphone gain.
Step 2: Register endpoint device
Objective: Add the voice endpoint and confirm it appears online.
Actions:
- Implement register endpoint device according to your environment.
Verification:
- Confirm expected state in Home Assistant and logs.
- Run a manual test to verify expected behavior.
Common failure and fix: If recognition fails: reduce ambient noise and retune microphone gain.
Step 3: Define core intents
Objective: Test commands for lights, climate, and media.
Actions:
- Keep phrasing short and repeatable.
Verification:
- Confirm expected state in Home Assistant and logs.
- Run a manual test to verify expected behavior.
Common failure and fix: If recognition fails: reduce ambient noise and retune microphone gain.
Step 4: Add fallback responses
Objective: Create responses for unknown intents and unavailable entities.
Actions:
- Implement add fallback responses according to your environment.
Verification:
- Confirm expected state in Home Assistant and logs.
- Run a manual test to verify expected behavior.
Common failure and fix: If recognition fails: reduce ambient noise and retune microphone gain.
Step 5: Add reliability checks
Objective: Track latency and failure counts; alert when endpoint disconnects.
Actions:
- Implement add reliability checks according to your environment.
Verification:
- Confirm expected state in Home Assistant and logs.
- Run a manual test to verify expected behavior.
Common failure and fix: If recognition fails: reduce ambient noise and retune microphone gain.
Step 6: Validate user scenarios
Objective: Run a morning/evening command set and verify results end-to-end.
Actions:
- Implement validate user scenarios according to your environment.
Verification:
- Confirm expected state in Home Assistant and logs.
- Run a manual test to verify expected behavior.
Common failure and fix: If recognition fails: reduce ambient noise and retune microphone gain.
Validation Checklist
- Wake and response cycle is consistent.
- Core intents execute correctly.
- Fallback message appears on unknown intent.
Operations and Maintenance
- Document update cadence for packages and containers.
- Schedule backup verification.
- Record service health baselines and alert thresholds.
Troubleshooting and Rollback
- If recognition fails: reduce ambient noise and retune microphone gain.
- If intent misses: simplify phrases and verify entity names/aliases.
- If responses lag: move processing local and reduce model size.