satellite/QWEN.md

VoskWyoming Satellite — Project Context

Project Overview

VoskWyoming Satellite is a remote voice satellite implementation using the Wyoming protocol for Home Assistant voice control. It provides:

• Home Assistant integration via Wyoming protocol
• Local wake word detection using Vosk (Russian wake words: "привет дроид", etc.)
• Audio enhancements via WebRTC noise suppression and gain control
• MQTT integration for LED control (ReSpeaker XVF3800 4-MIC array) and Home Assistant discovery
• Voice Activity Detection (VAD) using Silero or WebRTC

Key technologies: Python 3.9+, Wyoming protocol, Vosk, WebRTC, MQTT, systemd

---

Building and Running

Prerequisites

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

Setup

# Clone and setup
cd ~/projects/Satellite
python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate
pip install -r requirements.txt

Run (Development)

# From project root
./start_satellite.sh          # Uses systemd-style config
./start-dev.sh                # Development mode
python3 -m wyoming_satellite  # Direct module run

Main script: wyoming_satellite/__main__.py — argparse-based CLI with extensive options for mic, sound, wake word, VAD, and event handling.

Run (Production — systemd)

sudo ./install_systemd_services.sh  # Auto-installs services

# Start services
sudo systemctl enable --now wyoming-event.service
sudo systemctl enable --now wyoming-satelite-vosk.service
sudo systemctl enable --now wyoming-wakeword-vosk.service

# Check status
journalctl -u wyoming-satelite-vosk.service -f

Services

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

---

Development

Code Quality

# Linting
pylint wyoming_satellite/
mypy wyoming_satellite/

# Formatting
black wyoming_satellite/
isort wyoming_satellite/

# Tests
pytest tests/
tox  # Multi-version testing

Config files:

• pylintrc — Pylint with many disabled checks (pragmatic approach)
• mypy.ini — Permissive, ignores missing imports
• .isort.cfg — Import sorting
• tox.ini — pytest-based test runner for Python 3.9–3.13

Project Structure

Satellite/
├── wyoming_satellite/       # Main package
│   ├── __main__.py          # CLI entry point
│   ├── satellite.py         # Satellite implementations
│   ├── settings.py          # Dataclass-based settings
│   ├── event_handler.py     # Wyoming event handling
│   ├── vad.py               # Voice activity detection
│   └── webrtc.py            # WebRTC audio processing
├── services/                 # systemd service files
├── examples/                 # Example scripts (LED, MQTT)
├── scripts/                  # Helper scripts
├── tests/                    # pytest tests
├── sounds/                   # Audio files (awake.wav, etc.)
├── start_satellite.sh        # Main startup script
├── install_systemd_services.sh  # Service installer
└── requirements.txt          # Dependencies

Key Files

File	Purpose
wyoming_satellite/__main__.py	Main entry point, CLI parsing
wyoming_satellite/satellite.py	SatelliteBase, AlwaysStreamingSatellite, VadStreamingSatellite, WakeStreamingSatellite
wyoming_satellite/settings.py	Settings dataclasses (MicSettings, SndSettings, VadSettings, WakeSettings, etc.)
start_satellite.sh	Production startup script (wake/vad modes)
services/*.service	systemd unit files with placeholders

---

Configuration

Wake Words (Russian)

Configured in start_satellite.sh:

--wake-word-name "привет дроид"
--wake-word-name "привет придурок"
--wake-word-name "привет жопа с ушами"

VAD Settings

# 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

MQTT (LED Control)

Topics in examples/wyoming-led.py:

• wyoming/led/command
• wyoming/led/brightness/set
• wyoming/led/brightness/state
• wyoming/led/state
• wyoming/led/availability

---

Testing Practices

• Framework: pytest + pytest-asyncio
• Test files: tests/test_satellite.py, tests/test_wake_streaming.py
• Shared fixtures: tests/shared.py
• Multi-version: tox runs tests on Python 3.9–3.13

---

Deployment Notes

• Virtual env location: ~/.venv_satellite or ~/projects/.venv_satellite
• Service installer: install_systemd_services.sh auto-detects venv path and substitutes placeholders (__SAT_BASE_DIR__, __SAT_VENV__, __CURRENT_USER__)
• Wrapper script: satellite-python installed to /usr/local/bin/ for systemd services

---

External Resources

• Wyoming Protocol
• Home Assistant Wyoming Integration
• Vosk
• ReSpeaker 4-MIC Array

---

Known Issues / Workarounds

• pylintrc: Many checks disabled — pragmatic approach, focus on functionality over strict linting
• mypy: ignore_missing_imports = true — third-party stubs not always available
• Audio: Uses arecord/aplay with specific hardware (plughw:CARD=Array,DEV=0) — adjust for different microphones