logitech-ipc-protocol

Documentation rétro-ingénierée du protocole IPC de l'agent Logi Options+. Permet un contrôle programmatique des périphériques multi-hôtes Logitech (changement d'hôte, requêtes sur les périphériques) sans accès HID brut, à la fois sur macOS et Windows.

Ce protocole n'a pas été documenté publiquement avant ce projet.

Problème

macOS bloque l'accès HID brut aux périphériques d'entrée Bluetooth au niveau du noyau. Aucune permission, entitlement ou astuce ne contourne cela. L'agent Logi Options+ possède des entitlements signés par Apple (com.apple.security.device.bluetooth) qui lui accordent l'accès Bluetooth HID. Ce projet communique avec l'agent via son canal IPC à la place.

Fichiers

Utilisation

Mac

python3 switch_to_windows.py 0        # Basculer vers l'hôte 0 (DisplayPort)
python3 switch_to_windows.py 1        # Basculer vers l'hôte 1 (HDMI)
python3 switch_to_windows.py --dry-run 0  # Afficher ce qui se passerait

Nécessite Logi Options+ en cours d'exécution et m1ddc installé (brew install m1ddc).

Windows

# Démarrer l'écouteur de raccourcis AHK (s'exécute dans la barre d'état système, sans console)
# Nécessite AutoHotkey v2 : winget install AutoHotkey.AutoHotkey
start kvm.ahk

# Ou basculer directement depuis la ligne de commande
python kvm_daemon_windows.py --switch 1

# Afficher les périphériques découverts et les raccourcis configurés sans basculer
python kvm_daemon_windows.py --dry-run

Nécessite Logi Options+ en cours d'exécution. Installer les dépendances : pip install pywin32.

Le script AHK écoute Win+1/2/3 et appelle kvm_daemon_windows.py --switch N pour chacun. Le script Python découvre automatiquement les périphériques depuis l'agent (aucun ID de périphérique ou chemin HID codé en dur). Modifiez kvm_config.ini pour configurer les raccourcis et les valeurs d'entrée DDC/CI du moniteur.

Protocole

L'agent écoute sur :

• macOS : socket de domaine Unix à /tmp/logitech_kiros_agent-<hash>
• Windows : tube nommé à \\.\pipe\logitech_kiros_agent-<hash>

Même protocole filaire sur les deux plateformes. Format de trame binaire :

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

Basculer un périphérique vers un autre hôte :

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

Le payload est un champ google.protobuf.Any sérialisé en JSON inline avec une annotation @type. L'agent utilise un analyseur JSON protobuf strict ; les champs inconnus provoquent INVALID_MESSAGE_RECEIVED.

Les requêtes utilisent msg_id (snake_case). Les réponses utilisent msgId (camelCase). Les verbes sont des chaînes : "GET", "SET", "SUBSCRIBE", "BROADCAST".

Voir logi-options-ipc-reverse-engineering.md pour la documentation complète du protocole.

Gestion des erreurs IPC

Pour une automatisation de longue durée, reconnectez-vous sur BrokenPipeError et redécouvrez le chemin du socket/tube.

Problèmes HID++ sous Windows

Ces points s'appliquent lors de l'envoi de commandes HID++ directement, pas via l'agent. kvm_daemon_windows.py les évite tous en passant par le tube nommé de l'agent.

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

Envoyer : {0x11, 0x00, 0x00, 0x0D, 0x18, 0x14, ...}  (20 octets)
Lire : réponse octet 4 = indice de la fonctionnalité

Versions testées

Le protocole filaire et les chemins d'API principaux (/devices/list, /change_host/<id>/host) ont été stables. Le réappariement des périphériques a cassé les chemins HID et les numéros de collection mais le protocole IPC lui-même n'a pas été affecté.

Avertissement

Ce projet est uniquement à des fins éducatives et de recherche. Il documente un protocole non documenté et non supporté que Logitech peut modifier ou supprimer à tout moment. Les auteurs ne sont pas responsables des dommages, pertes de données, périphériques rendus inutilisables ou fonctionnalités cassées résultant de l'utilisation de ce code ou de cette documentation. Utilisation à vos risques et périls.

Ce projet n'est pas affilié à Logitech ni approuvé par Logitech.

Licence

MIT