protocolo-ipc-de-logitech

Documentación con ingeniería inversa del protocolo IPC del agente Logi Options+. Permite el control programático de dispositivos Logitech multi-host (cambio de host, consultas de dispositivos) sin acceso HID en bruto, tanto en macOS como en Windows.

El protocolo no había sido documentado públicamente antes de este proyecto.

Problema

macOS bloquea el acceso HID en bruto a dispositivos de entrada Bluetooth a nivel de kernel. Ningún permiso, entitlement o truco lo evita. El agente Logi Options+ tiene entitlements firmados por Apple (com.apple.security.device.bluetooth) que le otorgan acceso HID Bluetooth. Este proyecto se comunica con el agente a través de su canal IPC.

Archivos

Uso

Mac

python3 switch_to_windows.py 0        # Cambiar al host 0 (DisplayPort)
python3 switch_to_windows.py 1        # Cambiar al host 1 (HDMI)
python3 switch_to_windows.py --dry-run 0  # Mostrar lo que sucedería

Requiere Logi Options+ en ejecución y m1ddc instalado (brew install m1ddc).

Windows

# Iniciar el oyente de teclas rápidas AHK (se ejecuta en la bandeja del sistema, sin consola)
# Requiere AutoHotkey v2: winget install AutoHotkey.AutoHotkey
start kvm.ahk

# O cambiar directamente desde la línea de comandos
python kvm_daemon_windows.py --switch 1

# Mostrar dispositivos descubiertos y teclas rápidas configuradas sin cambiar
python kvm_daemon_windows.py --dry-run

Requiere Logi Options+ en ejecución. Instalar dependencias: pip install pywin32.

El script AHK escucha Win+1/2/3 y llama a kvm_daemon_windows.py --switch N para cada uno. El script Python descubre los dispositivos automáticamente desde el agente (sin IDs de dispositivos ni rutas HID fijas). Edite kvm_config.ini para configurar teclas rápidas y valores de entrada DDC/CI del monitor.

Protocolo

El agente escucha en:

• macOS: Socket de dominio Unix en /tmp/logitech_kiros_agent-<hash>
• Windows: Named pipe en \\.\pipe\logitech_kiros_agent-<hash>

Mismo protocolo alámbrico en ambas plataformas. Formato de trama binaria:

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

Cambiar un dispositivo a un host diferente:

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

El payload es un campo google.protobuf.Any serializado como JSON en línea con una anotación @type. El agente utiliza un analizador JSON estricto de protobuf; los campos desconocidos causan INVALID_MESSAGE_RECEIVED.

Las solicitudes usan msg_id (snake_case). Las respuestas usan msgId (camelCase). Los verbos son cadenas: "GET", "SET", "SUBSCRIBE", "BROADCAST".

Consulte logi-options-ipc-reverse-engineering.md para la documentación completa del protocolo.

Manejo de errores del IPC

Para automatización de larga duración, reconectar en BrokenPipeError y redescubrir la ruta del socket/pipe.

Problemas comunes de HID++ en Windows

Estos aplican al enviar comandos HID++ directamente, no a través del agente. kvm_daemon_windows.py los evita todos al usar el named pipe del agente.

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

Enviar: {0x11, 0x00, 0x00, 0x0D, 0x18, 0x14, ...}  (20 bytes)
Leer: byte 4 de respuesta = índice de funcionalidad

Versiones probadas

El protocolo alámbrico y las rutas principales de la API (/devices/list, /change_host/<id>/host) se han mantenido estables. El reemparejamiento del dispositivo rompió las rutas HID y los números de colección, pero el protocolo IPC en sí no se vio afectado.

Descargo de responsabilidad

Este proyecto es solo para fines educativos y de investigación. Documenta un protocolo no documentado y no soportado que Logitech puede cambiar o eliminar en cualquier momento. Los autores no son responsables de ningún daño, pérdida de datos, dispositivos inutilizados o funcionalidad rota resultante del uso de este código o documentación. Úselo bajo su propio riesgo.

Este proyecto no está afiliado ni respaldado por Logitech.

Licencia

MIT