gwolves-battery - Marc's Webpage

GWOLVES-BATTERY(1)marcp.xyzGWOLVES-BATTERY(1)

NAME

gwolves-battery - Read G-Wolves HSK Pro 8K battery level on Linux

SYNOPSIS

gwolves-battery              # first mouse found
gwolves-battery all          # all connected mice
gwolves-battery <serial>     # specific mouse (partial match)

DESCRIPTION

The G-Wolves HSK Pro 8K is a great mouse, but there is no Linux software for it. The only way to see the battery level is a web driver (WebHID, Chrome only). That is not something I want to open just to check a percentage, so I reverse-engineered the protocol.

The method: run the web driver once, capture the USB traffic with tshark while the driver polls the battery, then dig through the packets in Wireshark. The battery query turned out to be a simple pair of HID feature reports on interface 2 of the receiver: one SET_REPORT to request the data, one GET_REPORT to read it back. The battery percentage sits at byte 5 of the response.

The result is a single C file (~180 lines) using libusb, no other dependencies. It supports multiple mice at once, each identified by the receiver's unique serial number.

PROTOCOL

Device:  33e4:5817 (G-Wolves HSK Pro 8K Receiver), Interface 2

Step 1: SET_REPORT (request battery)
  bmRequestType  0x21   Host-to-device, Class, Interface
  bRequest       0x09   SET_REPORT
  wValue         0x0300 Feature Report, ID 0
  wIndex         2
  Data           00 02 8f 01 00 00 ... (64 bytes)

Step 2: GET_REPORT (read response, after ~10ms)
  bmRequestType  0xa1   Device-to-host, Class, Interface
  bRequest       0x01   GET_REPORT
  wValue         0x0300
  wIndex         2
  Response       a1 02 8f 01 00 [BATTERY] 00 ...
                                 ^^^^^^^ percentage at byte 5

EXAMPLES

$ gwolves-battery all
Found 1 mouse/mice:

1. Mouse 24A4E23D2605: 🔋 78%

$ gwolves-battery
🔋 Battery: 78% (Mouse: 24A4E23D2605)

BUILDING

$ curl -LO https://marcp.xyz/files/gwolves-battery.tar.gz
$ tar xzf gwolves-battery.tar.gz
$ cd G-Wolves-Battery
$ make            # needs gcc, make, libusb
$ make install    # copies to ~/.local/bin

NOTES

Non-root USB access needs a udev rule:

$ cat /etc/udev/rules.d/70-g-wolves.rules
SUBSYSTEMS=="usb", ATTRS{idVendor}=="33e4", ATTRS{idProduct}=="5817", MODE="0660", TAG+="uaccess"

Since it is a fast single binary, it drops straight into a status bar. I call it from dwmblocks; anything that runs a shell command works.