diff --git a/README.md b/README.md index 98502c2..2e7ad27 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ 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 an access error | 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` | Run `gbat` once from Terminal and approve any macOS permission prompt. `sudo` is not normally required. | | `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`. | @@ -157,11 +157,16 @@ xattr -dr com.apple.quarantine "$(brew --prefix gbat)" `gbat` opens Logitech HID++ interfaces in shared mode. 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. There is no device selector for setups with multiple mice. +battery feature. It filters only by Logitech's vendor ID, so with several +Logitech HID++ devices connected it may read another mouse, keyboard, or +headset. There is no device selector. It reads `UNIFIED_BATTERY` at `0x1004` and falls back to `BATTERY_STATUS` at `0x1000` when the unified feature is unavailable, does not answer, or returns an -incomplete response. HID access errors and incomplete writes stop the read. +incomplete response. Once a battery feature is found, HID access errors and +incomplete writes stop the read. During discovery, an interface that fails is +skipped; its error is reported only if no other interface finds the mouse or +reports it offline. If neither feature yields a battery status, the command reports an error instead of inventing a `0%` reading. diff --git a/README.zh-CN.md b/README.zh-CN.md index 5e1b2aa..88b2f90 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -116,7 +116,7 @@ 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` 或访问错误 | 从 Terminal 运行一次 `gbat`,并允许 macOS 弹出的权限请求。通常不需要 `sudo`。 | +| `Could not initialize HID access` 或 `Could not read battery level: HID access failed` | 从 Terminal 运行一次 `gbat`,并允许 macOS 弹出的权限请求。通常不需要 `sudo`。 | | Raycast 提示 `gbat binary not found` | 安装或构建 `gbat`,或在脚本中将 `GBAT_BINARY` 设为它的可执行文件路径。 | | `Battery: 100%` 但没有 `(charging)` | 鼠标充满后可能停止主动充电,这是正常现象。 | | macOS 阻止运行 | 打开 System Settings > Privacy & Security,为 `gbat` 选择 Open Anyway。 | @@ -129,9 +129,9 @@ xattr -dr com.apple.quarantine "$(brew --prefix gbat)" ## 工作原理 -`gbat` 以共享模式打开 Logitech HID++ 接口。它会检查接收器的设备索引 `1` 到 `6` 和 USB 直连索引 `0xFF`,先尝试 `1` 和 `0xFF`,再使用首个报告支持电池功能的接口及设备索引。连接多只鼠标时,无法指定要读取哪一只。 +`gbat` 以共享模式打开 Logitech HID++ 接口。它会检查接收器的设备索引 `1` 到 `6` 和 USB 直连索引 `0xFF`,先尝试 `1` 和 `0xFF`,再使用首个报告支持电池功能的接口及设备索引。它只按 Logitech 厂商 ID 筛选,连接多个 Logitech HID++ 设备时,可能读到另一只鼠标、键盘或耳机,且无法指定设备。 -它优先读取 `0x1004` 的 `UNIFIED_BATTERY`。该功能不可用、未响应或返回不完整响应时,会回退到 `0x1000` 的 `BATTERY_STATUS`。HID 访问错误和写入不完整会直接终止读取。如果两个功能都未返回电池状态,命令会报错,不会将读取失败显示为 `0%`。 +它优先读取 `0x1004` 的 `UNIFIED_BATTERY`。该功能不可用、未响应或返回不完整响应时,会回退到 `0x1000` 的 `BATTERY_STATUS`。找到电池功能后,HID 访问错误和写入不完整会直接终止读取。探测阶段某个接口出错时会跳过它,只有其他接口都没找到鼠标、也没有报告离线时,才返回该错误。如果两个功能都未返回电池状态,命令会报错,不会将读取失败显示为 `0%`。 ## 许可证