Reverse engineering a mouse configurator

Mon, 28 Aug 2023 00:00:00 +0000

Preamble: The problem

Once upon a time I had a mouse. This little mouse had five buttons. The typical three, plus a forward and backward on the side. It was nothing fancy, but it got me hooked on mice with additional buttons. There’s something very satisfying about moving through your browser history with a single button that I could not relinquish. After this mouse broke seven years ago, in 2016, I bought a brand new Mars Gaming MM4 18-button mouse. It has a nice 12-button keypad on the side, which can be configured with a propietary tool for Windows.

I was in university at the time, and Microsoft gave us free Windows keys through the Inspire program. I was already a Linux fanboy, but I had to keep Windows installed to run some programs that were necessary for my university, such as Solidworks, so I put up with this mouse configurator for the time being.

After I was done with university, I chose to nuke the Windows partition, which left me with no way of modifying the button mapping or changing the DPI resolution profiles. I tried running the configurator through Wine, but it did not work. It would boot, but it would refuse to communicate with the mouse. I then did the only sensible choice and decided to reverse engineer the configurator tool, or more specifically, the USB communication protocol.

Reverse engineering the communication protocol

To be able to reverse engineer the communication protocol that the mouse uses, I would firstly need an easy way of intercepting and processing the communication between the computer and the mouse. This proved easy, since Wireshark, our beloved network packet sniffer, can be used to intercept USB communications¹. I then spent a couple of days using the configurator, tweaking a single parameter, capturing the USB output and analyzing it to find how that tweak was encoded in the wire.

The mouse configurator seemed to be sending and receiving a dozen or so packets to and from the mouse. For each of the tweaks I made, I saved the packets into a pcap file with the data before and after the tweak. To convert the pcap files into a more manageable file format I wrote a small script in python. This scirpt uses the pyshark library to open the files, extract the info I wanted and write it out as a plain csv, with the binary data displayed as hexadecimal. I then loaded these csv files into Libreoffice Calc for further processing.

Having the data before and after the tweak allowed me to very easily see the differences that resulted in the tweak being applied. It was a matter of a game “Find the differences”, only I have a computer to find them for me. Any information I uncovered from this analysis I wrote down into Ghidra, which has a convenient Data Type Manager which lets you define data types, their structure, size and add explanatory comments to them.

With this same procedure I managed to reverse engineer around 75% of all the data being sent, and almost all of the exposed features on the configurator tool, with the exception of complex macros². I was satisfied with the work I had put in, but all of this would be in vain if I didn’t use it to create my own configuration tool.

Implementing a new driver in ratbag

I don’t need to say this, but creating your own configuration tool from scratch is a very hard task. That’s why I chose to implement my findings into the ratbag project. Ratbag, plus its frontend Piper, are MIT/GPLv2 licensed tools for configuring input devices, chiefly mice. They are, as far as I know, the predilect tool for this kind of task in Linux.

Figuring my way around the repositories took a couple of days, but seeing how other drivers were implemented helped significantly. Implementing a new driver is a matter of implementing two main components: The probe component, which obtains the current running configuration of the mouse, and the commit component, which applies the configuration to the mouse. Implementing the commit component proved easy, since I simply had to replicate the behavior that I previously reverse engineered. I even made it more efficient by not commiting configuration that hasn’t been changed, which the propietary tool does not do.

I then went ahead implementing the probe component. There is only a slight problem here. The propietary mouse configurator hardly does any probing. It only probes the device id, likely to confirm that it’s a supported device. It does not probe the current configuration of the mouse, such as buttons, LEDs and DPI resolutions. The configuration that shows up when the tool is launched is the one that is saved to disk on the host machine.

It didn’t take long while messing around to adapt the protocol to add this new feature. I analyzed the packet that probes the device id and identified the section that allowed for reading values from the mouse. Luckily, the same technique can be applied to the rest of the configurable values so that they can be read.

In parallel, I was also doing some changes in the Piper project. I needed to create an svg that resembled the mouse that would serve as the UI. Interestingly, Piper doesn’t use svg merely for display. It uses specific attributes to identify the location where to put clickable buttons on the UI, or layers to choose which leads to show on each screen, and which ones to highlight on mouse hover.

After I successfully implemented all of the features I considered necessary, I decided to open PRs to Piper and libratbag. After a protracted (by me) review process, both PRs were successfully merged, and will be available in the following release, likely to be v0.18.

Final thoughts

Even though this project was a success, I feel a slight bittersweet aftertaste. I successfully managed to implement everything that I wanted, but what is the likelihood that someone will be using this 8 year-old mouse nowadays, and on linux on top of that? Even I myself don’t use the tool that often.

I am at least glad to be able to have a free and open implementation of the protocol for posterity’s sake. At the very least, I hope this post encourages anyone to try the same for their own mice or any other device, either with the specific goal of re-implementing the configuration protocol, or simply exploring the possibilities that the USB protocol can offer.

And finally, this is a great example as to how free software benefits everyone. I benefit because I can run and modify the program without any restrictions. The project benefits from the contributions, and other users benefit from the collaboration and implementation of new features. This is just a small part of why I love free software.

The Wireshark USB dissector seems to not be fully implemented. In particular, the USBHID component does not seem to be parsing the GET_REPORT Response, so the response data does not get dissected and displayed neatly. Given this, I attempted to implement my own dissector that would parse the responses into a proper USBHID response packet. I got fairly deep into implementing this, but the usefulness was dwarfed by the effort of implementing and using it, so I did not proceed any further. ↩︎
I intentionally chose to forgo reverse engineering the macros. I had never used them, nor was planning to, and it would have added a significant amount of additional work to this process. ↩︎

Open-Source on The Dark Programmer's Tome of Secrets

Reverse engineering a mouse configurator

Preamble: The problem

Reverse engineering the communication protocol

Implementing a new driver in ratbag

Final thoughts