OpenLogi

命令行

使用 OpenLogi 命令行查询硬件、运行诊断,并通过本地 JSON API 自动化支持的设置。

OpenLogi v0.8.15 提供面向用户的硬件命令和版本化 JSON API。大多数硬件命令可以直接访问设备。openlogi backlight 和 openlogi api 命令只使用正在运行的 OpenLogi 代理。

运行命令

运行 openlogi --help 可以查看已安装的命令树。安装包和源码构建说明见安装。

不带子命令运行 openlogi 会执行 openlogi list。该命令列出已连接的接收器、已配对的 HID++ 设备和 Logitech 摄像头。它会优先使用正在运行的代理设备清单,然后回退到直接枚举硬件。扫描完成且未发现设备或摄像头时,退出码为 2。

命令结果
openlogi 或 openlogi list列出接收器、已配对的 HID++ 设备和 Logitech 摄像头。
openlogi assets sync下载本地软件包所需的资源。
openlogi --help输出命令和选项帮助。
openlogi --version输出 CLI 版本。

同步资源

openlogi assets sync 会并发探测自动资源镜像。第一个返回有效目录的镜像会提供本次同步的所有文件。该命令按 SHA-256 跳过未变化的文件,并删除目录中不存在的资源仓库。

使用 --base URL 或 OPENLOGI_ASSETS 可以指定单一资源源。--out DIR 可以更改目标目录。

openlogi assets sync
openlogi assets sync --base https://assets.example.invalid
OPENLOGI_ASSETS=https://assets.example.invalid openlogi assets sync

设置日志筛选器

OPENLOGI_LOG 为 CLI、桌面应用和代理设置 tracing 筛选器。它接受 EnvFilter 指令。未设置时,默认值为 info。日志写入 stderr,因此 JSON API 输出保留在 stdout。

OPENLOGI_LOG=debug openlogi list
OPENLOGI_LOG=hidpp=trace,openlogi_agent=debug openlogi api status

硬件命令

以下命令在 JSON API 之外访问硬件。如果可以,大多数命令会选择第一个兼容设备。如果有多个设备匹配,使用对应的 --device 或 --camera 选择器。openlogi backlight 的选择规则更严格,见键盘背光。

命令用途
openlogi backlight [--device NAME]读取键盘的 HID++ 0x1982 背光状态。
openlogi backlight [--device NAME] [status|off|on|auto on|auto off|level N|battery-saving on|battery-saving off]持久更改兼容键盘的背光控制。
openlogi snapshot [PATH] [--camera ID]从 Logitech 摄像头捕获一帧并写入 PNG。默认路径为 snapshot.png。
openlogi camera [--camera ID] [get]显示 Logitech 摄像头的 UVC 控制范围和当前值。
openlogi camera [--camera ID] set CONTROL VALUE写入列出的 UVC 图像控制或自动控制开关。
openlogi light list列出支持的独立灯和控制项。
openlogi light status|on|off [--device NAME]读取或更改一盏独立灯。
openlogi light brightness --percent 0..100|--lumens N [--device NAME]设置标准化亮度或原生流明。
openlogi light temperature --kelvin N [--device NAME]设置色温。
openlogi fixture contribute通过可恢复的向导创建保护隐私的 fixture。
openlogi fixture record case|profile为 fixture 捕获命名读取或代理语义状态。
openlogi fixture verify严格验证完整的 fixture 目录。

camera set 接受以下控制项名称:zoom、pan、tilt、focus、exposure、power_line_frequency、low_light_compensation、brightness、contrast、saturation、sharpness、gain、backlight_compensation、white_balance、tint、focus_auto、exposure_auto 和 white_balance_auto。

硬件命令可以更改设备状态。fixture 命令是维护工具。直接发现 fixture 时可能启用接收器通知,而且不会恢复这些标志。

键盘背光

openlogi backlight 的每次读取和更改都通过正在运行的 OpenLogi 代理完成。代理必须与 CLI 使用同一个 OPENLOGI_PROFILE,并接受 CLI 的协议版本。该命令不会直接打开键盘,也不会启动代理。如果没有兼容的代理响应,命令会报错并停止。

该命令从代理的设备清单中选择键盘:

  • --device NAME 按设备名称的一部分匹配,不区分大小写。该文本必须只匹配一台在线 HID++ 设备。
  • 不带 --device 时,必须恰好有一台在线设备已测得背光支持。如果代理还没有测得某台键盘的支持情况,用 --device 选择该键盘。
  • 如果设备清单尚未就绪、设备没有代理路由,或选择有歧义,命令会在任何读写之前停止。已知不支持背光的设备也会被拒绝。

代理写入键盘后会读回状态。CLI 打印读回结果后才报告成功,桌面应用中已打开的背光(Backlight)卡片也会显示新状态。如果代理在更改过程中超时或断开,结果为未确认。命令不会重试。再次发送更改前,先运行 openlogi backlight status。

此行为适用于 v0.8.17 之后的版本。更早的版本在没有代理运行时会直接打开键盘,并选择第一个匹配的设备。

硬件诊断

openlogi diag 运行直接 HID++ 诊断。它不会更新 config.toml,也不会使用桌面应用。在 macOS 上,诊断命令会在打开设备前为 CLI 二进制文件请求「输入监控」权限。

命令行为
diag features转储每台在线 HID++ 设备的功能表和固件实体。
diag controls [--device NAME]转储 HID++ 0x1b04 可重编程控制项和能力标志。
diag battery [--device NAME]输出 0x1004、0x1000 或 0x1F20 的原始电池报告。
diag dpi [--target DPI] [--device NAME]读取 DPI,写入测试值,回读,然后恢复原值。
diag pointer-speed [--target RAW] [--device NAME]测试 HID++ 0x2205 指针移动缩放,然后尝试恢复。
diag smartshift [--leave-flipped|--sensitivity N|--torque PERCENT] [--device NAME]切换 SmartShift,设置释放阈值,或设置滚轮扭矩。
diag lighting RRGGBB [--device NAME] [--method auto|effects|perkey|perkeyv2]将在线 RGB 设备设置为单一纯色。
diag wheel [--resolution low|high] [--device NAME]读取或设置 HID++ 0x2121 滚轮报告分辨率。

诊断命令用于验证写入路径,而不是日常偏好设置。diag dpi 会在测试成功后恢复原值。未指定 --leave-flipped 时,普通 diag smartshift 会恢复原始模式。其他诊断写入可能保留在设备中。

测试指针移动缩放

diag pointer-speed 测试 HID++ 0x2205 指针移动缩放。--device NAME 按名称的大小写无关子串选择设备。--target RAW 接受非零的原始 8.8 定点值,其中 256 是 1×。

未指定 --target 时,命令会将当前原始值减半。如果当前值是 1,命令会将其加倍。固件可能接受极端值而不裁剪。

诊断命令会写入测试值。它会先尝试恢复并验证原始值,然后再判断测试写入结果。即使测试写入失败,它也会尝试恢复。恢复错误表示 OpenLogi 无法确认原始缩放值。

测试 SmartShift 扭矩

diag smartshift --torque PERCENT 会写入 1 至 100 的滚轮反馈强度。只有设备公布 HID++ 0x2111 的 TUNABLE_TORQUE 时,这个选项才可用。该命令会保留当前 SmartShift 模式和自动释放阈值。

--sensitivity N 接受 1 至 255。1 至 254 设置自动释放阈值。值为 255 时,如果滚轮已处于棘轮模式,则选择永久棘轮模式。命令帮助指定的 --leave-flipped、--sensitivity 和 --torque 互斥。

JSON 自动化 API

openlogi api 是用于脚本和启动器的本地 JSON 接口。它需要正在运行且协议兼容的 OpenLogi 代理。它不会启动代理、直接打开硬件,或回退到诊断命令。

前提条件

调用 API 前,必须正常启动 OpenLogi。如果 API 返回 version_mismatch,使用版本匹配的 CLI 和代理构建。

先运行 openlogi api devices。复制一个完整且非 null 的 id,并把它作为一个带引号的 --device 值传入。设备操作要求 inventory: "ready"。只有设备清单已就绪且 devices 为空,才表示未发现外设。

openlogi api status
openlogi api devices
openlogi api dpi --device "$DEVICE_ID"

命令和响应字段

每个成功的命令都会将下表字段放入 data。实测值为 null 表示代理没有该实测值。此 API 不包括摄像头。

命令data 字段
statusagent_version、inventory、accessibility_granted、input_monitoring_granted、hook_installed、hid_open_failures、launch_at_login、virtual_keyboard
devicesinventory;devices 是包含 id、name、kind、online、battery、capabilities 和 light_capabilities 的数组
dpi --device ID [--set DPI]device、persistence、current、supported
smartshift --device ID [--mode free|ratchet] [--auto-disengage N]device、persistence、mode、auto_disengage、tunable_torque
fn-lock --device ID [--set on|off]device、persistence、fn_lock、default_fn_lock
os-layout --device ID --set on|off --savedevice、persistence、keep_os_layout
report-rate --device ID [--set HZ]device、persistence、current、supported
easy-switch --device ID [--channel N --name TEXT]device、persistence、current_channel、can_rename、channels

status.virtual_keyboard 为 active 时,agent 通过 macOS 虚拟 HID 键盘输入合成按键;为 unavailable 时,macOS 上改用软件按键事件;Windows 和 Linux 上为 unsupported。0.8.17 之前的 agent 不返回这个字段。

smartshift.tunable_torque 是滚轮最大力度的 1 至 100 百分比,或 null。fn-lock.default_fn_lock 是布尔值或 null。报告率值以赫兹为单位,并适用于当前连接。详见报告率。

每个 easy-switch.channels 项都有 channel、paired、connection、name、name_max_len 和 os。通道从 1 开始编号。connection 的值是 unknown、unifying、usb、bluetooth 或 bolt。详见 Easy-Switch。

更改设置

读取命令不会写入硬件。添加设置参数可以立即更改设备。

openlogi api dpi --device "$DEVICE_ID" --set 1200
openlogi api smartshift --device "$DEVICE_ID" --mode free
openlogi api smartshift --device "$DEVICE_ID" --mode ratchet --auto-disengage 255
openlogi api fn-lock --device "$DEVICE_ID" --set on
openlogi api os-layout --device "$DEVICE_ID" --set on --save
openlogi api report-rate --device "$DEVICE_ID" --set 1000 --save
openlogi api easy-switch --device "$DEVICE_ID" --channel 2 --name "Work laptop"

DPI 值必须出现在 supported 中。OpenLogi 会拒绝其他值,而不会取整。报告率必须出现在当前连接的报告率列表中。

SmartShift 会保留命令中省略的字段。auto_disengage 接受 1 至 254,或接受用于永久棘轮的 255。使用 --mode ratchet --auto-disengage 255 可以禁用自动释放。使用 --save 时,SmartShift 阈值必须为 8 至 255。

fn-lock --set on 会让功能键直接发送 F1 至 F12。off 使用键帽标注的媒体功能。os-layout 是代理设置,因此需要同时指定 --set 和 --save。使用 on 时,代理会让兼容键盘保持主机操作系统的键盘布局。使用 off 时,OpenLogi 不会更改键盘布局。

重命名 Easy-Switch 需要同时指定 --channel 和 --name。写入前会删除名称两侧的空白字符。设备会存储名称,因此 Easy-Switch 会拒绝 --save,并始终返回 persistence: "not_saved"。

保存偏好

将 --save 添加到明确的 DPI、SmartShift、Fn 锁定或报告率更改中,可以把已验证的设置保存到 config.toml。保存需要已探测的物理设备身份。OpenLogi 从不将 API 路由 ID 用作配置键。

保存只编辑选定的设置,并保留无关偏好和注释。按连接的 DPI 或 SmartShift 覆盖会返回 link_override。OpenLogi 不会保存会被该覆盖取代的设备默认值。完整文件参考见配置。

硬件写入、配置保存和代理重新加载是独立步骤。后续失败不会撤销硬件写入。保存错误中的 error.persistence: "not_saved" 表示 OpenLogi 未保存文件。error.persistence: "saved" 表示 OpenLogi 已保存文件,但重新加载失败或结果未知。

JSON 外层结构和退出码

参数解析完成后,每次 API 调用会向 stdout 写入一个 JSON 对象和一个换行。成功和运行时错误使用相同的外层结构。

{"schema_version":1,"ok":true,"data":{"inventory":"ready","devices":[]}}
{"schema_version":1,"ok":false,"error":{"code":"inventory_not_ready","message":"agent inventory is not ready; no device operation was attempted"}}
退出码含义
0成功。ok 为 true。
1运行时失败。检查 error.code。
2参数无效。Clap 会将诊断信息写入 stderr。

脚本必须检查 schema_version 和 ok。脚本必须忽略未知对象字段,并将未知错误码视为失败。解析 error.code,不要解析说明性的 error.message。

稳定错误码包括 agent_unavailable、handshake_failed、version_mismatch、timeout、disconnected、inventory_not_ready、device_not_found、device_offline、ambiguous_device、unsupported_feature、invalid_value、readback_mismatch、device_error、identity_unavailable、link_override、config_error、config_conflict、config_busy、config_save_failed、config_reload_failed 和 config_reload_unknown。

--help 和 --version 输出文本,而不是 JSON。stdout 写入失败时,无法输出 JSON 外层结构。

设备 ID 和隐私

API 设备 ID 是当前连接路由的不透明标识符。设备重连或更新 OpenLogi 后,重新获取 ID。不要构造或解析 ID,也不要使用数组位置或设备名称作为地址。

缺少路由时,ID 为 null。重复 ID 会保留在 devices 中,使用该 ID 的操作会返回 ambiguous_device。ID 可能包含硬件身份信息,因此必须仅在本地使用,并在分享输出前删除它们。

设备响应不包括配对密钥、应用历史记录或型号序列号。电池或能力为 null 不表示电量为零或功能不受支持。

本页目录