Wireless-Device-Battery-Monitor: Wireless Battery Is a Reverse-Engineering Archive Disguised as a Tray Icon

A 350 KB C++/Win32 utility reads battery levels from 90 wireless devices by speaking their undocumented HID protocols directly. No G HUB. No Synapse. No background service.

9 min read • View on GitHub • More from krisgfx9

A wide workshop bench in black ink on white. On the left, two fingers hold up a single slim key on a plain ring. On the right, a dense wall of ninety differently-shaped locks is mounted on the edges of wireless peripherals: mice, headsets, keyboards, controllers, and gamepads receding into the background. The single key is small and precise; the wall of locks is varied and packed.
One small key, ninety unique locks. The tool is trivial on the surface. The locks are the work.

Tested on real hardware

Wireless Battery project, Project README · krisgfx9/Wireless-Device-Battery-Monitor
Key Takeaways

The 350 KB Question

You know the ritual. A wireless mouse goes quiet mid-sentence, so you go looking for the number. Logitech G HUB is installed for the mouse. Razer Synapse is installed for the headset. Corsair iCUE is installed for the keyboard. Three applications, gigabytes of disk, hundreds of megabytes of RAM, and one background service per vendor, all to answer a single question: how much battery is left?

Windows does not solve it for you. As the creator of a competing utility put it in PC Gamer, the operating system only surfaces battery for some Bluetooth devices, and only inside Settings. Most 2.4 GHz dongle devices never report a level to Windows at all.

Wireless Battery is the opposite bet. It is a single C++/Win32 binary of roughly 350 KB that uses about 2 MB of RAM, runs no background service, and asks for no administrator rights. It draws the percentage right next to your taskbar and reads it straight from the hardware.

That sounds like a weekend project. It is not. The size is the least interesting thing about it.

"Wireless-Device-Battery-Monitor"が死ぬほど捗る なんでWindowsのデフォルトじゃないのかと 左からBluetooth ヘッドフォン、Logi高尾lのG502X、XBOXワイヤレスコントローラの電池残量 これがG HUBとかのアプリなしでも全部判る ゲーマーもノートPCも絶対に入れて損はないよ!! https://t.co/XioeEIDk5d

しゅまり, syumari_sky · @syumari_sky on X

The reaction above is from a user showing three devices side by side in the taskbar (a Bluetooth headset, a Logitech G502X, an Xbox controller) with no vendor app running. That is the whole pitch in one screenshot. The question is how it is possible.

Ninety Keys on One Ring

Wireless Battery is maintained by GitHub user krisgfx9, the repository owner and by far its largest contributor. The project is licensed GPL-3.0 and carries no runtime dependencies. There is no framework, no installer bundle, no updater daemon. Just Win32 API calls and a lot of very specific knowledge.

The interesting folder is src/drivers/. It holds around 75 individual .cpp files, one per vendor or protocol family, plus shared headers and per-device protocol notes in docs/. Each driver is a small negotiation with a piece of hardware that was never designed to be queried by anything other than its own vendor software.

Logitech talks HID++. Razer has its own report format. SteelSeries, Corsair, and HyperX each do something slightly different, which is why the project credits the reverse-engineering work of HeadsetControl and OpenRazer as upstream sources. Then there are the long-tail brands: Aula, Machenike, Kysona, VAXEE, Finalmouse, RAPOO, Xenta. Each one needed someone to sit down, send bytes, and watch what came back.

The README is honest about the state of that work. It separates hardware that has actually been tested from protocols that were implemented from documentation and never validated on a real device. That distinction matters. It means the support list is a claim about effort, not a guarantee, and it tells you the maintainer has been burned by assuming otherwise.

A WSJ hedcut-style editorial portrait of krisgfx9, the creator of Wireless Battery, rendered in black ink on white. The likeness follows the GitHub avatar photo, with stipple dots for skin texture and fine hatching for hair and clothing.

The Claim Game

With 90 drivers firing in one polling pass, the obvious question is: how do they avoid stepping on each other? A device that reports to the Logitech driver must not also be reported by the generic fallback. A device handled by a specific brand driver must not be double-counted.

The answer is a shared object called PollContext. It holds every enumerated HID collection, the accumulated results, and a claimed set of (vid, pid) pairs that have already been handled. Each driver asks for the products it knows about, probes them, and claims what it took. A claimed pair is invisible to every driver that runs afterward.

This makes call order the correctness mechanism. Specific drivers have to run before broad ones. The source comments spell out exactly why: PollAula runs before Kysona because the two share vendor ID 3554, and whichever fires first would otherwise grab the other's device. PollMachenike runs before the Ajazz path because they share vendor ID 248A. PollBluetooth runs before the generic HID check so that Windows' own reported level wins for any device visible both ways. The generic drivers run last, as a catch-all.

The pipeline: each device stops at the first driver that claims it, and the ledger on the right records what is already handled. Hover the 3554 device to see why order is the whole game.

A Handle With No Rights

Here is the detail that turns a clever utility into a genuinely elegant one. Normally, reading a device means opening it. When one process opens a mouse, other software can be locked out of it, and the input stream can be disturbed. That is why vendor suites and third-party tools so often refuse to coexist.

Wireless Battery sidesteps the problem entirely. Its OpenFeatureOnly() call opens the device handle with zero access rights, using non-overlapped I/O, and sends HID feature reports through that handle. Feature reports do not require the read or write permissions that would claim the device for exclusive use. Every open in the app also passes FILE_SHARE_READ | FILE_SHARE_WRITE.

The practical result: you can run Wireless Battery right next to G HUB, and neither notices the other. You get the number without the conflict, which is the rare case of a tool that adds value by taking up less space rather than more.

A close-up in black ink on white of two hands. One hand holds a wireless mouse that is actively being used, with a faint motion line suggesting a click. The other hand holds a slender probe with a small tag marked with a zero, touching the mouse's surface to read a gauge without gripping or disturbing it. A larger machine sits idle in the background, unaware.
Reading without taking. The probe opens the device with no access rights, so nothing is claimed and nothing is disturbed.

Sleeping Is Not Disconnected

The data model reveals a maintainer who has spent real time with flaky hardware. The central DeviceStatus struct keeps asleep as a separate flag from connected. A device that answers through its receiver but is currently sleeping keeps its last known value instead of blinking to unknown. A device that is switched off and truly gone is hidden. Most battery monitors collapse those two states into one and produce a reading that flickers for no reason.

There is also graceSec, a tolerance window for unstable radio links. When a device drops a reply, its last value survives for a configurable period rather than vanishing. And for collections with no interrupt OUT pipe, where a normal write simply fails, SetOutputAndRead arms an overlapped read first, then sends the report, then waits. The ordering is deliberate: it prevents the reply from arriving before the read has been posted.

Some devices get special caution. Comments in the shared header describe VAXEE as "read-only battery commands" and Finalmouse as "read-only GETs." A malformed write to fragile hardware can reset firmware or change settings, so where a device is delicate the driver simply refuses to write.

Every User a Contributor

Ninety drivers is not a finished number. It is a growing one, and the growth mechanism is built into the CLI. Running the app with the --dump flag prints the HID collections it can see, and the README asks users to attach that dump to device-support reports. Every frustrated owner of an unrecognized mouse becomes a potential protocol contributor.

There is a matching escape hatch for the opposite problem. If a driver pokes a device it should leave alone, users can add the offending VID:PID pair to a free-text registry value, and the app will skip it:

[HKEY_CURRENT_USER\Software\WirelessBattery]
"IgnoreDevices"="248A:1234;3554:5678"

Together, the dump flag and the ignore list turn a support burden into a crowdsourced catalogue. The maintainer does not have to own every device to support it. Someone else does, and the tooling makes their contribution easy to hand over.

Four Gigabytes Versus 350 Kilobytes

Everything above is the argument for a table. The claim is not that Wireless Battery is prettier or more feature-rich. It is that the vendor suites are doing a huge amount of work to answer a tiny question, and that a direct conversation with the hardware is a better fit for the job.

Wireless BatteryVendor suites (G HUB, Synapse, iCUE, GG)Windows Bluetooth settings
Install size~350 KBHundreds of MB to GBsBuilt in
Runtime memory~2 MBHundreds of MBNegligible
Background serviceNoneOne per vendorNone
Admin rightsNoUsually yesNo
2.4 GHz receiver coverageYes, via HIDYes, per vendorNo
Cross-brand in one viewYesNoPartial
Coexists with vendor softwareYesNot applicableYes
Device coverage modelCommunity-tested plus documented-but-untestedFirst-party onlyOS-reported only

One caveat worth stating plainly: the install size, memory, and admin-rights figures are the project's own README claims, not independent benchmarks. The structural differences (no service, cross-brand view, direct HID access) are visible in the code, but the numbers are self-reported.

That is the whole shape of the project. A trivial surface hides a monumental underside. The cleverness is not in an algorithm. It is in 90 small acts of reverse engineering, a disciplined order of operations, and one handle opened with no rights at all.