The X.Org joystick driver (xf86-input-joystick)

At XDC2012, Sascha Hlusiak, maintainer of the xf86-input-joystick module, gave a talk (slides) outlining the joystick driver's current state and future directions. There were quite a few tidbits of information in there that I want to repeat here, a slightly more public place.

The most important bit about the xf86-input-joystick module is what it is not: it is not a joystick driver. If you want to use your joystick in a game under X, you don't need that driver. The xf86-input-joystick module is designed to control the pointer with a joystick device. Sascha gave the example of using an XBox controller to control a Linux-driven media-center. The controller can serve as a cheap remote control (especially if you already have the controller but you'd need to buy a remote ;)

So why is the joystick module not a joystick driver? The evdev driver handles most input devices with arbitrary axes and games can use those devices through evdev. But this is a game-specific application, and the game likely knows what features of the joystick it wants.

For pointer control, it's not quite as obvious. Your average joystick has a couple of axes, four or more buttons and possibly even force feedback. The joystick module's configuration must determine which axis controls the pointer motion (and must be mapped from absolute to relative) and which button generates button (or key) events. Because no two joysticks are the same, there cannot be a sane default for the joystick driver configuration. The default install is thus almost certainly useless and may even interfere with your normal X install.

For example, a joystick sending absolute input events that does not have the mapping configured correctly will force the mouse pointer onto a specific position.That may make it impossible to move the pointer with the mouse.

For this reason, any distribution that ships the joystick module should add Option "Floating" "on" into the default configuration. This way the joystick is detected and enabled in X, but it won't actually control the cursor. This means the joystick may look like it's not working initially to the users who want it, but it's not breaking anything for those that install the module unintentionally. The joystick module should not be part of a default install, it's use-case is too narrow.

Once you're happy using the joystick module for it's intended purpose, there are vast configuration options to suit all tastes:

• Option "MapButton1" "button=3" maps the first joystick button into a right-click (X logical button 3)
• Option "MapButton2" "axis=+5x" maps the second joystick button to a x movement by 5 units
• Option "MapButton3" "keycode=50,40" maps to Shift +d, though you may want to read about keycodes vs keysyms first
• Option  "MapAxis2"      "mode=relative    keylow=111  keyhigh=116" will map the second axis to key events up/down

I recommend reading the joystick(4) man page for further examples on configuration options. Note, the linked man page isn't the latest one, but it's at least rendered in html, not plain roff.