Workflows

Revision: r2 Source: CLAUDE.md, Code-Analyse Last updated: 2026-04-10 14:00

Wakeword-Erkennung

  Client (Satellite)           Server                 Client (andere)
       |                         |                         |
       | 1. Wakeword erkannt     |                         |
       |    (Erkennung pausieren) |                         |
       |    (Audio puffern)      |                         |
       |                         |                         |
       |--WakewordDetected------>|                         |
       |                         |<--WakewordDetected------|
       |                         |     (wenn auch erkannt) |
       |                         |                         |
       |         2. 1 Sekunde warten                       |
       |            (Arbitrierung:                         |
       |             hoechstes audio_level                 |
       |             gewinnt)                              |
       |                         |                         |
       |<--WakewordSelected------|                         |
       |   (conversation_id)     |--WakewordAbort--------->|
       |                         |                         |
       | 3. Audio streamen       |                         |
       |   (max 60s oder         |                         |
       |    3s Stille)           |                         |
       |                         |                         |
       |------Audio------------->|                         |
       |------Audio------------->|                         |
       |--RecordingDone--------->|                         |
       |                         |                         |
       |         4. raw_audio_input_received               |
       |            Event ausloesen                        |
       |                         |                         |
       |         5. STT -> NLP -> Intent                   |

Timing-Parameter

Parameter	Wert	Beschreibung
Arbitration Timeout	1 Sekunde	Warten auf mehrere Wakewords
Max Silence	3 Sekunden	Stille beendet Aufnahme
Max Duration	60 Sekunden	Maximale Aufnahmedauer
Reconnect Interval	5 Sekunden	Wiederverbindungsversuch

Satellite-Registrierung

Admin aktiviert Registrierungsmodus (60 Sekunden Timeout)
Neuer Client verbindet sich, sendet SatelliteConnect (MAC, Room, Alias)
Server prueft MAC — nicht registriert + Registrierungsmodus aktiv
Server speichert satellites/{MAC}.json und sendet SatelliteAccepted
Client erhaelt session_key und Ports

Registrierungsdatei (satellites/{MAC}.json)

{
    "id": "sat-uuid-1234",
    "room_id": "wohnzimmer",
    "mac_address": "AA-BB-CC-DD-EE-FF",
    "alias": "Echo Wohnzimmer",
    "registered_at": "2026-01-31T12:00:00.000Z"
}

Service-Start-Reihenfolge

CRITICAL (0) -> CORE (10) -> NETWORK (20) -> MANAGER (30) -> PLUGIN (40) -> OPTIONAL (50)
     |              |              |              |              |              |
     v              v              v              v              v              v
  Logging      EventManager    Sockets        Satellite      Plugins        Extras
  Config                       Protocol       Registration   ConfigListener
                               ConfigListener

Abhaengigkeiten werden automatisch aufgeloest: Wenn Service B von Service A abhaengt, wird A vor B gestartet.

Installer-Workflow

Ablauf

1. CLI: --mode server|client|standalone --version X.X.X --source-archive /pfad/trixy.tar.gz
2. TUI startet mit F-Key Navigation:
   F1: System (Hostname, Username, Pfad, Autostart)
   F2: Netzwerk (WiFi-Hotspot / WLAN-Client / Server-Verbindung)
   F3: Plugins (Auswahl)
   F4: Hardware-Preflight (Disk/RAM Check)
   F5: Nutzungsbedingungen
   F6: Installation starten
3. Installation laeuft Schritt fuer Schritt mit Fortschritt
4. Bei Netzwerk-Aenderungen: Reboot-Warnung anzeigen

WiFi-Hotspot Setup (Server, Bookworm-kompatibel)

step_wifi_ap():
  1. hostapd.conf schreiben (SSID, WPA2, Kanal)
  2. dnsmasq.conf schreiben (DHCP-Range, DNS)
  3. systemd-networkd: /etc/systemd/network/10-trixy-wlan0.network (statische IP)
  4. NetworkManager: /etc/NetworkManager/conf.d/99-trixy-wlan0-unmanaged.conf
  5. dnsmasq Race-Fix: systemd override mit ExecStartPre wait-loop
  6. sysctl: IP-Forwarding persistent
  7. iptables: MASQUERADE NAT-Regel
  8. Services nur ENABLE (nicht start) -> Deferred Activation nach Reboot

WiFi-Client Setup (Client/Standalone)

step_wifi_connect():
  1. Primaeres WLAN: nmcli connection add mit autoconnect-priority=100
  2. Fallback-WLAN: nmcli connection add mit autoconnect-priority=10
  3. Auto-Switchback Timer installieren (optional)
  4. KEINE sofortige Aktivierung -> Deferred Activation nach Reboot

Kritisch: Netzwerk-Aktivierung ist IMMER deferred (erst nach Reboot), damit SSH-Sessions waehrend der Installation nicht abbrechen.

Training-Workflow

Trainer-Framework (ADR-008)

1. TrainerRegistry entdeckt Trainer:
   - Core: trixy_core/trainer/core/*.py + */trainer.py
   - Plugin: plugins/*/trainer.py
2. TUI: F7 zeigt Trainer-Liste
3. Sub-Navigation:
   F1: Info (Name, Version, Beschreibung)
   F2: Settings (dynamisches Formular aus FormSchema)
   F3: Dataset (Datensatz-Konfiguration)
   F4: Optional (zusaetzliche Optionen)
   F5: Validate (Pre-Training Checks: GPU, Daten, Speicher)
   F6: Training (Start/Pause/Stop, Fortschritt, LossChart)
4. Training laeuft als separater Prozess (multiprocessing.Process, spawn)
5. Fortschritt via Queue: Epoch, Loss, Accuracy, VRAM, ETA
6. LossChart Widget: Braille-Zeichen (U+2800-U+28FF), Bresenham-Linien

Wakeword-Training

WakewordTrainer:
  1. TTS-Engines generieren synthetische Wakeword-Samples (Piper, gTTS, Edge, ...)
  2. Audio-Augmentation: Noise-Mix, Volume, Pitch-Shifting
  3. Mel-Spectrogram Features extrahieren
  4. LogisticRegression auf OpenWakeWord-Basis
  5. Export: model.pth, model.onnx, model.pt, metafile.json

Intent-Training

IntentTrainer:
  1. DataGenerator sammelt Intents aus Plugin intents.yaml
  2. Pattern-Expansion mit Slot-Werten
  3. Sentence-Transformers Encoder (ONNX, 113MB)
  4. 2-Layer Linear Classifier
  5. Optional: BIO-Slot-Tagger Kopf
  6. Export: intent_classifier.onnx, slot_tagger.onnx, bio_labels.json

See also: architecture.md, integrations.md

workflows.md 6.4 KB Permalink Cronologia Originale