بروتوكول IPC لوجيتك

توثيق هندسي عكسي لبروتوكول IPC لعامل Logi Options+. يتيح التحكم البرمجي في أجهزة Logitech متعددة المضيفين (تبديل المضيف، استعلامات الجهاز) دون الوصول المباشر إلى HID، على كل من macOS و Windows.

لم يتم توثيق هذا البروتوكول بشكل علني قبل هذا المشروع.

المشكلة

يحظر macOS الوصول المباشر إلى HID لأجهزة الإدخال عبر Bluetooth على مستوى النواة. لا توجد أذونات أو صلاحيات أو اختراقات تتجاوز ذلك. يمتلك عامل Logi Options+ صلاحيات موقععة من Apple (com.apple.security.device.bluetooth) تمنحه الوصول إلى HID عبر Bluetooth. يتواصل هذا المشروع مع العامل عبر قناة IPC الخاصة به بدلاً من ذلك.

الملفات

الاستخدام

Mac

python3 switch_to_windows.py 0        # التبديل إلى المضيف 0 (DisplayPort)
python3 switch_to_windows.py 1        # التبديل إلى المضيف 1 (HDMI)
python3 switch_to_windows.py --dry-run 0  # عرض ما سيحدث دون تنفيذ

يتطلب تشغيل Logi Options+ وتثبيت m1ddc (brew install m1ddc).

Windows

# بدء مستمع مفاتيح الاختصار AHK (يعمل في علبة النظام، بدون وحدة تحكم)
# يتطلب AutoHotkey v2: winget install AutoHotkey.AutoHotkey
start kvm.ahk

# أو التبديل مباشرة من سطر الأوامر
python kvm_daemon_windows.py --switch 1

# عرض الأجهزة المكتشفة ومفاتيح الاختصار المهيأة دون تبديل
python kvm_daemon_windows.py --dry-run

يتطلب تشغيل Logi Options+. تركيب التبعيات: pip install pywin32.

يستمع سكريبت AHK لمفاتيح Win+1/2/3 ويستدعي kvm_daemon_windows.py --switch N لكل منها. يقوم سكريبت Python باكتشاف الأجهزة تلقائيًا من العامل (بدون معرفات جهاز ثابتة أو مسارات HID). عدّل kvm_config.ini لتكوين مفاتيح الاختصار وقيم إدخال DDC/CI للشاشة.

البروتوكول

يستمع العامل على:

• macOS: مقبس نطاق Unix في /tmp/logitech_kiros_agent-<hash>
• Windows: named pipe في \\.\pipe\logitech_kiros_agent-<hash>

نفس بروتوكول الاتصال على كلا النظامين. تنسيق الإطار الثنائي:

LE32(total_len) + BE32(proto_name_len) + "json" + BE32(msg_len) + JSON_message

لتبديل جهاز إلى مضيف مختلف:

{
  "msg_id": "1",
  "verb": "SET",
  "path": "/change_host/<device_id>/host",
  "payload": {
    "@type": "type.googleapis.com/logi.protocol.devices.ChangeHost",
    "host": 0
  }
}

الحمولة هي حقل google.protobuf.Any يتم تسلسله كـ JSON مضمن مع تعليق @type. يستخدم العامل محلل JSON صارم خاص بـ protobuf؛ الحقول غير المعروفة تسبب INVALID_MESSAGE_RECEIVED.

تستخدم الطلبات msg_id (snake_case). الردود تستخدم msgId (camelCase). الأفعال هي سلاسل: "GET", "SET", "SUBSCRIBE", "BROADCAST".

انظر logi-options-ipc-reverse-engineering.md للحصول على توثيق كامل للبروتوكول.

معالجة أخطاء IPC

للتشغيل الآلي طويل الأمد، أعد الاتصال عند BrokenPipeError وأعد اكتشاف مسار المقبس/الناقل.

مشاكل Windows HID++ المعروفة

تنطبق هذه عند إرسال أوامر HID++ مباشرة، وليس من خلال العامل. kvm_daemon_windows.py يتجنبها جميعًا بالمرور عبر named pipe الخاص بالعامل.

Get-PnpDeviceProperty -InstanceId "<instance_id>" -KeyName DEVPKEY_Device_HardwareIds
# ابحث عن: UP:FF43_U:0202

إرسال: {0x11, 0x00, 0x00, 0x0D, 0x18, 0x14, ...}  (20 بايت)
قراءة: البايت 4 من الاستجابة = فهرس الميزة

الإصدارات المختبرة

بروتوكول الاتصال ومسارات API الأساسية (/devices/list, /change_host/<id>/host) كانت مستقرة. إعادة إقران الجهاز كسرت مسارات HID وأرقام المجموعات لكن بروتوكول IPC نفسه لم يتأثر.

إخلاء مسؤولية

هذا المشروع لأغراض تعليمية وبحثية فقط. إنه يوثق بروتوكولًا غير موثق وغير مدعوم يمكن لـ Logitech تغييره أو إزالته في أي وقت. المؤلفون غير مسؤولين عن أي ضرر أو فقدان بيانات أو تعطل الأجهزة أو وظائف معطلة ناتجة عن استخدام هذا الرمز أو التوثيق. استخدم على مسؤوليتك الخاصة.

هذا المشروع ليس تابعًا أو معتمدًا من Logitech.

الترخيص

MIT