From 84277f9415f8548b87b2757fbf0f5667f7d7acf5 Mon Sep 17 00:00:00 2001 From: softmaxe <94467584+softmaxe@users.noreply.github.com> Date: Sat, 7 Nov 2026 22:27:43 +0800 Subject: [PATCH] feat: support Linux CLI battery queries with sudo --- Cargo.lock | 32 +++++++++++++++++++++++++ Cargo.toml | 7 ++++-- README.md | 56 +++++++++++++++++++++++++++++++++++++------- README.zh-CN.md | 27 ++++++++++++++++++--- src/hidpp.rs | 62 +++++++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 167 insertions(+), 17 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 739b795..3be32e3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2,6 +2,18 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "basic-udev" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "868a8681ed3a19fae3e302c705b1cabf5be53278cc8720a9b82e9805c9ab171d" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + [[package]] name = "cc" version = "1.4.4" @@ -18,6 +30,12 @@ version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" +[[package]] +name = "cfg_aliases" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" + [[package]] name = "find-msvc-tools" version = "0.1.11" @@ -37,9 +55,11 @@ version = "2.6.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "818c0e1d27887aaf76fe737042e27a66b796a7b099e6d2e1a72d106c2dff3fa6" dependencies = [ + "basic-udev", "cc", "cfg-if", "libc", + "nix", "pkg-config", "windows-sys", ] @@ -50,6 +70,18 @@ version = "0.2.189" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" +[[package]] +name = "nix" +version = "0.30.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6" +dependencies = [ + "bitflags", + "cfg-if", + "cfg_aliases", + "libc", +] + [[package]] name = "pkg-config" version = "0.3.34" diff --git a/Cargo.toml b/Cargo.toml index f731e00..4af5885 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,14 +2,17 @@ name = "gbat" version = "0.0.1" edition = "2021" -description = "Read Logitech GPW2 battery status on macOS" +description = "Read Logitech GPW2 battery status on macOS and Linux" license = "AGPL-3.0-only" repository = "https://github.com/softmaxe/gbat" homepage = "https://github.com/softmaxe/gbat" -[dependencies] +[target.'cfg(not(target_os = "linux"))'.dependencies] hidapi = { version = "2.6.7", features = ["macos-shared-device"] } +[target.'cfg(target_os = "linux")'.dependencies] +hidapi = { version = "2.6.7", default-features = false, features = ["linux-native-basic-udev"] } + # A one-shot CLI only pays for what it pages in, so trade build time for a # smaller binary: whole-program inlining, no unwinding tables, no symbols. This # cuts the binary by about a third; measured startup time is unchanged. diff --git a/README.md b/README.md index 54d95a1..9d190b6 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@
`gbat` reads the battery level and charging state of a Logitech G Pro Wireless 2 -on macOS, prints one line, and exits. +on macOS and Linux, prints one line, and exits. ```text Battery: 78% @@ -22,14 +22,15 @@ G HUB, Python, or a background process. ## Requirements -- macOS 11 Big Sur or later +- macOS 11 Big Sur or later, or Linux with hidraw and udev - A Logitech G Pro Wireless 2 connected through its LIGHTSPEED receiver or USB - A mouse that is awake when `gbat` runs ## Install The Homebrew package and GitHub release archive support Apple Silicon only, -with an `arm64` binary. +with an `arm64` binary. On Linux, [build from source](#build-from-source) and +[run battery queries with sudo](#linux-and-sudo). Raycast integration is macOS-only. Install with Homebrew: @@ -60,15 +61,22 @@ replace Apple code signing or notarization. ## Use -Run `gbat` with the mouse connected through its LIGHTSPEED receiver or USB: +Connect the mouse through its LIGHTSPEED receiver or USB. On macOS, run: ```sh gbat ``` +On Linux, run the binary with `sudo` (see [why sudo is needed](#linux-and-sudo)): + +```sh +sudo /path/to/gbat +``` + On success, the command writes one battery status line to stdout and exits with status `0`. On failure, it writes an error to stderr and exits with status `1`. -Run `gbat --version` to print the installed version without accessing the mouse. +Run `gbat --version` to print the installed version without accessing the mouse; +this works without `sudo` on both platforms. An idle mouse may take longer to answer while its radio wakes. If the receiver reports that the mouse is offline, turn it on or move it, then retry. @@ -119,7 +127,12 @@ when needed. Then clone and build: git clone https://github.com/softmaxe/gbat.git cd gbat cargo build --release --locked -./target/release/gbat +``` + +Run the built binary on macOS with `./target/release/gbat`, or on Linux with: + +```sh +sudo ./target/release/gbat ``` To keep the binary outside the build directory: @@ -130,6 +143,31 @@ cp target/release/gbat "$HOME/.local/bin/gbat" ``` Make sure `$HOME/.local/bin` is on `PATH` to run `gbat` from any directory. +On Linux, use `sudo "$HOME/.local/bin/gbat"`; `sudo` may use a different `PATH`. + +### Linux and sudo + +Use `sudo` for battery queries on Linux: + +```sh +sudo ./target/release/gbat +``` + +Linux exposes the receiver and mouse through `/dev/hidraw*`. These device nodes +are normally accessible only to root. Reading battery status requires opening +the appropriate node for both reading and writing: `gbat` sends a HID++ battery +query and receives the reply. Without sufficient permissions, opening the +device fails with `Permission denied (os error 13)`. + +`sudo` grants the CLI the access it needs for that invocation. `gbat` does not +install udev rules, change device permissions or group membership, or configure +passwordless sudo. Build with `cargo` as your regular user and use `sudo` only +when running the binary to read the battery. `--version` needs no elevation. + +The Linux CLI uses the native hidraw backend. It does not need `libudev-dev`, +`libusb`, or a separately installed HIDAPI library. A C compiler and linker are +still needed to build Rust dependencies (`sudo apt install build-essential` +on Ubuntu/Debian). ## Troubleshooting @@ -138,7 +176,8 @@ Make sure `$HOME/.local/bin` is on `PATH` to run `gbat` from any directory. | `No responsive Logitech HID++ interface found` | Connect the receiver or USB cable, wake the mouse, and retry. | | `The receiver reports no connected mouse` | The mouse is offline. Turn it on or move it, and retry. | | `Could not read battery level` | The mouse may have gone offline during the read, or its battery response could not be used. Move it and retry. | -| `Could not initialize HID access` or `Could not read battery level: HID access failed` | Run `gbat` once from Terminal and approve any macOS permission prompt. `sudo` is not normally required. | +| `Could not initialize HID access` or `Could not read battery level: HID access failed` on macOS | Run `gbat` once from Terminal and approve any macOS permission prompt. `sudo` is not normally required on macOS. | +| `Permission denied (os error 13)` on Linux | Run `sudo /path/to/gbat`; see [Linux and sudo](#linux-and-sudo). | | `gbat binary not found` in Raycast | Install or build `gbat`, or set `GBAT_BINARY` in the script to its executable path. | | `Battery: 100%` without `(charging)` | A full mouse may stop active charging. This is expected. | | macOS blocks the binary | Open System Settings > Privacy & Security and choose Open Anyway for `gbat`. | @@ -152,7 +191,8 @@ xattr -dr com.apple.quarantine "$(brew --prefix gbat)" ## How it works -`gbat` opens Logitech HID++ interfaces in shared mode. It checks receiver device +`gbat` opens Logitech HID++ interfaces in shared mode on macOS and through hidraw +on Linux. It checks receiver device indices `1` through `6` and the direct USB index `0xFF`, trying `1` and `0xFF` first. It uses the first interface and device index that reports a supported battery feature. It filters only by Logitech's vendor ID, so with several diff --git a/README.zh-CN.md b/README.zh-CN.md index d8d95fa..0aecd84 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -9,7 +9,8 @@ 简体中文 -`gbat` 在 macOS 上读取 Logitech G Pro Wireless 2 鼠标的电量和充电状态,输出一行结果后退出。 +`gbat` reads Logitech G Pro Wireless 2 battery status on macOS and Linux, prints +one line, and exits. ```text Battery: 78% @@ -20,12 +21,17 @@ Battery: 42% (charging) ## 系统要求 -- macOS 11 Big Sur 或更高版本 +- macOS 11 Big Sur or later, or Linux with hidraw and udev - 通过 LIGHTSPEED 接收器或 USB 连接的 Logitech G Pro Wireless 2 - 运行 `gbat` 时鼠标处于唤醒状态 ## 安装 +On Linux, build the CLI from source and +[run battery queries with sudo](README.md#linux-and-sudo). +Linux builds do not require `libudev-dev` or a separately installed HIDAPI library. +Homebrew packages, release archives, and Raycast integration remain macOS-only. + Homebrew 软件包和 GitHub Release 归档仅提供 Apple Silicon 的 `arm64` 可执行文件。 使用 Homebrew 安装: @@ -56,9 +62,18 @@ Release 可执行文件没有 Apple Developer ID 签名,也未经过 Apple 公 通过 LIGHTSPEED 接收器或 USB 连接鼠标,然后运行: ```sh +# macOS gbat +# Linux +sudo /path/to/gbat ``` +Linux normally restricts `/dev/hidraw*` to root. Battery reads require read/write +access to send a HID++ query and receive its reply. Run the binary with `sudo` +for each battery query; `gbat --version` works without `sudo`. The CLI does not +install udev rules or change device permissions. See +[Linux and sudo](README.md#linux-and-sudo) for details. + 成功时,命令向 stdout 输出一行电池状态,退出码为 `0`。失败时,命令向 stderr 输出错误,退出码为 `1`。运行 `gbat --version` 可查看已安装的版本,不会访问鼠标。 鼠标闲置后,读取可能需要等待无线模块唤醒。如果接收器报告鼠标离线,打开鼠标电源或移动鼠标后重试。 @@ -97,7 +112,10 @@ export GBAT_BINARY="/path/to/gbat" git clone https://github.com/softmaxe/gbat.git cd gbat cargo build --release --locked +# macOS ./target/release/gbat +# Linux +sudo ./target/release/gbat ``` 如需将可执行文件保存在构建目录之外: @@ -109,6 +127,8 @@ cp target/release/gbat "$HOME/.local/bin/gbat" 确认 `$HOME/.local/bin` 已加入 `PATH`,即可在任意目录运行 `gbat`。 +On Linux, run `sudo "$HOME/.local/bin/gbat"`; `sudo` may use a different `PATH`. + ## 故障排查 | 问题 | 处理方法 | @@ -116,7 +136,8 @@ cp target/release/gbat "$HOME/.local/bin/gbat" | `No responsive Logitech HID++ interface found` | 连接接收器或 USB 线,唤醒鼠标后重试。 | | `The receiver reports no connected mouse` | 鼠标已离线。打开鼠标电源或移动鼠标后重试。 | | `Could not read battery level` | 鼠标可能在读取时离线,或返回了无法使用的电池响应。移动鼠标后重试。 | -| `Could not initialize HID access` 或 `Could not read battery level: HID access failed` | 从 Terminal 运行一次 `gbat`,并允许 macOS 弹出的权限请求。通常不需要 `sudo`。 | +| HID access errors on macOS | Run `gbat` from Terminal and approve any macOS permission prompt. `sudo` is not normally required on macOS. | +| `Permission denied (os error 13)` on Linux | Run `sudo /path/to/gbat`; see [Linux and sudo](README.md#linux-and-sudo). | | Raycast 提示 `gbat binary not found` | 安装或构建 `gbat`,或在脚本中将 `GBAT_BINARY` 设为它的可执行文件路径。 | | `Battery: 100%` 但没有 `(charging)` | 鼠标充满后可能停止主动充电,这是正常现象。 | | macOS 阻止运行 | 打开 System Settings > Privacy & Security,为 `gbat` 选择 Open Anyway。 | diff --git a/src/hidpp.rs b/src/hidpp.rs index 1fb9000..9711360 100644 --- a/src/hidpp.rs +++ b/src/hidpp.rs @@ -54,7 +54,17 @@ pub enum HidppError { impl fmt::Display for HidppError { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { match self { - Self::Hid(error) => write!(formatter, "HID access failed: {error}"), + Self::Hid(error) => { + write!(formatter, "HID access failed: {error}")?; + #[cfg(target_os = "linux")] + if permission_denied(error) { + write!( + formatter, + ". On Linux, read battery status with sudo: sudo /path/to/gbat." + )?; + } + Ok(()) + } Self::ShortResponse { minimum, actual } => write!( formatter, "short HID++ response: expected at least {minimum} bytes, got {actual}" @@ -71,6 +81,16 @@ impl From