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

⚙️ 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.