satellite/README.md

VoskWyoming Satellite

Remote voice satellite using the Wyoming protocol.

• Works with Home Assistant
• Local wake word detection using Vosk
• Audio enhancements using webrtc
• MQTT integration for LED control and Home Assistant discovery

---

📋 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

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

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

# 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

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

---

📦 Installation

System Dependencies

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

Python Dependencies

# 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)

# 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:

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:

# 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

# Run linters
pylint wyoming_satellite/
mypy wyoming_satellite/

# Run tests (if available)
pytest tests/

Updating Dependencies

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

---

📖 Documentation

• Deployment Guide - Full deployment instructions
• Wyoming Protocol - Protocol documentation
• Home Assistant Integration - HA setup
• Vosk - Wake word recognition

---

🎥 Video Tutorials

• Wyoming Voice Satellite with ChatGPT
• Local ChatGPT Voice Assistant

---

⚙️ Audio Enhancements

WebRTC Noise Suppression

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

Configure in satellite startup:

--mic-auto-gain 5 \
--mic-noise-suppression 2

VAD (Voice Activity Detection)

Configured in config.yaml:

vad:
  vad_enabled: true
  mode: 3  # 0-3, higher = more aggressive
  sample_rate: 16000

---

🐛 Troubleshooting

Service won't start

# 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

# 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:

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.