Trixy7/.claude/project-knowledge/integrations.md

Integrationen

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

---

Trixy-Protokoll

Nachrichtenstruktur

+---------+----------+-----------+-----------+----------+---------------+-------------+----------+
| Magic   | Version  | Timestamp | Flags     | Checksum | ClassNameLen  | ClassName   | Data     |
| 4 bytes | 2 bytes  | 8 bytes   | 4 bytes   | 16 bytes | 2 bytes       | variable    | variable |
+---------+----------+-----------+-----------+----------+---------------+-------------+----------+

Feld	Beschreibung
Magic	TRXI (4 bytes)
Version	Major.Minor (je 1 byte)
Timestamp	Unix-Zeit in ms (8 bytes)
Flags	ProtocolFlags (32-bit)
Checksum	MD5 der Daten (16 bytes)
ClassNameLen	Laenge des Klassennamens
ClassName	Name der Nachrichtenklasse
Data	Serialisierte Daten

ProtocolFlags

Flag	Bit	Beschreibung
COMPRESSED	0	Daten komprimiert (zlib)
ENCRYPTED	1	AES-256-GCM verschluesselt
JSON	2	JSON-Format
ACK_REQUIRED	3	Bestaetigung erforderlich
BASE64	4	Base64-kodiert
MULTIPART	5	Teil einer Mehrteiligen Nachricht
DICT	6	Dictionary-Daten
SILENT	7	Kein Logging
PICKLE	8	Pickle-serialisiert
RESPONSE	9	Ist Antwort
ERROR	10	Enthaelt Fehlerdaten
BINARY	11	Rohe Binaerdaten

Hard-coded Befehle

Fuer Effizienz werden diese Befehle direkt gesendet (8 bytes):

Befehl	Bytes	Verwendung
TRXINOOP	54 52 58 49 4E 4F 4F 50	Keine Operation
TRXIPING	54 52 58 49 50 49 4E 47	Ping-Anfrage
TRXIPONG	54 52 58 49 50 4F 4E 47	Ping-Antwort
TRXIPRNT	54 52 58 49 50 52 4E 54	Debug-Ausgabe
TRXYHELO	54 52 58 59 48 45 4C 4F	Handshake

Network-Read/Write Pattern

# Empfangen:
header = await readexactly(8)  # Magic(4) + first 4 bytes
if header in HARD_COMMANDS:    # Direkt verarbeiten
    return
# Restlichen Header + ClassName + Data lesen

# Senden:
_send_message(class_name, data, flags)

Verschluesselung

AES-256-GCM

class TrixyEncryption:
    NONCE_SIZE = 12
    KEY_SIZE = 32  # 256 bit

    def encrypt(plaintext: bytes, associated_data: bytes | None) -> bytes
    # Gibt zurueck: Nonce (12 bytes) + Ciphertext + Tag (16 bytes)

    def decrypt(ciphertext: bytes, associated_data: bytes | None) -> bytes

    def save_key(path: Path) -> None
    @classmethod
    def load_key(path: Path) -> TrixyEncryption
    @classmethod
    def load_or_create(path: Path) -> TrixyEncryption

Plugin-System

Plugin-Verzeichnisstruktur

plugins/
└── mein_plugin/
    ├── main.py          # Plugin-Klasse (TrixyPlugin)
    ├── config.json      # Plugin-Konfiguration
    ├── trainer.py        # Optional: Plugin-eigener Trainer (ITrainer)
    └── intents.yaml     # Optional: Intent-Definitionen fuer IntentTrainer

Plugin-Entwicklung

from trixy_core.plugins import TrixyPlugin

class MeinPlugin(TrixyPlugin):
    NAME = "MeinPlugin"
    VERSION = "1.0.0"
    DESCRIPTION = "Beschreibung"
    AUTHOR = "Autor"

    async def on_load(self):
        pass

    async def on_unload(self):
        pass

    @TrixyEvent(["wakeword_received"])
    def on_wakeword(self, event_name, event_data):
        pass

Intent-Definitionen (intents.yaml)

Plugins definieren ihre Intents in YAML-Dateien, die vom IntentTrainer automatisch entdeckt werden:

intents:
  play_music:
    patterns:
      - "spiele {query}"
      - "spiel musik von {query}"
    examples:
      - text: "Koenntest du bitte Musik von Rammstein spielen"
        slots:
          query: "Rammstein"

Config-Tool Protokoll (Port 2105)

Nachrichten-Typen

Klasse	Richtung	Zweck
ConfigConnect	Tool -> Server	Verbindungsaufbau
ConfigConnectAccepted	Server -> Tool	Bestaetigung
ConfigConnectDenied	Server -> Tool	Ablehnung
ConfigStatusRequest	Tool -> Server	System-Status abfragen
ConfigStatusResponse	Server -> Tool	CPU, RAM, Disk, Uptime
ConfigReadRequest	Tool -> Server	Config-Wert lesen
ConfigReadResponse	Server -> Tool	Config-Wert
ConfigFieldOptionsRequest	Tool -> Server	Verfuegbare Optionen
ConfigFieldOptionsResponse	Server -> Tool	Options-Liste
ConfigSatelliteListRequest	Tool -> Server	Satellite-Liste
ConfigSatelliteListResponse	Server -> Tool	Satellites mit Status
ConfigSatelliteAudioRequest	Tool -> Server -> Satellite	Audio-Steuerung
ConfigSatelliteAudioResponse	Satellite -> Server -> Tool	Audio-Status

Audio-Streaming

Stream	Port	Format	Sample Rate	Channels
Audio Input	2102	16-bit PCM	16 kHz	1 (mono)
Audio Output	2103	16-bit PCM	16 kHz	1 (mono)
Music	2104	16-bit PCM	48 kHz	2 (stereo)

Trainer-Integration

TrainerRegistry Discovery

trixy_core/trainer/core/            # Core-Trainer
  ├── wakeword_trainer.py           # Direkte .py Datei
  └── intent/trainer.py             # Unterverzeichnis mit trainer.py

plugins/*/trainer.py                # Plugin-Trainer (automatisch entdeckt)

Training-Ausfuehrung

• Training laeuft als multiprocessing.Process (spawn-Kontext, CUDA-sicher)
• Fortschritt via multiprocessing.Queue (alle 0.5s gepollt)
• Steuerung: pause_event, resume_event, stop_event (multiprocessing.Event)
• TUI: F7 Trainer-Liste, Sub-Navigation F1-F6

---

See also: architecture.md, workflows.md