logitech-ipc-protocol

Logi Options+ 代理 IPC 协议的逆向工程文档。支持在 macOS 和 Windows 上通过程序控制 Logitech 多主机设备（主机切换、设备查询），无需原始 HID 访问。

此协议此前从未被公开记录过。

问题

macOS 在内核层面禁止对蓝牙输入设备的原始 HID 访问。没有权限、授权或黑客手段可以绕过。Logi Options+ 代理拥有苹果签名的授权（com.apple.security.device.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

# 启动 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 脚本自动从代理发现设备（无需硬编码设备 ID 或 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 注解。代理使用严格的 protobuf JSON 解析器；未知字段会导致 INVALID_MESSAGE_RECEIVED。

请求使用 msg_id（下划线命名法）。响应使用 msgId（驼峰命名法）。动词是字符串："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

发送: {0x11, 0x00, 0x00, 0x0D, 0x18, 0x14, ...}  (20 字节)
读取: 响应字节 4 = 特性索引

测试版本

线路协议和核心 API 路径（/devices/list、/change_host/<id>/host）保持稳定。设备重新配对会破坏 HID 路径和集合编号，但 IPC 协议本身未受影响。

免责声明

本项目仅用于教育和研究目的。它记录了一个未公开、不受支持的协议，Logitech 可随时更改或移除。作者不对因使用此代码或文档造成的任何损坏、数据丢失、设备损坏或功能失效负责。使用风险自负。

本项目与 Logitech 无关，也未获得 Logitech 的认可。

许可证

MIT