KVM-Tutorial 04 — Fehlerbehebung
Häufige Probleme und Lösungen für Openterface KVM-Geräte.
Gerät wird nicht erkannt
Symptome
- „No devices found“ im Gerätemenü
- Tastatur- und Maus-Indikatoren zeigen Orange oder Grau
- Serieller Port zeigt „N/A“
Diagnose
Linux:
lsusb | grep -E "534d|1a86"
dmesg | tail -20
ls /dev/hidraw* # HID video chip
ls /dev/ttyUSB* # serial chip
Erwartet: `534d:2109` (HDMI-Capture) und `1a86:7523` oder `1a86:fe0c` (Serial).
**macOS:** Apple-Menü > Über diesen Mac > Systembericht > Hardware > USB — nach Openterface suchen.
**Windows:** Geräte-Manager > „USB-Controller“ und „Anschlüsse (COM & LPT)“ — CH340 sollte als „USB-SERIAL CH340 (COMx)“ erscheinen.
### Lösungen
| Problem | Behebung |
|---------|-----|
| Gerät nicht in lsusb/Systembericht | Anderes USB-Kabel/Port versuchen. USB 2.0+ erforderlich |
| Gerät sichtbar, aber keine Knoten | udev-Regeln prüfen (Linux) oder Treiber neu installieren (Windows) |
| Zugriff verweigert | Benutzer zu `dialout`- und `video`-Gruppen hinzufügen (Linux) |
| Erkannt, dann verschwunden | `brltty` beansprucht den seriellen Port (Linux) — siehe unten |
---
## BrlTTY-Konflikt (Linux) {#brltty-conflict-linux}
**Die häufigste Ursache für Tastatur-/Mausausfall unter Linux.**
Der `brltty`-Dienst (Braille-Terminal) beansprucht USB-Serial-Geräte, einschließlich des CH9329/CH32V208-Chips.
### Behebung
```bash
# Option 1: Remove brltty (if you don't need Braille support)
sudo apt remove brltty # Debian/Ubuntu
sudo dnf remove brltty # Fedora
# Option 2: Blacklist the device (preferred)
echo 'ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", ENV{BRLTTY_BRAILLE_DRIVER}=""' | sudo tee /etc/udev/rules.d/99-brltty-openterface.rules
sudo udevadm control --reload-rules
---
## Kein Video / Schwarzer Bildschirm
### Schritte
1. **HDMI-Kabel** an beiden Enden fest angeschlossen prüfen
2. **Zielgerät** prüfen, ob es HDMI ausgibt (mit normalem Monitor testen)
3. **Anderes HDMI-Kabel** versuchen
4. **Gerät neu verbinden** — die App verarbeitet Hot-Plug-Ereignisse
5. **Video-Chipset-Erkennung prüfen:** Unterstützt: MS2109, MS2109S, MS2130S
### Backend-Auswahl (Qt)
Wenn ein Backend einen schwarzen Bildschirm zeigt, über **Preferences > Video > Media Backend** ein anderes versuchen:
- **FFmpeg** — Am zuverlässigsten (empfohlen)
- **GStreamer** — Nur Linux
- **Qt Multimedia** — Windows-Fallback
### GStreamer-Probleme (Linux)
```bash
GST_DEBUG=3 ./openterfaceQT 2>&1 | grep -i error
Anderen Sink versuchen:
```bash
OPENTERFACE_GST_SINK=xvimagesink ./openterfaceQT
EDID-Konflikt
Wenn das Ziel die EDID nicht erkennt, gibt es möglicherweise keine kompatible Auflösung aus. Ziel-Ausgabeauflösung ändern oder EDID über die Anzeigeeinstellungen der App bearbeiten.
Tastatur/Maus reagiert nicht
Schritte
- USB-Umschalter prüfen — auf Target stellen, nicht Host
- Seriellen Port-Status prüfen — Portname anzeigen, nicht „N/A“
- Baudrate wechseln — 9600 oder 115200
- Steuer-Chipset prüfen — Unterstützt: CH9329, CH32V208
- CTS-Überwachung prüfen — Die App überwacht Clear-To-Send-Leitungen für HID-Ereignisse
Maus-spezifische Probleme
- Relativer Modus unter macOS: Erfordert Bedienungshilfen-Berechtigung. System Settings > Privacy & Security > Accessibility prüfen
- Absoluter Modus: Seitenverhältnis muss zur Zielanzeige passen
- Mausverzögerung: Höheres Leistungs-Preset oder höhere Baudrate versuchen
- Serieller Port-Konflikte (Linux): Andere Apps schließen, die den Port nutzen:
sudo lsof /dev/ttyUSB0
Audio wird nicht abgespielt
Schritte
- Audio aktivieren über Audio-Symbol > Enable Audio
- Mikrofonberechtigung prüfen — System Settings > Privacy & Security > Microphone (macOS)
- Richtiges Eingabegerät wählen — „OpenterfaceA“ oder Capture-Gerätename
- Richtiges Ausgabegerät wählen — Lautsprecher oder Kopfhörer
- HDMI-Audioausgabe des Ziels prüfen — Ist das Ziel für Audio über HDMI konfiguriert?
USB-Serial-Treiberprobleme
macOS
kextstat | grep com.apple.driver.usb.cdc
Bei Bedarf WCH CH34x-Treiber von WCH CH34xDriver GitHub installieren. In System Settings > General > Login Items & Extensions > Driver Extensions aktivieren.
Windows
Wenn der Serial-Chip nicht im Geräte-Manager erscheint, CH340/CH341-Treiber installieren. Installer enthält ihn meist; bei Portable-Builds separat herunterladen.
Linux
Der CH340-Treiber (ch341-Modul) ist im Kernel enthalten:
lsmod | grep ch341
dmesg | grep ch341
Firmware-Update schlägt fehl
USB-Stabilität
- Während des Flashvorgangs nicht abziehen
- Host nicht in den Ruhezustand versetzen
- Direkten USB-Port verwenden (Hubs vermeiden)
Wiederherstellung
- Stromzyklus: USB abziehen, 10 Sekunden warten, wieder verbinden
- ISP-Modus erneut betreten (einige Geräte: Taste beim Einschalten gedrückt halten)
- Serial Reset Tool zum erneuten Flashen des Bootloaders verwenden
- Bei Brick Support kontaktieren
Leistungsprobleme
Hohe CPU-Auslastung
- Hardware-Beschleunigung aktivieren — Preferences > Video > Hardware Acceleration (VAAPI, V4L2-M2M)
- Auflösung senken — 720p nutzt deutlich weniger CPU als 1080p
- Bildrate senken — 15fps halbiert die Decode-Last
- Backend wechseln — FFmpeg mit HW-Beschleunigung nutzt typischerweise weniger CPU als GStreamer
Frame-Drops
FPS-Zähler in der Statusleiste prüfen. Liegt die tatsächliche FPS unter dem Ziel, ist die Pipeline der Engpass. Frame-Dropping im FFmpeg-Frame-Processor aktivieren, um flüssige Wiedergabe zu priorisieren.
Protokollierung und Diagnose
Protokollierung aktivieren
- macOS: Settings > Logging Setting > Log to file (
~/Documents/openterface.log) - Qt: Preferences > Log > Log-Level und Dateipfad setzen
Serial-Konsole (Qt)
Über Device > Serial Port Debug öffnen — zeigt Echtzeit-Serial-Protokollmeldungen mit Filtern für Keyboard, Mouse, HID, Chip Info.
Plattformspezifische Probleme
Linux: Qt-Plattform-Plugin
This application failed to start because no Qt platform plugin could be initialized.
export QT_QPA_PLATFORM=xcb
Linux: Wayland-Video-Probleme
QT_QPA_PLATFORM=xcb ./openterfaceQT
Windows: CH340-Treiber
Wenn die Treiberinstallation fehlschlägt: Treibersignaturerzwingung vorübergehend deaktivieren, dann manuell über den Geräte-Manager installieren.
Raspberry Pi: Video-Ruckeln
Auf Pi 3 oder Pi 4 mit wenig RAM:
- Auflösung auf 720p senken
- FFmpeg-Backend verwenden (nicht GStreamer)
- 9600 Baud für Serial-Stabilität
Android-spezifische Probleme
Gerät wird nicht erkannt
Symptom: Videovorschau zeigt Platzhalter, nicht den Zielbildschirm.
- USB-OTG-Verbindung prüfen — Kabel ab- und wieder anstecken
- OTG-Unterstützung prüfen — USB-Stick anschließen, um OTG zu bestätigen
- KVM-Gerät prüfen — Ist es eingeschaltet? Leuchten Indikatoren?
- Anderes Kabel versuchen — manche OTG-Adapter sind defekt
- App neu starten — vollständig schließen (aus letzten Apps wischen) und erneut öffnen
- USB-Berechtigung prüfen — bei Systemdialog Allow tippen
Kein Video
Symptom: Gerät erkannt, aber Bildschirm schwarz oder eingefroren.
- HDMI-Kabel prüfen — Ist HDMI des Ziel-PCs fest am KVM-HDMI-Eingang?
- Zielausgabe prüfen — Zeigt der Ziel-PC tatsächlich etwas an?
- Niedrigere Auflösung versuchen — Einstellungen → Video Format → niedrigere Auflösung
- Kameraberechtigung prüfen — Android-Einstellungen → Apps → Openterface → Berechtigungen → Camera erlauben
- App neu starten
Maus reagiert nicht
Symptom: Video funktioniert, Tippen auf dem Bildschirm bewirkt am Ziel nichts.
- USB-Verbindung für HID prüfen — Einstellungen → Device, Gerät aktiv?
- Anderen Mausmodus versuchen — zwischen Absolute und Relative wechseln
- Trennen und neu verbinden — roten Disconnect Device-Button, dann erneut verbinden
- Ziel-PC prüfen — Erkennt er USB-Tastatur/Maus? USB-Kabel am Ziel ab- und anstecken
Tastatur sendet keine Tasten
Symptom: Maus funktioniert, Tippen bewirkt nichts.
- Tastatur geöffnet — Tastatur-Button tippen
- Serial-Verbindung prüfen — Einstellungen → Device, aktiv?
- Baudrate prüfen — Einstellungen → Baudrate, passend zum Gerät (Standard 115200)
- Tastaturlayout prüfen — richtiges Layout (US, JP, DE) gewählt
App stürzt ab oder friert ein
- App schließen und neu starten
- Videoauflösung und Bildrate senken — hohe Einstellungen können Geräte mit wenig RAM überlasten
- Verfügbaren Speicher prüfen — wenig Speicher verursacht Instabilität
- App aktualisieren — neuere Version bei Google Play oder GitHub Releases
Screenshots oder Aufnahmen werden nicht gespeichert
- Storage-Berechtigung prüfen — Android-Einstellungen → Apps → Openterface → Berechtigungen → Storage
- Verfügbaren Speicherplatz auf dem Gerät prüfen
- Aufnahmen und Screenshots werden im Standard-Medienordner des Geräts gespeichert
Logs sammeln (Android)
Wenn normale Fehlerbehebung nicht hilft, Logs für Maintainer sammeln:
adb logcat | grep -i openterface > openterface.log
Diese Datei beim Öffnen eines GitHub-Issues beifügen.
iPadOS-spezifische Probleme
Hinweis: iPadOS wird nur auf KVM-Go unterstützt. Bei Mini-KVM oder uConsole KVM Extension funktioniert die iPadOS-App nicht.
Bluetooth verbindet nicht
Symptom: BLE-Button wird nicht grün oder keine Geräte in der Scan-Liste.
- Bluetooth auf dem iPad aktiviert — Einstellungen > Bluetooth
- KVM-Go eingeschaltet — Dongle am USB-Port des Ziel-PCs
- iPad näher an KVM-Go-Dongle — BLE-Reichweite typisch bis 10 Meter
- iPad-Bluetooth-Berechtigung — Einstellungen > Privacy & Security > Bluetooth > Openterface erlauben
- Refresh im BLE-Bildschirm für erneuten Scan
- Openterface-App-Bluetooth-Berechtigung — bei Ablehnung beim ersten Start in Einstellungen wieder aktivieren
Keine Videovorschau
Symptom: BLE verbunden, aber Bildschirm schwarz oder Anleitungsbild.
- HDMI-Verbindung — HDMI-Ausgang des Ziel-PCs fest am KVM-Go-HDMI-Eingang?
- Zielausgabe — Zeigt der Ziel-PC tatsächlich etwas an?
- Niedrigere Auflösung — Video-Button, niedrigere Auflösung (720p oder 480p)
- Kameraberechtigung — Einstellungen > Privacy & Security > Camera > Openterface erlauben
- App neu starten — aus letzten Apps nach oben wischen und erneut öffnen
Maus/Touch reagiert nicht
Symptom: Video funktioniert, Tippen bewirkt am Ziel nichts.
- BLE-Verbindung — BLE-Button grün mit RSSI-Wert
- Anderen Mausmodus — zwischen Pan Mode und iPencil Mode wechseln
- Trennen und neu verbinden — BLE-Bildschirm, Disconnect, dann Connect
- Ziel-PC — Erkennt er KVM-Go als USB-Tastatur/Maus?
Tastatur sendet keine Tasten
Symptom: Maus funktioniert, Tippen bewirkt nichts.
- Schwebende Tastatur geöffnet — Keyboard-Button
- BLE-Verbindung — Eingabe über Bluetooth, nicht USB
- Tastaturmodus — zwischen Normal und Game wechseln
- Externe Tastatur: Bei physischer iPad-Tastatur prüfen, ob iPadOS Tastenereignisse an die App weiterleitet
Audio wird nicht abgespielt
Symptom: Video funktioniert, Ziel-PC-Audio über iPad nicht hörbar.
- Audio-Button — grünes Lautsprecher-Symbol
- Mikrofonberechtigung — Einstellungen > Privacy & Security > Microphone > Openterface erlauben
- iPad-Lautstärke — nicht stumm oder auf Minimum
- Ziel-Audioausgabe — Ist der Ziel-PC für Audio über HDMI konfiguriert?
App stürzt ab oder friert ein
- App schließen und neu starten
- Videoauflösung senken — hohe Auflösung belastet ältere iPads
- Verfügbaren Speicher prüfen
- App aktualisieren — neuere Version im App Store
Screenshots oder Aufnahmen werden nicht gespeichert
- Photo Library-Berechtigung — Einstellungen > Privacy & Security > Photos > Openterface erlauben
- Verfügbaren Speicher auf dem iPad prüfen
- Über Dateien-App — Aufnahmen werden in
Documents/Recordings/gespeichert, auch ohne Photo Library-Zugriff
Werksreset
- Serial Reset Tool aus Settings (macOS) oder Device-Menü (Qt) verwenden
- Setzt den HID-Chip auf Werkseinstellungen zurück
- Gerät nach Reset neu verbinden
Verbindungswiederherstellung
Die Anwendungen behandeln automatische Wiederherstellung für:
- Gerätetrennung/-wiederverbindung (Hot-Plug für USB, BLE-Reconnect für iPadOS)
- Kommunikations-Timeouts
- Chipset-Fallbacks (MS2109 → MS2109S → MS2130S)
- Serial-Port-Wiederherstellung
- iPadOS BLE-Auto-Reconnect (bis zu 3 Versuche mit 2-Sekunden-Verzögerung)
Fehlerberichte einreichen
- Protokollierung in Datei aktivieren
- Problem reproduzieren
- Über GitHub Issues oder E-Mail an [email protected] einreichen