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
docs/architecture/overview.md
+175
View File
@@ -0,0 +1,175 @@
# Architecture Overview
High-level architecture of Wyoming Satellite.
## Core Components
```
┌─────────────────────────────────────────────────────────────┐
│ Home Assistant │
│ (Wyoming Integration) │
└──────────────────────┬──────────────────────────────────────┘
│ Wyoming Protocol (TCP)
│ Port 10700
┌──────────────────────▼──────────────────────────────────────┐
│ Wyoming Satellite │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SatelliteBase │ │
│ │ ├─ AlwaysStreamingSatellite │ │
│ │ ├─ VadStreamingSatellite │ │
│ │ └─ WakeStreamingSatellite │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MicSettings │ │ SndSettings │ │ WakeSettings │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ EventHandler │ │
│ └─────────────────────────────────────────────────────┘ │
└──────────┬─────────────────────┬───────────────────────────┘
│ │
│ Audio In │ Audio Out
│ (arecord) │ (aplay)
┌──────────▼──────┐ ┌────────▼──────────┐
│ Microphone │ │ Speaker │
│ USB/HAT │ │ USB/HAT │
└─────────────────┘ └───────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Local Services (Optional) │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Wake Word Service │ │ Event Service │ │
│ │ (Vosk, port 10400) │ │ (MQTT, port 10500) │ │
│ └─────────────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Satellite Modes
### AlwaysStreamingSatellite
Continuously streams audio to Home Assistant.
- **Pros:** Lowest latency, simplest
- **Cons:** Highest bandwidth, no local processing
- **Use case:** Fast LAN, no privacy concerns
### VadStreamingSatellite
Uses Voice Activity Detection to start streaming only when speech is detected.
- **VAD Systems:**
- **Silero:** Neural network-based, more accurate
- **WebRTC:** Lightweight, faster
- **Features:**
- Pre-roll buffer (sends audio before VAD trigger)
- Wake word timeout (wait for wake word after VAD)
- **Use case:** Privacy-focused, bandwidth-constrained
### WakeStreamingSatellite
Uses local wake word detection before streaming.
- **Wake Word Systems:**
- **Vosk:** Grammar-based (Russian phrases)
- **openWakeWord:** Neural network
- **Porcupine:** Commercial KWS
- **Flow:**
1. Continuously listen for wake word
2. On detection → start streaming to HA
3. Process command → stop streaming
- **Use case:** Full local wake word, "Hey Google" style
## Audio Pipeline
```
Microphone
│
▼
┌─────────────────┐
│ Audio Capture │ arecord -r 16000 -c 1 -f S16_LE
└────────┬────────┘
│
▼
┌─────────────────┐
│ Pre-processing │ Volume, AGC, Noise Suppression
└────────┬────────┘
│
▼
┌─────────────────┐
│ VAD / Wake │ Decision: stream or not?
└────────┬────────┘
│
▼
┌─────────────────┐
│ Wyoming Protocol│ Encode to Wyoming messages
└────────┬────────┘
│
▼
Home Assistant
```
## Key Files
| File | Purpose |
|------|---------|
| `wyoming_satellite/__main__.py` | CLI entry point, argument parsing |
| `wyoming_satellite/satellite.py` | Satellite implementations |
| `wyoming_satellite/settings.py` | Settings dataclasses |
| `wyoming_satellite/event_handler.py` | Wyoming event handling |
| `wyoming_satellite/vad.py` | VAD implementations (Silero, WebRTC) |
| `wyoming_satellite/webrtc.py` | WebRTC audio processing |
## Configuration
Main configuration via CLI arguments (see `__main__.py`):
```bash
# Microphone
--mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw'
--mic-noise-suppression 2
--mic-auto-gain 5
# Wake word
--wake-uri tcp://127.0.0.1:10400
--wake-word-name "привет дроид"
# VAD
--vad
--vad-system webrtc
--vad-threshold 0.5
# Events (LED, MQTT)
--event-uri tcp://127.0.0.1:10500
```
## State Machine
```
┌──────────────┐
│ Stopped │
└──────┬───────┘
│ Start
▼
┌──────────────┐
┌────────│ Listening │────────┐
│ └──────┬───────┘ │
│ │ │
VAD trigger Wake detection Streaming
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ VAD │ │ Wake │ │Streaming │
│ Active │ │ Active │ │ Audio │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
└───────────────┴───────────────┘
│
AudioStop
▼
┌──────────────┐
│ Listening │
└──────────────┘
```