Skip to content

feat(native-hid): pick devices and drivers with OpenMouse's own registry - #124

Merged
snekxs merged 6 commits into
mainfrom
feat/native-hid-registry
Nov 17, 2026
Merged

snekxs merged 6 commits into
mainfrom
feat/native-hid-registry

Conversation

@snekxs

@snekxs snekxs commented Nov 17, 2026

Copy link
Copy Markdown
Member

Builds on #123; merge that first (this PR then retargets to main).

Problem

Bridge decided which devices were mice with its own vendor-id table (KNOWN_BRANDS in Rust, brands.mjs in the helper), and tried each brand's driver classes on every interface of those vendor ids.

  • It covered only 22 of the 46 brands OpenMouse supports. SteelSeries, Corsair, HyperX, Glorious, ASUS, VAXEE, G-Wolves and the rest only showed a battery once the web panel connected.
  • Adding them the same way wasn't safe. Several share chip vendor ids with non-mouse hardware: ASUS 0x0b05 (motherboard RGB, GPUs), Elan 0x04f3 (touchpads), Holtek 0x04d9, Corsair 0x1b1c (coolers, fan hubs). The helper would have sent mouse commands to those every poll.
  • It picked the wrong driver where vendor ids are shared. A wired Endgame Gear OP1 8k got the wireless OP1we driver ("vendor channels missing", and 1000 Hz reported instead of 2000).
  • The Node adapter reported no collections, so drivers that find their channels in the descriptor couldn't work. It also wrote every report to every collection, and read feature reports with a fixed buffer, which Windows rejects.

Change

Discovery and dispatch now follow @openmouse/protocol's registry: the same supports() checks the control panel runs in the browser.

  1. Filters. Bridge asks the helper once for SUPPORTED_HID_FILTERS (what the panel passes to requestDevice). It only ever opens a device one of them matches, and only to read its report descriptors.
  2. Describe. hid::describe_devices groups and parses devices exactly as the panel's Bridge transport does (inspect_path, factored out of inspect_candidate). Results are cached, so a device is opened only when it first appears, never during a panel session.
  3. Identify. When the devices change, the helper reports each one's registry brand. Those are the mice Bridge lists, under the same device ids as before.
  4. Read and apply. Status and apply requests carry the described devices. The helper builds the registry's client on a new DescribedDeviceAdapter, which:
    • sends a report only down the collection that declares it, padded to the declared size as Chrome does;
    • reads feature reports at their declared size and drops the id slot (the OP1 8k returns 0x00 there), as report_payload does;
    • listens only on collections that declare input reports (a feature-only collection made node-hid drop the handle on Windows).

A profile saved under the brand its driver reports (Attack Shark) for hardware the registry files elsewhere (Delux) is still found: Bridge sends every supported device, and the helper keeps the one whose status reports that brand.

Without Node.js, Bridge falls back to the vendor-id table and brands.mjs. Zaunkoenig's acknowledged automation is unchanged.

Testing

  • cargo fmt --check, cargo clippy --all-targets: clean. cargo test: 305 pass.
  • npm test in native-hid: 41 pass, including adapter routing, padding, id-slot and listening tests, and identification and brand matching.
  • On Windows hardware, through Bridge's real detect_mice() and read_status() (OPENMOUSE_LIVE_REGISTRY=1 cargo test live_mice -- --ignored --nocapture):
    • Keychron G6 HE 8K on TurboLink 8K: 21%, 800 DPI, 1000 Hz.
    • Endgame Gear OP1 8k (wired): identified correctly, 800 DPI, 2000 Hz, no battery.
    • Wooting 60HE+: identified, no battery.
    • An MSI Mystic Light controller on the same bus matches no filter and is never opened.
  • dump_live_bus (ignored test) writes what Bridge sends the helper, for checking other hardware.

Known differences from the browser

  • Bridge keeps its 3 s probe and 10 s helper timeouts, so a slow-waking wireless mouse may miss a poll and be read on the next.
  • Input reports still use the old adapter's report-id guess.
  • Razer descriptors aren't parsed, as in the panel's Bridge transport.
  • Brands other than the three above need validation on their hardware.
  • Settings writes go through the new path but were only exercised in tests.

…nMouse connects

brands.mjs pointed Keychron at drivers/keychron/hid (KeychronHidClient),
which mouse-protocol no longer has: it was split into the 8K, 1K, 4K,
8K Nordic and Nape clients. Every native read failed with "Cannot find
module", so a Keychron mouse only got a battery once the web panel
reported one. The entry now lists the five clients in registry order.

The TurboLink 8K receiver also answers Keychron8kHidClient on three
interfaces, and only the 0xffc1 one reports the battery. The helper took
the first answer, so it would still have shown none. select-client.mjs
now prefers an answer with a battery and falls back to the first answer
when none has one, as for a wired mouse.

A test checks that every driver class brands.mjs names exists in the
protocol package, so a future rename fails the tests instead of quietly
stopping battery reads.
…a battery

After an answer without a battery, the helper tried every remaining class on every interface. Each failed probe can wait out its 3 s timeout, so a wired mouse of a brand with several classes (Razer has five) could run past Bridge's 10 s limit on the helper and lose a DPI read that works today. Only the class that answered is now tried on the other interfaces, which is all the Keychron receiver needs.
Bridge chose which devices were mice by a vendor-id table of its own and
tried each brand's driver classes on every interface of those vendor ids.
That covered 22 of the 46 brands OpenMouse supports, picked the wrong
driver where vendor ids are shared (the wired Endgame Gear OP1 8k ran the
wireless OP1we driver), and adding the rest would have sent mouse commands
to anything on chip vendor ids like ASUS, Elan, Holtek or Corsair.

Discovery and dispatch now follow @openmouse/protocol's registry, the same
supports() checks the control panel runs in the browser:

- Bridge asks the helper once for SUPPORTED_HID_FILTERS and only ever opens
  a device one of them matches, to read its report descriptors.
- hid::describe_devices groups and parses devices as the panel's own Bridge
  transport does, cached so a device is opened only when it first appears
  (never during a panel session).
- When the devices change, the helper identifies each one's brand; those
  are the mice Bridge lists, with the same device ids as before.
- Status and apply requests carry the described devices. The helper builds
  the registry's client on a DescribedDeviceAdapter, which sends a report
  down only the collection that declares it, padded to its declared size as
  Chrome does, reads feature reports at their declared size and drops the
  id slot, and only listens on collections that declare input reports.

Without Node.js the vendor-id table and brands.mjs remain the fallback.
Zaunkoenig's acknowledged automation is unchanged.
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 36 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between ca7b714 and 457a067.

Files selected for processing: 10

  • native-hid/README.md
  • native-hid/src/apply.mjs
  • native-hid/src/brands.mjs
  • native-hid/src/hid-device-adapter.mjs
  • native-hid/src/registry.mjs
  • native-hid/src/registry.test.mjs
  • src/drivers/mod.rs
  • src/drivers/native_hid.rs
  • src/drivers/registry.rs
  • src/hid.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions github-actions Bot added type: enhancement PR title category: enhancement area: native Native bridge and platform services area: devices HID access and device drivers area: documentation Documentation labels Nov 17, 2026
…he battery search

Preferring an answer with a battery also chose the target of DPI and polling-rate writes, so with two mice of one brand connected a profile could be applied to the second because it reported a battery. Only status reads prefer a battery now; writes take the first mouse that answers, as before.

The battery search had no bound of its own, so stalled sibling interfaces could run a read past Bridge's 10 s limit on the helper. It now stops 4 s after the first battery-less answer, whose status is kept instead of being read a second time.
Status reads alone prefer a battery, so the registry path keeps settings writes on the first mouse too. Adds a check that every helper script parses, since no test loads apply.mjs.
@snekxs
snekxs changed the base branch from fix/keychron-native-battery to main November 17, 2026 21:50
@snekxs
snekxs merged commit 521a068 into main Nov 17, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: devices HID access and device drivers area: documentation Documentation area: native Native bridge and platform services type: enhancement PR title category: enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant