Skip to content

Reverse engineeringreference

tikus: a browser configurator and firmware updater for vendor mice

tikus is a static web app that configures and updates the firmware of the mice I own, replacing four vendor tools with one browser tab. This page covers how it talks to the devices, why each write and flash is allowed, and what went wrong on the way. The firmware patches it can install are covered separately in Patching an nRF52840 gaming mouse’s firmware.

Status as of 2026-11-19: the app is public at https://tikus.io, and the source is private, because its test fixtures include decrypted vendor firmware. Hardware claims below say which device and date they were checked on; everything else is marked as recorded-only or untested.

TL;DR:

  • One browser tab, no backend. The browser talks to the mouse over WebHID; Firefox, which has no WebHID, goes through a small native bridge on the same computer.
  • Each protocol layer is tested by replaying recorded traffic from the vendor’s own tool, byte for byte. A setting is only writable once such a recording exists.
  • Firmware updates accept only files whose origin can be proven: the vendor’s released packages by SHA-256, or a patched build that carries a passing patch-gate record.
  • Every early flash on the nRF52840 mouse failed at 100 % because tikus sent the decrypted firmware. The bootloader decrypts what it receives itself, so it must get the package bytes unchanged.
Caddy(static files + headers)Browser tab(tikus SPA)HTTPS, oncehidlab bridge(Firefox only)ws://127.0.0.1Mouse / dongle(vendor HID collection)WebHIDSame device inupdate modeWebHID (new device id)Windows HID

Nothing a device sends leaves the browser. The server only delivers the app; settings, captures and firmware files stay in the tab.

DeviceSettingsFirmware updateHow it was checked
Nuvoton M483 wired mouseRead, write, factory resetYes, from the vendor updater .exeSettings writes and an update from 1.10 to 1.11 run on the mouse (2026-11-05 and 2026-11-09)
nRF52840 mouse + CH32V305/nRF52820 8K dongle, wired or wirelessAll fields of the vendor web configurator, plus buttons, profile, dongle LED, long distance and low powerYes: the vendor package, or a gated patched buildPairing on hardware 2026-11-05; one-click update on the nRF52840 mouse 2026-11-19; new button and dongle settings checked by replaying the vendor’s commands on the mouse, not yet through the page
8K-family mouse (vendor web launcher)Startup reads, DPI, key remapNoDPI write matches a recording of the vendor’s launcher; not yet run on the mouse
PAW3950 mouseSettings, register access, raw sensor imageBuilt but switched offTaken from the vendor web app; I have no device of this model, so nothing has run on hardware
First-generation 8K dongle (NXP LPC55 + nRF52820)Identity onlyNoProbed live; it speaks a different protocol from the nRF52840 mouse family
GRIDDLE LX keyboardLayout, actuation, profilesNoAgainst the firmware’s own test vectors; no board exists yet

The keyboard is my own design, so its protocol comes from its firmware rather than from captures; see GRIDDLE LX.

A setting becomes writable only after a recording exists of the vendor’s tool performing that same write. The reason is that a wrong byte in a mouse’s configuration block can go unnoticed until something misbehaves. Each settings block on the M483 mouse, for example, packs several options into one byte, and one of them was once misread as “ripple control on”.

The recordings come from three places:

SourceUsed for
USB capture (USBPcap) of the vendor desktop appM483 mouse settings and the complete firmware update
A WebHID recorder pasted into the vendor’s web configuratornRF52840 mouse and 8K-family mouse settings: every report the page sends, with timestamps
The vendor’s exact bytes replayed with a native tool, replies recordedSettings whose replies the recorder missed

The third row came from a recorder bug. On the nRF52840 mouse vendor’s web configurator, the hook that should catch the mouse’s replies never fired, so one session captured only what was sent. Rather than repeat the session, I sent those 13 commands to the mouse unchanged with a native HID tool and recorded each reply, then set every setting back. A read of the whole settings page before and after was identical. The replies are what the tests replay; the commands are still the vendor’s, byte for byte.

Writes edit the block read from the device in place and are checked by reading it back. Bytes tikus does not understand are never rebuilt, and packed bytes keep their unmapped bits.

FileAccepted whenRecovery if it stops
M483 mouse updater .exe or raw imageThe extracted image’s SHA-256 is one of the vendor’s releases (1.04, 1.09, 1.10, 1.11)The mouse stays in its bootloader and can be flashed again
The nRF52840 mouse vendor’s own .binIts SHA-256 is one of the 29 packages the vendor’s web configurator links, now or previouslyThe mouse stays in update mode and accepts the same file again
Patched nRF52840 mouse build (.tikusfw)It carries a passing patch-gate record and a stock recovery image whose header matchesAs above, with the bundled stock image
PAW3950 mouse .fwNever, for now-

Two kinds of override were removed before opening the app to others: a SAFETY OFF switch that allowed a modified nRF52840 mouse package without a gate record, and acceptance of any M483 mouse image the updater format could hold.

The page has a five-step guide (GUIDE button) that explains each part of the update in plain words, including the second browser permission dialog that appears because the mouse becomes a different USB device in update mode.

The bug behind every failed flash on the nRF52840 mouse

Section titled “The bug behind every failed flash on the nRF52840 mouse”

The Compx bootloader on the nRF52840 mouse takes a header, an erase, then the image in 32-byte chunks, and answers with a status report. tikus streamed all 106,496 bytes, the mouse acknowledged every chunk, and then it reported error 3 instead of success and stayed in update mode. It happened twice; both times a native tool flashed the same package into the stuck mouse without trouble.

The difference was what each tool streamed. The native tool and the vendor’s own web configurator send the image bytes exactly as they sit in the package file. tikus sent the decrypted payload. Its bundle format carried both, and an early version of the flasher took the decrypted one. The bootloader decrypts what it receives, so it decrypted plain code into noise and rejected the checksum.

I first compared the two tools’ outputs by feeding both the same decrypted payload, and they matched. That comparison could not find the bug, because I had given the reference tool the port’s input instead of the input its own command line passes. The fix makes the flasher take the package and cut the bytes itself, so no caller can hand it decrypted data, and a test checks the bytes on the wire against the package file. The first flash after the fix completed on the mouse.

The app is static, but it can rewrite a mouse’s flash, so the server is strict about what the page may load and talk to:

HeaderValue and reason
Content-Security-PolicyScripts only from the site and no inline script. Connections only to the site, the local bridge, and the PAW3950 mouse vendor’s firmware host. No framing
Permissions-Policyhid=(self): WebHID for this origin only, never inside a frame. USB, serial, Bluetooth, camera, microphone off
Strict-Transport-Security, X-Content-Type-Options, Referrer-PolicyOne year HSTS, no sniffing, no referrer
Cross-Origin-Opener-Policy, Cross-Origin-Resource-PolicySame origin

Checked on the built container: ten routes loaded with no policy violations, fonts and the theme bootstrap still worked, and WebHID was still available.

  • Test harnesses that feed a reference implementation should give it the inputs its own CLI passes. A difference test where both sides get the same wrong bytes reports “identical”.
  • A vendor web driver can hide its replies from a recorder that hooks the WebHID prototype. Listening on each device the page opens worked.
  • A mouse exposes one WebHID handle per interface. Only the one with the vendor collection takes configuration reports.
  • An 8K dongle answers some commands itself, even with the mouse switched off, so a reply is not proof the mouse saw a command.
  • Fonts referenced through a relative node_modules path built fine but were served as the HTML fallback in production. The page looked nearly right in a fallback face, and the type checks measured the wrong font.