OpenLogi CLI 实战指南从设备清单到 HID 冒烟测试的完整命令手册【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogiOpenLogi 是一个用 Rust 编写的、面向 Logitech HID 外设的原生本地优先替代方案除 GUI 之外还提供了一个功能完整的命令行工具openlogi。本指南以 docs/USAGE.md 为核心系统讲解 CLI 的每一条命令——从查看配对设备、预取设备渲染资源到对真实硬件执行 DPI、SmartShift、RGB 灯光等 HID 读写回环冒烟测试并深入对应源码验证其工作机制。读完本文你将能熟练使用 CLI 完成设备排查、能力探测与写入链路验证并理解OPENLOGI_LOG、OPENLOGI_ASSETS等关键环境变量的作用。openlogi 命令总览openlogi的可执行入口是一个极薄的包装crates/openlogi/src/main.rs直接调用openlogi_cli::run()而完整的命令树与参数解析都集中在crates/openlogi-clicrate 中。从源码结构看CLI 目前包含 7 大类子命令见 crates/openlogi-cli/src/cmd/mod.rs子命令用途openlogi list列出已配对的 HID 设备默认子命令openlogi backlight读取或持久设置键盘背光HID 0x1982openlogi snapshot从 Logitech 摄像头抓取一帧保存为 PNGopenlogi camera读写摄像头设备级 UVC 图像控制项openlogi assets sync从最快的可用镜像预取设备渲染图openlogi diag sub对真实设备执行 HID 写路径冒烟测试openlogi light检查与控制独立式 Logitech 灯如 Litra本文聚焦 USAGE.md 中约定的核心用法即list、assets sync与diag系列。默认子命令与日志控制运行openlogi时不带任何子命令默认等价于openlogi list。这一点由 crates/openlogi-cli/src/lib.rs 保证Cli::parse()解析出cmd: OptionCommand为None时自动补上Command::List并有对应的单元测试bare_invocation_has_no_subcommand锁定该行为。日志输出写到 stderr等级由环境变量OPENLOGI_LOG控制未设置时默认info见 crates/openlogi-cli/src/lib.rsOPENLOGI_LOGdebug openlogi list由于日志走 stderr、正常结果走 stdout脚本解析 stdout 时不会被调试信息污染。openlogi list查看配对设备openlogi list # paired devices: slot, codename, kind, online, battery这是最常用的命令输出每个接收器receiver、配对设备以及 Logitech UVC 摄像头。单个设备的行格式为slot N ● codename (kind, wpidxxxx, batteryxx% level (status))其中slot设备在接收器上的配对槽位号●/○实心圆点表示在线online空心表示离线codename设备型号名缺失时显示Unknown devicekind设备类型如mouse、keyboard由枚举小写化而来wpid无线产品 ID缺失时显示wpid?battery电量百分比与充放电状态缺失时显示battery—。以上字段的渲染逻辑定义在 crates/openlogi-cli/src/cmd/list.rs并有完整单元测试如battery42% low (discharging)、离线设备使用空心圆点。list还有一个对脚本友好的特性当扫描成功但没有任何设备时进程以退出码2结束常量NOTHING_FOUND与真正的枚举失败区分开方便脚本判断没有硬件而不是出错了crates/openlogi-cli/src/cmd/list.rs。数据来源优先读取运行中的 Agentlist的数据并非总是自己枚举硬件当本机存在运行中的 OpenLogi Agent 时它会通过 IPC 请求一份快照因为 Agent 才是真正持有设备权限的进程其清单与 GUI 一致且不会重复打开同一批 HID 节点。只有在 Agent 不可达无监听、握手超时、协议版本不匹配等时才回退为当前进程直接枚举并把数据来源说明写到 stderrcrates/openlogi-cli/src/cmd/list.rs。如果列表为空命令会输出排查提示例如macOS 上先退出 Logi Options两者会争夺 HID 访问权、蓝牙直连设备需要授予输入监控Input Monitoring权限、当前 hidpp 版本仅识别 Logi Bolt 接收器PID 0xC548等crates/openlogi-cli/src/cmd/list.rs。openlogi assets sync预取设备渲染资源openlogi assets sync # pre-fetch device renders from the fastest available mirrorGUI 在展示设备时需要配套的渲染图与元数据hero 图、侧面图、颜色变体等。assets sync把这些文件预先拉取到openlogi-desktopcrate 的资源目录这样执行cargo bundle打包时就能直接带上典型工作流是openlogi assets sync cargo bundle --release见 crates/openlogi-cli/src/cmd/assets/sync.rs。三镜像并发探测与统一来源默认情况下同步会并发探测三个镜像第一个返回有效目录index.json的镜像为该次同步的唯一资源来源见 crates/openlogi-assets/src/source.rs生产源assets.openlogi.org与 npm 发布版本对应的 Cloudflare Pages 分支别名如v0-1-0.openlogi-assets.pages.dev固定的 jsDelivr npm 发布目录logi-assets/catalog0.1.0。当三个源全部不可用时会合并报告各自的错误crates/openlogi-assets/src/error.rs。如果你希望跳过自动选源改用单一固定资源源有两种等价方式openlogi assets sync --base https://assets.openlogi.org # 或通过环境变量 OPENLOGI_ASSETShttps://assets.openlogi.org openlogi assets sync--base与OPENLOGI_ASSETS由同一参数声明绑定#[arg(long, env OPENLOGI_ASSETS)]见 crates/openlogi-cli/src/cmd/assets/sync.rs。同步过程细节同步逻辑会为每个设备 depot 建立目录并按清单拉取两类文件基线文件热区元数据core_metadata.json/metadata.json、manifest 与 hero 渲染front_core.png/front.png缺失时会打印 WARN可选资产side.png/side_core.png侧面图以及front_ext*/side_ext*颜色变体只有清单列出时才拉取。已存在的文件通过 sha256 比对判断是否为缓存命中FetchOutcome::CacheHit从而跳过重复下载同时会清理清单中已不存在的孤儿 depot 目录保证 bundle 与注册表一致。最终输出done: N fetched, M cache-hit, X MB total under outcrates/openlogi-cli/src/cmd/assets/sync.rs。目标目录默认是crates/openlogi-desktop/assets可通过--out dir修改。openlogi diag真实硬件冒烟测试diag系列的命令定位非常明确诊断而非持久配置——它们不读写config.toml也不与 GUI 通信全部通过openlogi_hid的同一套 API 直接驱动硬件。因此一个diag全绿意味着 GUI 的写路径在当前主机上也是通的见 crates/openlogi-cli/src/cmd/diag.rs。目前提供 7 个子命令crates/openlogi-cli/src/cmd/diag.rs子命令行为关键 HID 特性diag features导出设备上报的完整 HID 特性表与固件实体特性遍历0x0000/0x0003 等diag controls导出可重编程按键CID与能力标志0x1b04 ReprogControlsV4diag battery读取原始电量上报0x1004 / 0x1000diag dpi读 → 写 → 回读 → 恢复0x2201 / 0x2202diag smartshift切换模式 → 回读 → 切回0x2110 / 0x2111diag lighting RRGGBB为有线 RGB 键盘设置纯色0x8070 / 0x8081 / 0x8080diag wheel读取或设置滚轮上报分辨率0x2121设备选择规则与 --devicediag各子命令执行前需要选定目标设备选择顺序为crates/openlogi-cli/src/cmd/diag.rs若传了--device NAME选择名称包含该字符串不区分大小写的第一个在线设备否则若该子命令声明了必需特性如 DPI 需要 0x2201/0x2202选择特性表中暴露任一必需特性的第一个在线设备——这能避免在鼠标键盘同时在线时鼠标类诊断误选键盘否则选择第一个在线设备。当无设备匹配时错误信息会列出当前所有在线设备并提示使用--device明确指定。多个设备配对的场景如蓝牙直连的鼠标和键盘各自独立枚举强烈建议显式传--device。diag dpiDPI 读写回环openlogi diag dpi # read → write → read-back → restore DPI (smoke test)执行流程crates/openlogi-cli/src/cmd/diag/dpi.rs读取 DPI 能力当前值 支持的 DPI 列表≤12 个值时逐值列出更多值时以min..max (step ≈ N, M values)区间汇总未传--target时自动选取与当前值相邻的一个测试目标设备支持的 DPI 少于两个时会要求显式传--target写入目标 DPI回读验证若设备将目标吸附到另一个受支持的值会打印 note 而不报错恢复原始 DPI输出✓ DPI round-trip OK。--target N必须是设备上报列表中的值--device NAME用于指定设备。任何写了没生效或回读值不在支持列表的情况都会以错误退出。diag smartshift滚轮模式切换回环openlogi diag smartshift # toggle SmartShift and restore (smoke test)针对配备 SmartShift 滚轮自动在自由滚动/棘轮间切换的设备流程为读取当前模式与灵敏度 → 切换模式 → 回读确认模式确实改变 → 再切回恢复原状crates/openlogi-cli/src/cmd/diag/smartshift.rs。两个额外参数--leave-flipped切换后不恢复方便肉眼验证滚轮确实翻转与--sensitivity互斥--sensitivity N不切换模式而是设置自动解除棘轮的灵敏度。N取值范围 1–255代表滚轮自由转动的速度阈值数值越低越灵敏常见区间 10–40255表示永久棘轮仅在棘轮模式下有意义0会被拒绝——设备把 0 视为无变化crates/openlogi-cli/src/cmd/diag/smartshift.rs。设置灵敏度时若模式意外改变或回读值不一致命令会直接报错退出。diag features导出完整 HID 特性表openlogi diag features # dump every HID feature the active device reports当默认封装如 DPI 用 0x2201、SmartShift 用 0x2111不被某台设备识别时用它找出设备真正暴露的特性 IDcrates/openlogi-cli/src/cmd/diag/features.rs。输出包含每个在线设备的特性表idx / id / ver / flags四列flags 列出obsolete、hidden、engineering、manufacturing-deactivatable、compliance-deactivatable等已知标志未文档化的位则以unknown0x..原始掩码呈现固件实体信息每个固件镜像的类型、版本号如MPM17.00_B0008、传输 PID、[active]标记与可选的 extra 版本字节无法描述的实体也会以unreadable (原因)形式报告而不是丢弃。这些格式在 crates/openlogi-cli/src/cmd/diag/features.rs 有大量单元测试锁定例如零 PID 的休眠实体仍如实打印、未知特性位以掩码展示。diag controls导出可重编程按键openlogi diag controls # dump reprogrammable controls and capability flags读取 HID 0x1b04ReprogControlsV4上报的可重编程按键输出cid / task / flags / capabilities四列能力列包括divertable可分流/拦截、raw-xy、force-raw-xy、analytics-events、raw-wheel等标志crates/openlogi-cli/src/cmd/diag/controls.rs。这组 CID 是后续按键重映射、手势绑定等功能的来源排查某按键为什么不能映射时首先看它是否标记为divertable。diag lighting有线 RGB 键盘纯色测试openlogi diag lighting ff0000 # solid colour for a wired RGB keyboard (any RRGGBB hex)将一台有线直连 USBLogitech RGB 键盘设置为纯色。颜色参数为 6 位 RRGGBB 十六进制如ff0000为红色可选#前缀非法输入非 6 位十六进制、含非十六进制字符会在触碰硬件前就被拒绝见 crates/openlogi-cli/src/cmd/diag/lighting.rs 与颜色校验测试。目标设备通过 VID/PID 直接匹配没有接收器 UID 的直连设备即有线键盘Bolt/Unifying 接收器下的鼠标会被跳过因此不绑定单一型号。可用--device NAME在多台有线键盘间选择。HID 灯光路径由--method控制默认auto依次回退effects强制 0x8070 ColorLedEffects板上固定效果覆盖perkey强制 0x8080 PerKeyLighting逐键原始数据流perkeyv2强制 0x8081 PerKeyLighting2区域寻址的新一代实现。例如openlogi diag lighting 00ff00 --method perkey结合 GUI 与配置文件的定位CLI 是 OpenLogi可脚本化能力的体现见 README.md 中 Script it 一节。与 GUI 一样持久化配置是一份纯文本 TOML位于$XDG_CONFIG_HOME/openlogi/config.tomlLinux/macOS或%USERPROFILE%\.config\openlogi\config.tomlWindows完整示例见 docs/config.example.toml字段说明见 docs/CONFIGURATION.md。值得注意的是diag系列刻意不触碰这份配置——诊断命令与持久配置完全解耦避免冒烟测试意外改变用户设置。小结openlogiCLI 覆盖了从日常查看list、资源预取assets sync到硬件级验证diag全系列的完整链路。它始终与 GUI 共享同一套 HID 写路径因此既适合日常脚本集成如用退出码区分无设备与枚举失败也是排查设备兼容性、抓取特性表、验证写链路是否畅通的首选工具。安装与配置的完整说明请参见 README.md。【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考