Configure mouse thumb buttons as F13 in Linux
13 February 2021
Like most people, I have a mouse with thumb buttons on it. Mouse designers of the late 90s and early 00s decided to call these buttons “Back” and “Forward” and make them navigate backwards and forwards in web browsers and such. Not a feature I use very much.
What I do use a lot is VoIP communications software, where I use push-to-talk bound to one of these thumb buttons. Therein lies the problem: whenever I press push-to-talk with my web browser active, it takes me off the page I was on and onto the previous page I was on. I don’t want that to happen.
Browser designers clearly don’t relate to this issue, so there’s no easy, universal way to disable this backwards-forwards functionality of the thumb buttons. And even if I did disable it in Firefox, my file browser would still use them for navigation, and if I disabled it there, there’d still be some app out there that insists on using these buttons for this purpose. It’s a battle I can’t win.
Some years ago I discovered a great solution for this. My Logitech mouse allows rebinding the mouse buttons to arbitrary keyboard buttons, so why don’t I just change it to some keyboard button I almost never use like the Pause button? Even better, the F-keys that normally run from F1 to F12 actually run all the way up to F24. Modern keyboards obviously never go that high, but due to legacy reasons operating systems still support these “high F” keys.
So I opened the Logitech Control Panel on Windows, entered the key binding interface and… wait, I can’t actually input F13 in here. How do I do it? I’ll spare you the suspense and say that I did it with a simple AutoHotKey script that sent the F13 keystroke which the Logitech software happily accepted. I don’t have that script anymore because I don’t use Windows, but it was a oneliner so you’ll figure it out. I’m counting on you.
But then I switched to Linux, and the Logitech Control Panel doesn’t work on Linux and unfortunately, the forwards/backwards buttons do. What now?
The actual solution
Enter libratbag, a community-maintained effort to enable features in modern mice (and a small handful of other peripherals) that would normally be accessed through the driver software, which is unfortunately typically exclusive to Windows.
It’s supposed to be a library/dbus daemon type thing to enable GUI frontends to access these devices, and it has a GUI frontend called Piper. Unfortunately, Piper doesn’t want to accept the F13 key.
Thankfully libratbag also comes with a command line utility called ratbagctl.
$ ratbagctl
singing-gundi: Logitech MX518 Gaming Mouse
When invoked, it shows us a list of supported devices along with a human-readable ID. In this case there’s only one supported device, “singing-gundi” the Logitech MX518 Gaming Mouse.
We read man ratbagctl like a good boy and piece together the following commands:
$ ratbagctl singing-gundi button 3 get
Button: 4 is mapped to 'button 4'
Button 3 is the first thumb button, the one closer to the user. We can see it’s currently bound to ‘button 4’, which is the default and not at all confusing (ratbag indexes the buttons from 0 while X11 – or whatever is handling the input – indexes from 1). We want to rebind it to F13.
The manpage specifies the command button N action set button B, but this is for setting it to
mouse buttons, not keyboard keys, so we can’t rebind it to F13 this way. Instead we need to use
ratbagctl singing-gundi button 3 action set macro KEY_F13
The shell should be silent in response, which means the command succeeded. We can check that it worked with
$ ratbagctl singing-gundi button 3 get
Button: 3 is mapped to macro '↕F13'
And that’s it! The first thumb button is now going to be sending the F13 keystroke, which X11 calls XF86Tools by the way. This should be recognized in pretty much any app or game as a keybinding, but browsers won’t go backwards when pressing it.
If you want to go back to the default, simply use
ratbagctl singing-gundi button 3 action set button 4