feat: OpenClaw HTTP bridge, HA conversation agent fixes, voice pipeline tooling
- Add openclaw-http-bridge.py: HTTP server translating POST requests to OpenClaw CLI calls - Add launchd plist for HTTP bridge (port 8081, auto-start) - Add install-to-docker-ha.sh: deploy custom component to Docker HA via SSH - Add package-for-ha.sh: create distributable tarball of custom component - Add test-services.sh: comprehensive voice pipeline service checker Fixes from code review: - Use OpenClawAgent (HTTP) in async_setup_entry instead of OpenClawCLIAgent (CLI agent fails inside Docker HA where openclaw binary doesn't exist) - Update all port references from 8080 to 8081 (HTTP bridge port) - Remove overly permissive CORS headers from HTTP bridge - Fix zombie process leak: kill child process on CLI timeout - Remove unused subprocess import in conversation.py - Add version field to Kokoro TTS Wyoming info - Update TODO.md with voice pipeline progress
This commit is contained in:
Aodhan Collins
195
homeai-voice/WYOMING_SATELLITE_SETUP.md
Normal file
195
homeai-voice/WYOMING_SATELLITE_SETUP.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Wyoming Satellite Setup Guide
|
||||
|
||||
> How to configure the Wyoming Satellite wizard in Home Assistant
|
||||
|
||||
---
|
||||
|
||||
## When Adding Wyoming Satellite Integration
|
||||
|
||||
When you add the Wyoming Satellite integration, Home Assistant will open a wizard to configure a voice assistant. Here's what to do:
|
||||
|
||||
---
|
||||
|
||||
## Option 1: Skip Wizard and Configure Later (Recommended)
|
||||
|
||||
**Best approach if you haven't created the OpenClaw pipeline yet:**
|
||||
|
||||
1. **Skip/Cancel the wizard** - just add the satellite integration without configuring the pipeline
|
||||
2. The satellite will be added but not assigned to a pipeline yet
|
||||
3. Continue with creating the voice assistant pipeline (see below)
|
||||
4. Come back and assign the satellite to the pipeline later
|
||||
|
||||
---
|
||||
|
||||
## Option 2: Use Default Pipeline Temporarily
|
||||
|
||||
**If you want to test the satellite immediately:**
|
||||
|
||||
1. In the wizard, select **"Home Assistant"** as the pipeline (default)
|
||||
2. This will use HA's built-in conversation agent (not OpenClaw)
|
||||
3. You can test basic commands like "What time is it?"
|
||||
4. Later, switch to the OpenClaw pipeline once it's created
|
||||
|
||||
---
|
||||
|
||||
## Creating the Voice Assistant Pipeline
|
||||
|
||||
**Do this BEFORE configuring the satellite (or after if you used Option 2):**
|
||||
|
||||
### Step 1: Create the Pipeline
|
||||
|
||||
1. Go to **Settings → Voice Assistants**
|
||||
2. Click **Add Assistant**
|
||||
3. Configure:
|
||||
- **Name**: `HomeAI with OpenClaw`
|
||||
- **Language**: `English`
|
||||
- **Speech-to-Text**: Select `Mac Mini STT` (Wyoming)
|
||||
- **Conversation Agent**: Select `OpenClaw Conversation`
|
||||
- **Text-to-Speech**: Select `Mac Mini TTS` (Wyoming)
|
||||
4. Click **Create**
|
||||
|
||||
### Step 2: Set as Preferred (Optional)
|
||||
|
||||
1. In the Voice Assistants list, find "HomeAI with OpenClaw"
|
||||
2. Click the three dots (⋮)
|
||||
3. Select **Set as preferred**
|
||||
|
||||
This makes it the default pipeline for all new satellites.
|
||||
|
||||
---
|
||||
|
||||
## Assigning Satellite to Pipeline
|
||||
|
||||
### If You Skipped the Wizard
|
||||
|
||||
1. Go to **Settings → Devices & Services**
|
||||
2. Find **Wyoming Protocol** (the satellite entry)
|
||||
3. Click **Configure**
|
||||
4. Select **Pipeline**: `HomeAI with OpenClaw`
|
||||
5. Click **Submit**
|
||||
|
||||
### If You Used the Default Pipeline
|
||||
|
||||
1. Go to **Settings → Devices & Services**
|
||||
2. Find **Wyoming Protocol** (the satellite entry)
|
||||
3. Click **Configure**
|
||||
4. Change **Pipeline** from "Home Assistant" to `HomeAI with OpenClaw`
|
||||
5. Click **Submit**
|
||||
|
||||
---
|
||||
|
||||
## Satellite Configuration Details
|
||||
|
||||
The wizard may ask for these details:
|
||||
|
||||
| Field | Value | Notes |
|
||||
|-------|-------|-------|
|
||||
| **Name** | `Mac Mini Living Room` | Or any name you prefer |
|
||||
| **Pipeline** | `HomeAI with OpenClaw` | Select after creating it |
|
||||
| **Wake Word** | `hey_jarvis` | Should be auto-detected |
|
||||
| **Audio Input** | Default | Detected from satellite |
|
||||
| **Audio Output** | Default | Detected from satellite |
|
||||
|
||||
---
|
||||
|
||||
## Complete Voice Pipeline Flow
|
||||
|
||||
Once configured, the flow will be:
|
||||
|
||||
```
|
||||
1. Say "Hey Jarvis" → Wake word detected by satellite
|
||||
2. Satellite captures audio → Sends to Wyoming STT (10.0.0.101:10300)
|
||||
3. STT transcribes → Sends text to HA Voice Pipeline
|
||||
4. HA routes to OpenClaw Conversation agent
|
||||
5. OpenClaw processes → Calls Ollama LLM + skills
|
||||
6. Response generated → Sent to Wyoming TTS (10.0.0.101:10301)
|
||||
7. TTS generates audio → Sent back to satellite
|
||||
8. Satellite plays audio → You hear the response
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing the Pipeline
|
||||
|
||||
### Test 1: Via HA Assist (No Wake Word)
|
||||
|
||||
1. Open Home Assistant UI
|
||||
2. Click the **Assist** icon (microphone) in top-right
|
||||
3. Type: `"What time is it?"`
|
||||
4. Press Enter
|
||||
5. **Expected**: You should hear a spoken response via TTS
|
||||
|
||||
### Test 2: Via Satellite (With Wake Word)
|
||||
|
||||
1. Say: **"Hey Jarvis"**
|
||||
2. Wait for acknowledgment beep
|
||||
3. Say: **"What time is it?"**
|
||||
4. **Expected**: You should hear a spoken response
|
||||
|
||||
### Test 3: Home Control
|
||||
|
||||
1. Say: **"Hey Jarvis"**
|
||||
2. Say: **"Turn on the reading lamp"**
|
||||
3. **Expected**:
|
||||
- Light turns on
|
||||
- You hear confirmation: "I've turned on the reading lamp"
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Satellite Not Responding
|
||||
|
||||
1. **Check satellite is online**:
|
||||
- Settings → Devices & Services → Wyoming Protocol
|
||||
- Should show "Connected"
|
||||
|
||||
2. **Check pipeline is assigned**:
|
||||
- Configure satellite → Verify pipeline is set
|
||||
|
||||
3. **Check satellite logs** on Mac Mini:
|
||||
```bash
|
||||
tail -f /tmp/homeai-wyoming-satellite.log
|
||||
```
|
||||
|
||||
### Wake Word Not Detected
|
||||
|
||||
1. **Check microphone**:
|
||||
- Satellite logs should show audio input
|
||||
- Try speaking louder or closer to mic
|
||||
|
||||
2. **Adjust wake word sensitivity**:
|
||||
- May need to configure threshold in satellite settings
|
||||
|
||||
### No Audio Output
|
||||
|
||||
1. **Check speaker**:
|
||||
```bash
|
||||
afplay /System/Library/Sounds/Glass.aiff
|
||||
```
|
||||
|
||||
2. **Check TTS is working**:
|
||||
- Test via HA Assist (type query)
|
||||
- Should hear response
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Recommended Setup Order:**
|
||||
|
||||
1. ✅ Add Wyoming STT integration (10.0.0.101:10300)
|
||||
2. ✅ Add Wyoming TTS integration (10.0.0.101:10301)
|
||||
3. ✅ Add OpenClaw Conversation integration (10.0.0.101:8080)
|
||||
4. ✅ Create voice assistant pipeline "HomeAI with OpenClaw"
|
||||
5. ✅ Add Wyoming Satellite integration (10.0.0.101:10700)
|
||||
6. ✅ Assign satellite to "HomeAI with OpenClaw" pipeline
|
||||
7. ✅ Test the complete voice loop
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [`VOICE_PIPELINE_SETUP.md`](VOICE_PIPELINE_SETUP.md) - Complete setup guide
|
||||
- [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) - Troubleshooting guide
|
||||
- [`OPENCLAW_NETWORK_FIX.md`](OPENCLAW_NETWORK_FIX.md) - Network access fix
|
||||
Reference in New Issue
Block a user