Files

T

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

- Перемещена документация в 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>

2026-05-19 20:12:20 +03:00

8.4 KiB

Raw Blame History

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

# 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   │
                  └──────────────┘

8.4 KiB Raw Blame History