Серия KVM ▾

KVM Tutorial 04 — Устранение неполадок

Распространённые проблемы и решения для устройств Openterface KVM.

Устройство не обнаружено

Симптомы

  • «No devices found» в меню устройств
  • Индикаторы клавиатуры и мыши показывают оранжевый или серый цвет
  • Последовательный порт показывает «N/A»

Диагностика

Linux:

lsusb | grep -E "534d|1a86"
dmesg | tail -20
ls /dev/hidraw*   # HID video chip
ls /dev/ttyUSB*   # serial chip
Ожидается: `534d:2109` (захват HDMI) и `1a86:7523` или `1a86:fe0c` (serial).

**macOS:** Apple Menu > About This Mac > System Report > Hardware > USB — найдите Openterface.

**Windows:** Device Manager > «Universal Serial Bus devices» и «Ports (COM & LPT)» — CH340 должен отображаться как «USB-SERIAL CH340 (COMx)».

### Решения

| Проблема | Исправление |
|---------|-----|
| Устройство отсутствует в lsusb/System Report | Попробуйте другой USB-кабель/порт. Требуется USB 2.0+ |
| Устройство видно, но нет узлов | Проверьте правила udev (Linux) или переустановите драйверы (Windows) |
| Отказано в доступе | Добавьте пользователя в группы `dialout` и `video` (Linux) |
| Обнаружено, затем исчезает | `brltty` захватывает последовательный порт (Linux) — см. ниже |

---

## Конфликт BrlTTY (Linux) {#brltty-conflict-linux}

**Наиболее частая причина отказа клавиатуры/мыши в Linux.**

Служба `brltty` (Braille-терминал) захватывает USB serial-устройства, включая чип CH9329/CH32V208.

### Исправление
```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
---

## Нет видео / чёрный экран

### Шаги

1. **Проверьте HDMI-кабель** — надёжно подключён с обеих сторон
2. **Проверьте целевое устройство** — выводит HDMI (протестируйте с обычным монитором)
3. **Попробуйте другой HDMI-кабель**
4. **Переподключите устройство** — приложение обрабатывает события hot-plug
5. **Проверьте определение видеочипа:** Поддерживаются: MS2109, MS2109S, MS2130S

### Выбор backend (Qt)

Если один backend показывает чёрный экран, попробуйте другой через **Preferences > Video > Media Backend**:
- **FFmpeg** — Наиболее надёжный (рекомендуется)
- **GStreamer** — Только Linux
- **Qt Multimedia** — Запасной вариант для Windows

### Проблемы GStreamer (Linux)

```bash
GST_DEBUG=3 ./openterfaceQT 2>&1 | grep -i error
Попробуйте другой sink:
```bash
OPENTERFACE_GST_SINK=xvimagesink ./openterfaceQT

Несоответствие EDID

Если целевое устройство не распознаёт EDID, оно может не выводить совместимое разрешение. Измените разрешение вывода цели или отредактируйте EDID через настройки дисплея приложения.

Клавиатура/мышь не реагируют

Шаги

  1. Проверьте переключатель USB — должен быть установлен на Target, а не Host
  2. Проверьте статус последовательного порта — должно отображаться имя порта, а не «N/A»
  3. Попробуйте сменить baud rate — 9600 или 115200
  4. Проверьте чип управления — Поддерживаются: CH9329, CH32V208
  5. Проверьте мониторинг CTS — Приложение отслеживает линии Clear-To-Send для HID-событий

Проблемы, специфичные для мыши

  • Относительный режим на macOS: Требуется разрешение «Универсальный доступ». Проверьте System Settings > Privacy & Security > Accessibility
  • Абсолютный режим: Убедитесь, что соотношение сторон соответствует дисплею цели
  • Задержка мыши: Попробуйте более высокий пресет производительности или увеличьте baudrate
  • Конфликты последовательного порта (Linux): Закройте другие приложения, использующие порт: sudo lsof /dev/ttyUSB0

Аудио не воспроизводится

Шаги

  1. Включите аудио через значок аудио > Enable Audio
  2. Проверьте разрешение микрофона — System Settings > Privacy & Security > Microphone (macOS)
  3. Выберите правильное устройство ввода — «OpenterfaceA» или имя устройства захвата
  4. Выберите правильное устройство вывода — динамики или наушники
  5. Проверьте вывод HDMI-аудио цели — настроено ли целевое устройство на передачу аудио через HDMI?

Проблемы с драйвером USB Serial

macOS

kextstat | grep com.apple.driver.usb.cdc

При необходимости установите драйвер WCH CH34x с WCH CH34xDriver GitHub. Включите в System Settings > General > Login Items & Extensions > Driver Extensions.

Windows

Если serial-чип не отображается в Device Manager, установите драйвер CH340/CH341. Установщик обычно включает его; для portable-сборок скачайте отдельно.

Linux

Драйвер CH340 (модуль ch341) встроен в ядро:

lsmod | grep ch341
dmesg | grep ch341

Сбой обновления прошивки

Стабильность USB

  • Не отключайте во время прошивки
  • Не переводите хост в режим сна
  • Используйте прямой USB-порт (избегайте хабов)

Восстановление

  1. Цикл питания: отключите USB, подождите 10 секунд, подключите снова
  2. Повторный вход в режим ISP (на некоторых устройствах: удерживайте кнопку при включении)
  3. Используйте Serial Reset Tool для повторной прошивки загрузчика
  4. Обратитесь в поддержку, если устройство «забrick-илось»

Проблемы с производительностью

Высокая загрузка CPU

  1. Включите аппаратное ускорение — Preferences > Video > Hardware Acceleration (VAAPI, V4L2-M2M)
  2. Снизьте разрешение — 720p использует значительно меньше CPU, чем 1080p
  3. Снизьте частоту кадров — 15fps сокращает нагрузку декодирования вдвое
  4. Смените backend — FFmpeg с HW-ускорением обычно использует меньше CPU, чем GStreamer

Пропуски кадров

Проверьте счётчик FPS в строке состояния. Если фактический FPS ниже целевого, pipeline является узким местом. Включите отбрасывание кадров в процессоре кадров FFmpeg для приоритета плавного воспроизведения.

Журналирование и диагностика

Включение журналирования

  • macOS: Settings > Logging Setting > Log to file (~/Documents/openterface.log)
  • Qt: Preferences > Log > установите уровень журнала и путь к файлу

Serial-консоль (Qt)

Откройте через Device > Serial Port Debug — показывает сообщения serial-протокола в реальном времени с фильтрами Keyboard, Mouse, HID, Chip Info.

Проблемы, специфичные для платформы

Linux: плагин платформы Qt

This application failed to start because no Qt platform plugin could be initialized.

export QT_QPA_PLATFORM=xcb

Linux: проблемы с видео на Wayland

QT_QPA_PLATFORM=xcb ./openterfaceQT

Windows: драйвер CH340

Если установка драйвера не удаётся: временно отключите принудительную проверку подписи драйвера, затем установите вручную через Device Manager.

Raspberry Pi: прерывистое видео

На Pi 3 или Pi 4 с малым объёмом памяти:

  1. Снизьте разрешение до 720p
  2. Используйте backend FFmpeg (не GStreamer)
  3. Используйте 9600 baud для стабильности serial

Проблемы, специфичные для Android

Устройство не обнаружено

Симптом: Предпросмотр видео показывает заглушку, а не экран цели.

  1. Проверьте USB OTG-подключение — отключите и снова подключите кабель
  2. Проверьте поддержку OTG — подключите USB-флешку, чтобы убедиться, что телефон поддерживает OTG
  3. Проверьте KVM-устройство — включено ли оно? Горят ли индикаторы?
  4. Попробуйте другой кабель — некоторые OTG-адаптеры неисправны
  5. Перезапустите приложение — полностью закройте (смахните из недавних приложений) и откройте снова
  6. Проверьте разрешение USB — если системный диалог запросил доступ USB, нажмите Allow

Нет видео

Симптом: Устройство обнаружено, но экран чёрный или заморожен.

  1. Проверьте HDMI-кабель — HDMI целевого ПК надёжно подключён ко входу HDMI KVM?
  2. Проверьте вывод цели — целевой ПК действительно что-то отображает?
  3. Попробуйте более низкое разрешение — откройте настройки → Video Format → выберите более низкое разрешение
  4. Проверьте разрешение камеры — Android Settings → Apps → Openterface → Permissions → убедитесь, что Camera разрешена
  5. Перезапустите приложение

Мышь не реагирует

Симптом: Видео работает, но касание экрана ничего не делает на цели.

  1. Проверьте USB-подключение для HID — откройте настройки → Device и подтвердите, что устройство активно
  2. Попробуйте другой режим мыши — переключитесь между Absolute и Relative
  3. Отключите и подключите снова — используйте красную кнопку Disconnect Device, затем подключите снова
  4. Проверьте целевой ПК — распознаёт ли USB-клавиатуру/мышь? Отключите и снова подключите USB-кабель на стороне цели

Клавиатура не отправляет клавиши

Симптом: Мышь работает, но ввод текста ничего не делает.

  1. Убедитесь, что клавиатура открыта — нажмите кнопку клавиатуры
  2. Проверьте serial-подключение — откройте настройки → Device и подтвердите, что оно активно
  3. Проверьте baudrate — откройте настройки → Baudrate и убедитесь, что соответствует устройству (по умолчанию 115200)
  4. Проверьте раскладку клавиатуры — выбрана правильная раскладка (US, JP, DE)

Приложение вылетает или зависает

  1. Закройте и перезапустите приложение
  2. Снизьте разрешение и частоту кадров видео — высокие настройки могут перегрузить устройства с ограниченной памятью
  3. Проверьте доступное место — мало места может вызвать нестабильность
  4. Обновите приложение — проверьте новую версию в Google Play или GitHub Releases

Скриншоты или записи не сохраняются

  1. Проверьте разрешение Storage — Android Settings → Apps → Openterface → Permissions → Storage
  2. Проверьте доступное место на устройстве
  3. Записи и скриншоты сохраняются в папку медиа по умолчанию на устройстве

Сбор логов (Android)

Если стандартное устранение неполадок не помогает, соберите логи для maintainer'ов:

adb logcat | grep -i openterface > openterface.log

Приложите этот файл при создании issue на GitHub.

Проблемы, специфичные для iPadOS

Примечание: iPadOS поддерживается только на KVM-Go. Если вы используете Mini-KVM или uConsole KVM Extension, приложение iPadOS не будет работать.

Bluetooth не подключается

Симптом: Кнопка BLE не становится зелёной или устройства не появляются в списке сканирования.

  1. Проверьте, что Bluetooth включён на iPad — Settings > Bluetooth
  2. Убедитесь, что KVM-Go включён — dongle должен быть подключён к USB-порту целевого ПК
  3. Поднесите iPad ближе к dongle KVM-Go — дальность BLE обычно до 10 метров
  4. Проверьте разрешение Bluetooth на iPad — Settings > Privacy & Security > Bluetooth > убедитесь, что Openterface разрешён
  5. Нажмите Refresh на экране BLE для повторного сканирования
  6. Проверьте разрешение Bluetooth приложения Openterface — если отклонено при первом запуске, включите снова в Settings

Нет предпросмотра видео

Симптом: BLE подключён, но экран чёрный или показывает изображение-руководство.

  1. Проверьте HDMI-подключение — HDMI-выход целевого ПК надёжно подключён ко входу HDMI KVM-Go?
  2. Проверьте вывод цели — целевой ПК действительно что-то отображает?
  3. Попробуйте более низкое разрешение — нажмите кнопку Video и выберите более низкое разрешение (720p или 480p)
  4. Проверьте разрешение камеры — Settings > Privacy & Security > Camera > убедитесь, что Openterface разрешён
  5. Перезапустите приложение — смахните вверх из недавних приложений и откройте снова

Мышь/касание не реагируют

Симптом: Видео работает, но касание экрана ничего не делает на цели.

  1. Проверьте BLE-подключение — кнопка BLE должна быть зелёной с значением RSSI
  2. Попробуйте другой режим мыши — переключитесь между Pan Mode и iPencil Mode
  3. Отключите и подключите снова — откройте экран BLE, нажмите Disconnect, затем Connect снова
  4. Проверьте целевой ПК — распознаёт ли KVM-Go как USB-клавиатуру/мышь?

Клавиатура не отправляет клавиши

Симптом: Мышь работает, но ввод текста ничего не делает.

  1. Убедитесь, что плавающая клавиатура открыта — нажмите кнопку Keyboard
  2. Проверьте BLE-подключение — ввод идёт через Bluetooth, а не USB
  3. Проверьте режим клавиатуры — попробуйте переключиться между Normal и Game mode
  4. Внешняя клавиатура: если используете физическую клавиатуру iPad, проверьте, что iPadOS направляет события клавиш в приложение

Аудио не воспроизводится

Симптом: Видео работает, но вы не слышите целевой ПК через iPad.

  1. Проверьте кнопку Audio — должна показывать зелёный значок динамика
  2. Проверьте разрешение микрофона — Settings > Privacy & Security > Microphone > убедитесь, что Openterface разрешён
  3. Проверьте громкость iPad — убедитесь, что iPad не на mute или на минимальной громкости
  4. Проверьте вывод аудио цели — настроен ли целевой ПК на передачу аудио через HDMI?

Приложение вылетает или зависает

  1. Закройте и перезапустите приложение
  2. Снизьте разрешение видео — высокое разрешение может нагружать старые iPad
  3. Проверьте доступное место — мало места может вызвать нестабильность
  4. Обновите приложение — проверьте App Store на наличие новой версии

Скриншоты или записи не сохраняются

  1. Проверьте разрешение Photo Library — Settings > Privacy & Security > Photos > убедитесь, что Openterface разрешён
  2. Проверьте доступное место на iPad
  3. Просмотр через приложение Files — записи сохраняются в Documents/Recordings/ даже без доступа к Photo Library

Сброс к заводским настройкам

  1. Используйте Serial Reset Tool из Settings (macOS) или меню Device (Qt)
  2. Сбрасывает HID-чип к заводским настройкам
  3. Переподключите устройство после сброса

Восстановление соединения

Приложения обрабатывают автоматическое восстановление для:

  • Отключения/переподключения устройства (hot-plug для USB, переподключение BLE для iPadOS)
  • Таймаутов связи
  • Fallback чипсетов (MS2109 → MS2109S → MS2130S)
  • Восстановления последовательного порта
  • Автопереподключения BLE iPadOS (до 3 попыток с задержкой 2 секунды)

Отправка отчётов о дефектах

  1. Включите журналирование в файл
  2. Воспроизведите проблему
  3. Отправьте через GitHub Issues или по e-mail на [email protected]