homeai/homeai-voice/WYOMING_SATELLITE_SETUP.md

# 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