Skip to content

feat(gwolves): add HTX Ultra driver (wired + wireless) - #31

Open
defendercf wants to merge 1 commit into
OpenMouse-Project:mainfrom
defendercf:add-gwolves-htx-ultra
Open

feat(gwolves): add HTX Ultra driver (wired + wireless)#31
defendercf wants to merge 1 commit into
OpenMouse-Project:mainfrom
defendercf:add-gwolves-htx-ultra

Conversation

@defendercf

Copy link
Copy Markdown

Protocol

The protocol was captured live from the official G-Wolves web driver at
mouse.fit (patching HIDDevice.prototype.sendReport/inputreport in the
browser console), then independently reproduced with hidapitester with
no browser involved. It's the same shared VGN-family reference design
already implemented for the VGN Dragonfly F2 Master+ and the Pulsar 4K
Wireless Receiver — 16-byte packets on output report 8:

  • Read: opcode 0x08, Write: opcode 0x07, at a 16-bit address
  • Packet checksum: 85 - sum(bytes[0..14]) - reportId
  • Payload checksum: 85 - sum(precedingPayloadBytes) (confirmed on every
    captured packet, DPI/LOD/all 7 polling rates)
  • DPI: 4-byte stage entries, 50-DPI steps, (dpi/50)-1 encoding
  • Polling rate: period-in-ms for ≤1000Hz, one-hot bit flags above (see
    PROTOCOL-NOTES.md, attached below, for the full derivation)
  • LOD: Low=3, Medium=1, High=2 (firmware's own non-sequential ordering,
    confirmed by capturing all three)

Changes

  • src/gwolves/index.ts - new protocol module (own implementation, not
    importing vgn's, matching the Pulsar/VGN precedent)
  • src/drivers/gwolves/hid.ts - new driver, model-agnostic
  • src/drivers/gwolves/products.ts - product catalog (HTX Ultra wired
    0x5618 + wireless receiver 0x3854, both verified: true)
  • src/drivers/gwolves/hid.test.ts - 4 tests, device recognition
  • src/drivers/gwolves/protocol.test.ts - 6 tests, against real captured
    packets
  • src/drivers/vendors.ts - added gwolves 0x33e4 + two HID filters
  • src/drivers/registry.ts - registered driver
  • package.json / src/index.ts - ./gwolves export

Wireless quirk: the mouse must be actively awake (recently moved) to
accept config writes over the 2.4GHz receiver — writes sent while idle
are silently ignored. Noted in the driver and surfaced in the
setPollingRate error hint.

One thing worth flagging: src/drivers/mouse-types.ts already had
"G-Wolves" in its brand union before this PR, with no implementation
behind it. Not sure if that's leftover scaffolding or related to other
in-progress work — happy to coordinate if there's context I'm missing.

Testing

Build passes cleanly. All 517 tests pass (npm run [check).
PROTOCOL-NOTES.md

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant