Segfault Research > Projects > Other > USButton2key
First published on: 15-May-2014

(this utility replaces my previous one called "xpplugin_throttle_thwarthog")



I have a "Thrustmaster Hotas Warthog" throttle and joystick, which I use when playing X-Plane in Linux.
The devices are fantastic and do work in Linux but the throttle...

...has some analog switches (see below in the above pic) which do not have only a meaning when they're in their "on" position, but as well when they're in an "off" position - a very simple example is for example that in a flighsim one of those switches is supposed to trigger a "landing gears down" event in its "on" position and a "landing gears up" event in its "off" position.

So here comes the problem:
most apps/games trigger a reaction only when a button changes its state and sends an "on" signal (and in many cases it keeps firing such signals if it kept pressed), but that when that button changes its state to "off" all what happens is that the "on" events stop being sent and the "off" event is ignored - in the above example of the landing gears, this would mean that by using such a switch I could e.g. lower the landing gears but never retract them, at least not by using the same button and just switching it to its "off" position.

As I wasn't able to find a way to make my flightsim behave as I wanted I started looking for utilities which would allow me to at least map both "on" and "off" states of a switch to a keyboard event (in the flightsim itself I would then just map the keyboard keys to those specific actions) but found none, so I decided to program my own utility and this is what came out.

What it does

USButton2key allows you to map any state (on/off) of any button of any USB device you have, to any single ASCII character or sequence of ASCII characters you wish. When you then press one of the mapped buttons the program will:

  1. notice it
  2. look at your mapping for that specific button and state and recognize which ASCII character(s) have to be generated
  3. generate one or multiple keyboard event/s (depending if you mapped the button & state to a single or to multiple characters)
  4. send the keyboard event/s to the window which is currently focused on your X-desktop.


  • It doesn't need any special drivers/modules.
    If when you plug in your USB-device you see under "/dev/input/" a new "event..."-file showing up then it should work.
  • Should work with any software which runs in X which accepts keyboard input.
  • Allows to map devices which have up to 1000 buttons on a single USB device.
    No special reasons why I limit it to 1000 - let me know if more is needed.
  • GTK UI to configure the mapping.
    No fiddling around with config files - but you still can, if you want.
  • A single executable which you can place anywhere you want.
  • Depending on how you use it, a single config file (for mapping & overall settings) for all devices, or multiple configurations for multiple setups and/or devices.
  • Optional different configurations for identical devices all connected at once to the PC - decision of which mapping to use based on which USB-port you're using to connect them.
    Assuming you have 4 identical USB joysticks or throttles or anything else connected to your PC at once, you can use a mapping for the device that is connected to the first USB-port on your left, another mapping for the device that is connected to the second USB-port on your right, etc... .
  • Option to use the mapped sequence of characters as a command.
    For each button you have an "Execute" option which will add at the end of the sequence of characters a "return" character => if a shell is focused at that time then it will excute the sequence of chars (which will therefore be interpreted as a command).
  • Buttons status checked every 0.05 seconds.
    Ok, not sure if this is actually a feature - if you're faster at pressing and releasing (or the opposite) then the program won't notice any change.

This is a first "alpha" release!
Please kindly let me know here if you think that this is useful, if you wish for some additional functionality, if you found some bugs, or if you have anything else to say about it.
There are obviouly things that are not yet ready (e.g. see all those "n/a"s in the UI and the unuseful menu) but basically the utility should do what it's supposed to do.
Right now I am quite happy with it but I have to admit that I ended up spending 99% of the time programming it without really using it while playing => I hope that it works fine but if it doesn't then please tell me.

I can think of a few improvements for the future:

  • User-configurable button status checks intervals
    Currently hardcoded to 0.05 seconds, might not be fast enough for some users.
  • Suppress display of UI
    No need for the UI if you just want to use the current settings.
  • Wayland support

Again: let me know here if you're interested in it and/or if you have any suggestions.