Fix/logi bolt macos support#91
Merged
thisislvca merged 4 commits intoApr 14, 2026
Merged
Conversation
The iokit-only backend on macOS could not detect mice connected through a Logi Bolt USB receiver. Two changes fix this: 1. Default backend preference to "auto" on all platforms so hidapi is tried when IOKit enumeration returns no devices. 2. Replace `break` with `continue` after a failed divert so the device-index loop keeps scanning receiver slots instead of stopping at the first non-mouse device (e.g. a keyboard on an earlier slot). Tested with MX Master 3S For Mac paired to a Bolt receiver (PID 0xC548) on macOS — device detected at slot 4, all HID++ features operational. Closes TomBadash#59 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Default HID backend to "auto" so hidapi enumerates Bolt receiver interfaces alongside IOKit - On macOS, prefer IOKit for opening devices (non-exclusive access) to prevent cursor freeze; fall back to hidapi only when IOKit fails - Continue scanning receiver slots after divert failure instead of stopping at the first non-mouse device (e.g. keyboard on slot 3) - Sort candidates so direct devices (Bluetooth) are tried before USB receivers, avoiding slow slot-scan timeouts for BT users - Show actual connection type (Bluetooth / Logi Bolt) in the UI status badge, derived from HID++ device index - Update README and README_CN to reflect Bolt support Tested with MX Master 3S For Mac on both Bluetooth and Logi Bolt (PID 0xC548) on macOS — seamless switching between both modes. Closes TomBadash#59 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Divert failure continues to next receiver slot - Candidates sorted: direct devices before USB receivers - Transport label: "Bluetooth" for devIdx 0xFF, "Logi Bolt" for slots 1-6 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
thisislvca
reviewed
Apr 14, 2026
thisislvca
left a comment
thisislvca
left a comment
Collaborator
There was a problem hiding this comment.
The connection fix looks good to me overall. One thing I want to double-check before merge is the new transport label.
Right now we label any non-0xFF devIdx as Logi Bolt. As far as I can tell, that only proves the mouse was reached through a receiver slot, not that the receiver itself is definitely Bolt. In other words, this seems sufficient to distinguish Bluetooth vs receiver-backed, but maybe not enough to specifically claim Logi Bolt.
Could you either:
- confirm that the receiver can be identified as Bolt from PID / product string / other metadata and keep the current label, or
- change the fallback label to something safer like
USB receiverunless Bolt is positively identified?
If you tweak that part, can you also re-test both Bluetooth and the Bolt receiver once more before we merge?
…ely identified Previously any non-0xFF devIdx was labeled "Logi Bolt", but that only proves the device is behind a receiver slot — not that the receiver is Bolt. Now we check the receiver PID (0xC548, per Solaar) and fall back to "USB Receiver" for Unifying/Nano/Lightspeed receivers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Thanks for the review @thisislvca ! You were right — devIdx != 0xFF only proves the device is behind a receiver slot, not that it's specifically Bolt. I checked the Solaar receiver database and confirmed that 0xC548 is the only Bolt receiver PID (notably, 0xC52B is Unifying, not Bolt). |
Collaborator
|
LGTM, thanks |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #59 — Logitech mice connected via a Logi Bolt USB receiver were not detected on macOS.
Root causes:
iokit-only, which skippedhidapienumeration — the Bolt receiver's vendor-specific HID++ interfaces (usage_page >= 0xFF00) were neverdiscovered
breakafter failed_divert()stopped the device-index loop at the first non-mouse device (e.g. MX Keys S keyboard on slot 3), preventing discovery of mice on later slotsChanges:
"auto"on all platforms sohidapienumerates alongside IOKitbreakwithcontinueafter divert failure so all receiver slots (1–6) are probedTesting
Tested on macOS 15 (Apple Silicon) with MX Master 3S For Mac:
0xC548, receiver slot 4): all HID++ features working — REPROG_V4, DPI, Smart Shift, battery0xB034, devIdx0xFF): instant connection, no regressionScreenshots
Status badge shows Connected · Logi Bolt or Connected · Bluetooth depending on transport.