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.
Topology
Section titled “Topology”Nothing a device sends leaves the browser. The server only delivers the app; settings, captures and firmware files stay in the tab.
Devices and how far each one is checked
Section titled “Devices and how far each one is checked”| Device | Settings | Firmware update | How it was checked |
|---|---|---|---|
| Nuvoton M483 wired mouse | Read, write, factory reset | Yes, from the vendor updater .exe | Settings 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 wireless | All fields of the vendor web configurator, plus buttons, profile, dongle LED, long distance and low power | Yes: the vendor package, or a gated patched build | Pairing 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 remap | No | DPI write matches a recording of the vendor’s launcher; not yet run on the mouse |
| PAW3950 mouse | Settings, register access, raw sensor image | Built but switched off | Taken 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 only | No | Probed live; it speaks a different protocol from the nRF52840 mouse family |
| GRIDDLE LX keyboard | Layout, actuation, profiles | No | Against 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.
The write rule
Section titled “The write rule”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:
| Source | Used for |
|---|---|
| USB capture (USBPcap) of the vendor desktop app | M483 mouse settings and the complete firmware update |
| A WebHID recorder pasted into the vendor’s web configurator | nRF52840 mouse and 8K-family mouse settings: every report the page sends, with timestamps |
| The vendor’s exact bytes replayed with a native tool, replies recorded | Settings 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.
Firmware updates: which files are allowed
Section titled “Firmware updates: which files are allowed”| File | Accepted when | Recovery if it stops |
|---|---|---|
| M483 mouse updater .exe or raw image | The 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 .bin | Its SHA-256 is one of the 29 packages the vendor’s web configurator links, now or previously | The 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 matches | As above, with the bundled stock image |
| PAW3950 mouse .fw | Never, 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.
Security headers
Section titled “Security headers”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:
| Header | Value and reason |
|---|---|
| Content-Security-Policy | Scripts 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-Policy | hid=(self): WebHID for this origin only, never inside a frame. USB, serial, Bluetooth, camera, microphone off |
| Strict-Transport-Security, X-Content-Type-Options, Referrer-Policy | One year HSTS, no sniffing, no referrer |
| Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy | Same 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.
Gotchas and lessons learned
Section titled “Gotchas and lessons learned”- 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_modulespath 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.
Related docs
Section titled “Related docs”- Patching an nRF52840 gaming mouse’s firmware: the patched builds this app installs, and how they are checked before flashing.
- Fixing merged reports from an 8 kHz mouse on Windows: what happens to the reports after they reach the PC.
- GRIDDLE LX: the keyboard whose configuration protocol tikus also speaks.