sirmrak/satellite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Документация: рефакторинг структуры docs/ и очистка мусора

Browse Source 
- Перемещена документация в docs/ с четкой структурой:
  - tutorials/ — пошаговые руководства (2mic-hat, installer)
  - integration/ — техническая интеграция (vad-wakeword, mqtt-led)
  - deployment/ — развёртывание (systemd-services)
  - architecture/ — архитектура проекта (overview)
- Обновлён README.md с навигацией по документации
- DEPLOY.md сокращён до quick start с ссылками на docs/
- Добавлен docs/README.md — индекс документации
- Создан QWEN.md — контекст для ИИ-ассистента
- Удалён мусор:
  - wyoming_satellite.zip (build artifact)
  - wyoming-led.service, wyoming-satellite.service (дубликаты)
  - .qwen/settings.json.orig (бэкап)
  - .lgd-nfy0 (пустой файл)
  - docker/run (заглушка)
- Обновлён .gitignore:
  - examples/led_brightness_config.json (автогенерируемый конфиг)
  - *.old, *.bak, *~ (бэкапы)
  - *.zip (архивы)
  - .qwen/settings.json.orig
  - *.lgd-* (пустые файлы)
- led_brightness_config.json исключён из отслеживания (assume-unchanged)

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
sirmrak
2026-05-19 20:12:20 +03:00
co-authored by Qwen-Coder
parent cae22004b1
commit adac79e765
17 changed files with 866 additions and 357 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -245
View File
@@ -1,38 +1,27 @@
# VoskWyoming Satellite
# README — 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
Remote voice satellite using the [Wyoming protocol](https://github.com/rhasspy/wyoming) for Home Assistant.
[![An open standard from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-open-standard.png)](https://www.openhomefoundation.org/)
---
## Features
## 📋 Requirements
- 🏠 **Home Assistant integration** — Native Wyoming protocol support
- 🎤 **Local wake word detection** — Vosk-based Russian wake words ("привет дроид", etc.)
- 🔇 **Audio enhancements** — WebRTC noise suppression and automatic gain control
- 💡 **MQTT LED control** — ReSpeaker XVF3800 4-MIC array support with HA discovery
- 🎯 **Voice Activity Detection** — Silero or WebRTC VAD for privacy-focused operation
* 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
---
## 🚀 Quick Start
### 1. Clone and Install
### 1. 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
```
@@ -42,271 +31,125 @@ pip install -r requirements.txt
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
### 3. Start
```bash
sudo systemctl enable --now wyoming-satelite-vosk.service
sudo systemctl status wyoming-satelite-vosk.service
journalctl -u wyoming-satelite-vosk.service -f
```
In Home Assistant: **Settings → Devices & Services → Discovered → Wyoming Satellite → Configure**
---
## 📦 Installation
## Documentation
### System Dependencies
| Guide | Description |
|-------|-------------|
| [**Deployment**](DEPLOY.md) | Full deployment guide with systemd services |
| [**Tutorials**](docs/tutorials/) | Step-by-step setup for different hardware |
| [**Architecture**](docs/architecture/overview.md) | How Wyoming Satellite works |
| [**MQTT LED**](docs/integration/mqtt-led.md) | LED control with Home Assistant |
| [**VAD Integration**](docs/integration/vad-wakeword.md) | Technical integration guide |
```bash
sudo apt-get install python3-venv python3-pip alsa-utils
```
### Tutorials
### Python Dependencies
```bash
# Create and activate venv
python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate
# Install requirements
pip install -r requirements.txt
```
- [**2-MIC HAT**](docs/tutorials/2mic-hat.md) — Raspberry Pi + ReSpeaker 2-MIC HAT
- [**Installer**](docs/tutorials/installer.md) — Interactive installer guide
---
## 🔧 Configuration
## Requirements
### 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) |
- **Python 3.9+**
- **Linux** (tested on Raspberry Pi OS)
- **Microphone** (USB or HAT)
- **Optional:** ReSpeaker XVF3800 USB 4-MIC Array (for LED control)
---
## 🎤 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
## 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
├── wyoming_satellite/ # Main Python package
├── examples/ # Example scripts (LED, MQTT, configs)
├── services/ # systemd service files
├── docs/ # Documentation
│ ├── tutorials/ # Hardware-specific guides
│ ├── integration/ # Technical integration guides
│ ├── deployment/ # Deployment guides
│ └── architecture/ # Architecture documentation
├── sounds/ # Audio files (awake.wav, etc.)
├── scripts/ # Helper scripts
└── tests/ # Unit tests
```
### Running Tests
---
## Configuration
### Wake Words (Russian)
Edit `start_satellite.sh`:
```bash
# Run linters
--wake-word-name "привет дроид"
--wake-word-name "привет придурок"
--wake-word-name "привет жопа с ушами"
```
### Audio Settings
```bash
--mic-noise-suppression 2
--mic-auto-gain 5
```
### VAD Settings
```bash
--vad
--vad-system webrtc
--vad-threshold 0.5
```
---
## Development
```bash
# Linting
pylint wyoming_satellite/
mypy wyoming_satellite/
# Run tests (if available)
# Tests
pytest tests/
```
### Updating Dependencies
```bash
# Update requirements.txt from current venv
pip freeze > requirements.txt
# Format
black wyoming_satellite/
isort wyoming_satellite/
```
---
## 📖 Documentation
## Video Tutorials
* [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
- [Wyoming Voice Satellite with ChatGPT](https://www.youtube.com/watch?v=eTKgc0YDCwE)
- [Local ChatGPT Voice Assistant](https://www.youtube.com/watch?v=pAKqKTkx5X4)
---
## 🎥 Video Tutorials
## External Resources
* [Wyoming Voice Satellite with ChatGPT](https://www.youtube.com/watch?v=eTKgc0YDCwE)
* [Local ChatGPT Voice Assistant](https://www.youtube.com/watch?v=pAKqKTkx5X4)
- [Wyoming Protocol](https://github.com/rhasspy/wyoming)
- [Home Assistant Integration](https://www.home-assistant.io/integrations/wyoming)
- [Vosk](https://alphacephei.com/vosk/)
- [ReSpeaker 4-MIC Array](https://github.com/respeaker/usb_4mic_array)
---
## ⚙️ 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
## License
This project is part of the Open Home Foundation ecosystem.