logitech-ipc-protocol

Dokumentation des per Reverse Engineering ermittelten IPC-Protokolls des Logi Options+ Agenten. Ermöglicht die programmatische Steuerung von Logitech-Multi-Host-Geräten (Host-Wechsel, Geräteabfragen) ohne direkten HID-Zugriff, sowohl unter macOS als auch Windows.

Das Protokoll wurde vor diesem Projekt nicht öffentlich dokumentiert.

Problem

macOS blockiert den direkten HID-Zugriff auf Bluetooth-Eingabegeräte auf Kernel-Ebene. Keine Berechtigungen, Berechtigungsnachweise oder Hacks umgehen dies. Der Logi Options+ Agent verfügt über von Apple signierte Berechtigungsnachweise (com.apple.security.device.bluetooth), die ihm Bluetooth-HID-Zugriff gewähren. Dieses Projekt kommuniziert stattdessen über den IPC-Kanal mit dem Agenten.

Dateien

Verwendung

Mac

python3 switch_to_windows.py 0        # Zu Host 0 wechseln (DisplayPort)
python3 switch_to_windows.py 1        # Zu Host 1 wechseln (HDMI)
python3 switch_to_windows.py --dry-run 0  # Anzeigen, was passieren würde

Erfordert, dass Logi Options+ läuft und m1ddc installiert ist (brew install m1ddc).

Windows

# Den AHK-Hotkey-Listener starten (läuft in der Taskleiste, keine Konsole)
# Erfordert AutoHotkey v2: winget install AutoHotkey.AutoHotkey
start kvm.ahk

# Oder direkt von der Kommandozeile umschalten
python kvm_daemon_windows.py --switch 1

# Gefundene Geräte und konfigurierte Hotkeys anzeigen, ohne umzuschalten
python kvm_daemon_windows.py --dry-run

Erfordert, dass Logi Options+ läuft. Abhängigkeiten installieren: pip install pywin32.

Das AHK-Skript lauscht auf Win+1/2/3 und ruft für jede Taste kvm_daemon_windows.py --switch N auf. Das Python-Skript ermittelt Geräte automatisch vom Agenten (keine fest codierten Geräte-IDs oder HID-Pfade). Bearbeiten Sie kvm_config.ini, um Hotkeys und DDC/CI-Eingabewerte für den Monitor zu konfigurieren.

Protokoll

Der Agent lauscht auf:

• macOS: Unix-Domain-Socket unter /tmp/logitech_kiros_agent-<hash>
• Windows: Named Pipe unter \\.\pipe\logitech_kiros_agent-<hash>

Gleiches Drahtprotokoll auf beiden Plattformen. Binäres Frame-Format:

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

Ein Gerät auf einen anderen Host umschalten:

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

Das Payload ist ein google.protobuf.Any-Feld, das als Inline-JSON mit einer @type-Annotation serialisiert wird. Der Agent verwendet einen strengen Protobuf-JSON-Parser; unbekannte Felder führen zu INVALID_MESSAGE_RECEIVED.

Anfragen verwenden msg_id (snake_case). Antworten verwenden msgId (camelCase). Verben sind Zeichenketten: "GET", "SET", "SUBSCRIBE", "BROADCAST".

Siehe logi-options-ipc-reverse-engineering.md für die vollständige Protokolldokumentation.

IPC-Fehlerbehandlung

Bei langlebiger Automatisierung nach BrokenPipeError erneut verbinden und den Socket/Pipe-Pfad neu ermitteln.

Windows HID++-Probleme

Diese gelten beim direkten Senden von HID++-Befehlen, nicht über den Agenten. kvm_daemon_windows.py vermeidet sie alle, indem es die Named Pipe des Agenten verwendet.

Get-PnpDeviceProperty -InstanceId "<instance_id>" -KeyName DEVPKEY_Device_HardwareIds
# Look for UP:FF43_U:0202

Send: {0x11, 0x00, 0x00, 0x0D, 0x18, 0x14, ...}  (20 bytes)
Read: response byte 4 = feature index

Getestete Versionen

Das Drahtprotokoll und die Kern-API-Pfade (/devices/list, /change_host/<id>/host) waren stabil. Das Neukoppeln von Geräten hat HID-Pfade und Collection-Nummern beeinträchtigt, aber das IPC-Protokoll selbst war nicht betroffen.

Haftungsausschluss

Dieses Projekt dient ausschließlich Ausbildungs- und Forschungszwecken. Es dokumentiert ein undokumentiertes, nicht unterstütztes Protokoll, das Logitech jederzeit ändern oder entfernen kann. Die Autoren übernehmen keine Verantwortung für Schäden, Datenverlust, unbrauchbare Geräte oder beeinträchtigte Funktionalität, die aus der Nutzung dieses Codes oder der Dokumentation resultieren. Nutzung auf eigene Gefahr.

Dieses Projekt steht in keiner Verbindung zu Logitech und wird nicht von Logitech unterstützt.

Lizenz

MIT