logitech-ipc-protocol

Документация, полученная в результате реверс-инжиниринга IPC-протокола агента Logi Options+. Обеспечивает программное управление мульти-хостовыми устройствами Logitech (переключение между хостами, запросы информации об устройстве) без прямого доступа к HID, как на macOS, так и на Windows.

Данный протокол ранее не был публично задокументирован.

Проблема

macOS блокирует прямой HID-доступ к Bluetooth-устройствам ввода на уровне ядра. Никакие разрешения, антлиты или хаки это не обходят. Агент Logi Options+ имеет подписанные Apple антлиты (com.apple.security.device.bluetooth), предоставляющие ему Bluetooth HID-доступ. Этот проект взаимодействует с агентом через его 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

# Start the AHK hotkey listener (runs in system tray, no console)
# Requires AutoHotkey v2: winget install AutoHotkey.AutoHotkey
start kvm.ahk

# Or switch directly from the command line
python kvm_daemon_windows.py --switch 1

# Show discovered devices and configured hotkeys without switching
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: Именованный канал \\.\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 избегает всех этих проблем, работая через именованный канал агента.

Get-PnpDeviceProperty -InstanceId "<instance_id>" -KeyName DEVPKEY_Device_HardwareIds
# Ищите UP:FF43_U:0202

Send: {0x11, 0x00, 0x00, 0x0D, 0x18, 0x14, ...}  (20 байт)
Read: ответ, байт 4 = индекс функции

Протестированные версии

Проводной протокол и основные пути API (/devices/list, /change_host/<id>/host) остаются стабильными. Переспаривание устройств нарушало HID-пути и номера коллекций, но сам IPC-протокол не затрагивался.

Отказ от ответственности

Этот проект предназначен только для образовательных и исследовательских целей. Он документирует незадокументированный, неподдерживаемый протокол, который Logitech может изменить или удалить в любое время. Авторы не несут ответственности за любой ущерб, потерю данных, повреждение устройств или нарушение функциональности в результате использования этого кода или документации. Используйте на свой страх и риск.

Этот проект не связан с Logitech и не одобрен ею.

Лицензия

MIT