درس KVM 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
• الوضع المطلق: تحقق من تطابق نسبة العرض مع شاشة الهدف
• تأخير الفأرة: جرّب preset أداء أعلى أو زد 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

إذا لم تظهر الشريحة التسلسلية في Device Manager، ثبّت تعريف CH340/CH341. المثبّت يتضمنه عادةً؛ للنسخ المحمولة، حمّله منفصلًا.

Linux

تعريف CH340 (وحدة ch341) مدمج في النواة:

lsmod | grep ch341
dmesg | grep ch341

---

فشل تحديث البرنامج الثابت

استقرار USB

• لا تفصل أثناء التفليش
• لا تعلّق جهاز المضيف
• استخدم منفذ USB مباشر (تجنّب المحاور)

الاستعادة

1. دورة طاقة: افصل USB، انتظر 10 ثوانٍ، أعد التوصيل
2. أعد الدخول إلى وضع ISP (بعض الأجهزة: اضغط الزر أثناء التشغيل)
3. استخدم Serial Reset Tool لإعادة تفليش bootloader
4. تواصل مع الدعم إذا أصبح الجهاز brick

---

مشاكل الأداء

استخدام 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

إذا فشل تثبيت التعريف: عطّل Driver Signature Enforcement مؤقتًا، ثم ثبّت يدويًا عبر Device Manager.

Raspberry Pi: تقطع الفيديو

على Pi 3 أو Pi 4 بذاكرة محدودة:

1. خفّض الدقة إلى 720p
2. استخدم backend FFmpeg (وليس GStreamer)
3. استخدم 9600 baud لاستقرار serial

---

مشاكل خاصة بـ Android

الجهاز غير مكتشف

العرض: معاينة الفيديو تعرض placeholder وليس شاشة الهدف.

1. تحقق من اتصال USB OTG — افصل وأعد توصيل الكابل
2. تحقق من دعم OTG — جرّب توصيل فلاش USB للتأكد أن هاتفك يدعم OTG
3. تحقق من جهاز KVM — هل هو مشغّل? هل مؤشرات LED مضاءة?
4. جرّب كابلًا مختلفًا — بعض محولات OTG معطلة
5. أعد تشغيل التطبيق — أغلقه بالكامل (اسحب من التطبيقات الأخيرة) وأعد فتحه
6. تحقق من إذن USB — إذا طلب حوار النظام وصول USB، اضغط Allow

لا يوجد فيديو

العرض: الجهاز مكتشف لكن الشاشة سوداء أو مجمدة.

1. تحقق من كابل HDMI — هل HDMI لجهاز PC الهدف متصل بإحكام بمدخل HDMI لـ KVM?
2. تحقق من إخراج الهدف — هل PC الهدف يعرض شيئًا فعلاً?
3. جرّب دقة أقل — افتح الإعدادات → Video Format → اختر دقة أقل
4. تحقق من إذن الكاميرا — Android Settings → Apps → Openterface → Permissions → تأكد أن Camera مسموح
5. أعد تشغيل التطبيق

الفأرة لا تستجيب

العرض: الفيديو يعمل لكن اللمس على الشاشة لا يفعل شيئًا على الهدف.

1. تحقق من اتصال USB لـ HID — افتح الإعدادات → Device وتأكد أن الجهاز نشط
2. جرّب وضع فأرة مختلف — بدّل بين Absolute وRelative
3. افصل وأعد التوصيل — استخدم زر Disconnect Device الأحمر، ثم أعد التوصيل
4. تحقق من PC الهدف — هل يتعرف على لوحة مفاتيح/فأرة 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)

إذا لم يساعد حل المشكلات القياسي، اجمع السجلات لمشاركتها مع المطورين:

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 لـ PC الهدف
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 لـ PC الهدف متصل بإحكام بمدخل HDMI لـ KVM-Go?
2. تحقق من إخراج الهدف — هل PC الهدف يعرض شيئًا فعلاً?
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. تحقق من PC الهدف — هل يتعرف على KVM-Go كلوحة مفاتيح/فأرة USB?

لوحة المفاتيح لا ترسل مفاتيح

العرض: الفأرة تعمل لكن الكتابة لا تفعل شيئًا.

1. تأكد أن لوحة المفاتيح العائمة مفتوحة — اضغط زر Keyboard
2. تحقق من اتصال BLE — الإدخال يمر عبر Bluetooth وليس USB
3. تحقق من وضع لوحة المفاتيح — جرّب التبديل بين Normal وGame mode
4. لوحة مفاتيح خارجية: إذا كنت تستخدم لوحة مفاتيح iPad فعلية، تحقق أن iPadOS يوجّه أحداث المفاتيح للتطبيق

الصوت لا يعمل

العرض: الفيديو يعمل لكن لا تسمع PC الهدف عبر iPad.

1. تحقق من زر Audio — يجب أن يعرض أيقونة مكبر صوت خضراء
2. تحقق من إذن الميكروفون — Settings > Privacy & Security > Microphone > تأكد أن Openterface مسموح
3. تحقق من مستوى صوت iPad — تأكد أن iPad ليس صامتًا أو على الحد الأدنى
4. تحقق من إخراج صوت الهدف — هل PC الهدف مُعد لإرسال الصوت عبر 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)
• مهلة الاتصال
• بدائل chipset (MS2109 → MS2109S → MS2130S)
• استعادة المنفذ التسلسلي
• إعادة اتصال BLE تلقائي على iPadOS (حتى 3 محاولات بتأخير ثانيتين)

إرسال تقارير العيوب

1. فعّل تسجيل السجل في ملف
2. أعد إنتاج المشكلة
3. أرسل عبر GitHub Issues أو بريد إلكتروني إلى [email protected]