# VoskWyoming Satellite

Remote voice satellite using the [Wyoming protocol](https://github.com/rhasspy/wyoming).

* Works with [Home Assistant](https://www.home-assistant.io/integrations/wyoming)
* Local wake word detection using [Vosk](https://alphacephei.com/vosk/)
* Audio enhancements using [webrtc](https://github.com/rhasspy/webrtc-noise-gain/)
* MQTT integration for LED control and Home Assistant discovery

[![An open standard from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-open-standard.png)](https://www.openhomefoundation.org/)

---

## 📋 Requirements

* Python 3.9+
* Linux (tested on Raspberry Pi OS)
* Microphone (USB or HAT)
* Optional: ReSpeaker XVF3800 USB 4-MIC Array (for LED control)

---

## 🚀 Quick Start

### 1. Clone and Install

```bash
git clone <repository-url> ~/projects/Satellite
cd ~/projects/Satellite

# Create virtual environment
python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Install systemd Services

```bash
sudo ./install_systemd_services.sh
```

This script automatically:
- Detects your virtual environment location
- Substitutes correct paths in service files
- Installs the `satellite-python` wrapper

### 3. Start Services

```bash
# LED control (optional, requires ReSpeaker)
sudo systemctl enable wyoming-event.service
sudo systemctl start wyoming-event.service

# Wyoming Satellite
sudo systemctl enable wyoming-satelite-vosk.service
sudo systemctl start wyoming-satelite-vosk.service

# Wake word detection (Vosk)
sudo systemctl enable wyoming-wakeword-vosk.service
sudo systemctl start wyoming-wakeword-vosk.service
```

### 4. Verify

```bash
sudo systemctl status wyoming-satelite-vosk.service
journalctl -u wyoming-satelite-vosk.service -f
```

---

## 📦 Installation

### System Dependencies

```bash
sudo apt-get install python3-venv python3-pip alsa-utils
```

### Python Dependencies

```bash
# Create and activate venv
python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate

# Install requirements
pip install -r requirements.txt
```

---

## 🔧 Configuration

### Service Files

All service files are in `service/` directory and use placeholders that are automatically replaced during installation:

| Placeholder | Description |
|-------------|-------------|
| `__SAT_BASE_DIR__` | Path to Satellite repository |
| `__SAT_VENV__` | Path to virtual environment |
| `__CURRENT_USER__` | Current username |
| `__HOME_DIR__` | User home directory |

### Available Services

| Service | Description | Port |
|---------|-------------|------|
| `wyoming-satelite-vosk.service` | Main Wyoming satellite | 10700 |
| `wyoming-wakeword-vosk.service` | Vosk wake word detection | 10400 |
| `wyoming-event.service` | LED control + MQTT | 10500 |

### Configuration Files

| File | Location | Description |
|------|----------|-------------|
| `config.yaml` | `local/vosk-wake-dev/wyoming_vosk_wake/` | VAD and wake word settings |
| `led_brightness_config.json` | `examples/` | LED brightness levels (auto-created) |

---

## 🎤 Usage

### Manual Start (without systemd)

```bash
# Activate venv
source ~/.venv_satellite/bin/activate

# Start satellite
./start_satellite.sh

# Or directly
python3 -m wyoming_satellite \
  --name 'my-satellite' \
  --uri 'tcp://0.0.0.0:10700' \
  --mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw' \
  --snd-command 'aplay -r 22050 -c 1 -f S16_LE -t raw'
```

### Wake Word Configuration

Edit `local/vosk-wake-dev/wyoming_vosk_wake/config.yaml`:

```yaml
vad:
  vad_enabled: true
  energy_threshold: 800
  speech_threshold: 0.5
  min_speech_duration_ms: 200

logging_level: debug  # debug, info, warning, error
```

### LED Control (ReSpeaker)

The LED service requires the [ReSpeaker XVF3800 control scripts](https://github.com/respeaker/usb_4mic_array):

```bash
# Clone ReSpeaker repo
git clone https://github.com/respeaker/usb_4mic_array.git ~/projects/reSpeaker_XVF3800_USB_4MIC_ARRAY

# The LED service will automatically find xvf_host.py
```

MQTT Topics:
- `wyoming/led/command` - Send commands
- `wyoming/led/brightness/set` - Set brightness (0-255)
- `wyoming/led/brightness/state` - Brightness state
- `wyoming/led/state` - Current LED state
- `wyoming/led/availability` - Online/offline status

---

## 🔍 Examples

See `examples/` directory for additional scripts:

| File | Description |
|------|-------------|
| `wyoming-led.py` | LED control with MQTT and Home Assistant discovery |
| `2mic_service.py` | Configuration for 2-mic HAT |
| `4mic_service.py` | Configuration for 4-mic array |
| `usbmic_service.py` | Configuration for USB microphone |

---

## 🛠️ Development

### Project Structure

```
Satellite/
├── service/                    # systemd service files
├── examples/                   # Example scripts
├── local/                      # Local wake word services
│   └── vosk-wake-dev/         # Vosk wake word detection
├── scripts/                    # Helper scripts
├── install_systemd_services.sh # Auto-install services
├── requirements.txt            # Python dependencies
├── start_satellite.sh          # Main startup script
└── DEPLOY.md                   # Deployment guide
```

### Running Tests

```bash
# Run linters
pylint wyoming_satellite/
mypy wyoming_satellite/

# Run tests (if available)
pytest tests/
```

### Updating Dependencies

```bash
# Update requirements.txt from current venv
pip freeze > requirements.txt
```

---

## 📖 Documentation

* [Deployment Guide](DEPLOY.md) - Full deployment instructions
* [Wyoming Protocol](https://github.com/rhasspy/wyoming) - Protocol documentation
* [Home Assistant Integration](https://www.home-assistant.io/integrations/wyoming) - HA setup
* [Vosk](https://alphacephei.com/vosk/) - Wake word recognition

---

## 🎥 Video Tutorials

* [Wyoming Voice Satellite with ChatGPT](https://www.youtube.com/watch?v=eTKgc0YDCwE)
* [Local ChatGPT Voice Assistant](https://www.youtube.com/watch?v=pAKqKTkx5X4)

---

## ⚙️ Audio Enhancements

### WebRTC Noise Suppression

Enabled by default via `requirements.txt` (webrtc-noise-gain==1.2.3)

Configure in satellite startup:
```bash
--mic-auto-gain 5 \
--mic-noise-suppression 2
```

### VAD (Voice Activity Detection)

Configured in `config.yaml`:
```yaml
vad:
  vad_enabled: true
  mode: 3  # 0-3, higher = more aggressive
  sample_rate: 16000
```

---

## 🐛 Troubleshooting

### Service won't start

```bash
# Check status
sudo systemctl status wyoming-satelite-vosk.service

# View logs
journalctl -u wyoming-satelite-vosk.service -f

# Check Python path
which satellite-python
satellite-python --version
```

### Microphone not detected

```bash
# List audio devices
arecord -L
aplay -L

# Test recording
arecord -r 16000 -c 1 -f S16_LE -t raw -d 5 test.wav
aplay test.wav
```

### MQTT Connection Issues

Check broker settings in `examples/wyoming-led.py`:
```python
MQTT_BROKER = "192.168.200.100"
MQTT_PORT = 1883
MQTT_USER = "mqtt"
MQTT_PASS = "mqtt"
```

---

## 📝 License

This project is part of the Open Home Foundation ecosystem.

[![An open standard from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-open-standard.png)](https://www.openhomefoundation.org/)