NAME¶

joystick - Joystick input driver

SYNOPSIS¶

Snipped for xorg.conf.d(5):

Section "InputClass"
  Identifier "joystick-all"
  Driver "joystick"
  Option "MatchIsJoystick"   "on"
  Option "MatchDevicePath"   "/dev/input/event*"
  ...
EndSection

DESCRIPTION¶

joystick is an Xorg input driver for controlling the pointer with a joystick device.

Use this driver, if you want to

- generate cursor movement, perform button or key events to control desktop and applications

- generate cursor key events for playing legacy games, that have no native joystick support

Do not use, if you want to

- play games, that have native joystick support

- use XI2 applications. The evdev(4) driver will suffice for those in most cases.

You may mix above scenarios by setting the device floating. The driver reports relative cursor movement, button and key events, as well as raw axis values through valuators.

SUPPORTED HARDWARE¶

The joystick input module can be used on top of the following kernel devices:

- Linux's evdev device
- Linux's joystick device
- BSD's usbhid device

Every joystick supported by the kernel should be supported by the joystick input driver. The joystick is assumed to be calibrated and reporting axis values between -32768 and 32768. See the Linux kernel documentation for a complete list of supported devices.

There is no support for force feedback at the moment.

CONFIGURATION DETAILS¶

Please refer to xorg.conf(5) for general configuration details. This section only covers configuration details specific to this driver.

The following Driver Options are supported:

Option "Device" "string"

Option "Path" "string"

Specifies the device through which the joystick can be accessed. This option is mandatory and there is no default setting.

In Linux, joysticks are usually accessible through /dev/input/jsX or /dev/input/eventX.

In *BSD, joysticks are usually recognized as /dev/uhidX.

Option "AutoRepeat" "delay rate"

Sets the auto repeat behaviour for key events. delay is the time in milliseconds before a key starts repeating. rate is the number of times a key repeats per second. Default: Xorg default

Option "DebugLevel" "integer"

Controls the verbosity of the driver for debugging purposes. The higher the DebugLevel, the more output is produced. Default: 0

Option "MapButton<number>" "string"

Sets the mapping of a joystick button to the desired action. Button counting starts with 1, Possible options are:

Option "MapAxis<number>" "string"

Sets the mapping of the axis to the desired action. Axis counting starts with 1, the parameter may contain:

Option "StartKeysEnabled" "boolean"

Set to False to disable key event generation after startup. You can toggle key event generation with the disable-keys button mapping. Default: enabled

Option "StartMouseEnabled" "boolean"

Set to False to disable mouse event generation after startup. You can toggle mouse event generation with the disable-mouse button mapping. Default: enabled

DEFAULT CONFIGURATION¶

The default configuration is as follows:

  Option "DebugLevel"        "0"
  Option "StartKeysEnabled"  "True"
  Option "StartMouseEnabled" "True"
  Option "MapButton1"        "button=1"
  Option "MapButton2"        "button=2"
  Option "MapButton3"        "button=3"
  Option "MapButton4"        "none"
  ...
  Option "MapAxis1"          "mode=relative    axis=+1x  deadzone=5000"
  Option "MapAxis2"          "mode=relative    axis=+1y  deadzone=5000"
  Option "MapAxis3"          "mode=relative    axis=+1zx deadzone=5000"
  Option "MapAxis4"          "mode=relative    axis=+1zy deadzone=5000"
  Option "MapAxis5"          "mode=accelerated axis=+1x  deadzone=5000"
  Option "MapAxis6"          "mode=accelerated axis=+1y  deadzone=5000"
  Option "MapAxis7"          "mode=none"
  ...

ACCELERATED AXIS CONFIGURATION¶

Accelerated mode should be selected, if the axis is a directional pad, which reports only three states: negative, center, positive. It will result in smoothly accelerated movement when the axis is deflected. An optional factor will affect the acceleration and final speed.

This example will set up the axis as scrolling vertically inverted, with half the speed:

  Option "MapAxis1"     "mode=accelerated axis=-0.5zy"

This example maps four buttons to the four pointer directions, so you can use the buttons like a d-pad. The movement will be accelerated with half the normal speed:

  Option "MapButton1"     "axis=+0.5x"
  Option "MapButton2"     "axis=-0.5x"
  Option "MapButton3"     "axis=+0.5y"
  Option "MapButton4"     "axis=-0.5y"

ABSOLUTE AXIS CONFIGURATION¶

In absolute axis mode, the position of the cursor will match the position of the configured axis, but relative to the previous position of the cursor. You can specify the range in which the cursor can move. The default range is the screen size.

In this example the first axis gets a range from left to the right of the screen. The second axis gets a total range of 200 pixels, 100 to the top and 100 to the bottom:

  Option "MapAxis1"     "mode=absolute axis=x"
  Option "MapAxis2"     "mode=absolute axis=200y"

GENERATING KEY EVENTS¶

Providing a "key=<scancode>[,<scancode>[...]]" option will generate X Events with specified scancodes. When the button/axis is released, the keys will be released in opposite order.

If you want a certain KeySym, look up the matching scancode using xmodmap -pk. The scancodes depend on the configured keyboard layout. You can also use unused keycodes and map them to a KeySym of your choice using xmodmap(1).

You can specify up to 4 scancodes per joystick button/axis, which can be used for modificators to get the KeySym you want.

Examples:

  Option "MapButton1"     "key=64,23"

  Option "MapButton1"     "key=50,40"

  Option "MapButton1"     "key=65"

  Option  "MapAxis1"      "mode=relative    keylow=113  keyhigh=114 axis=0.5key"
  Option  "MapAxis2"      "mode=relative    keylow=111  keyhigh=116"
  Option  "MapAxis3"      "mode=accelerated keylow=113  keyhigh=114"
  Option  "MapAxis4"      "mode=accelerated keylow=111  keyhigh=116"

The keys for the first two axes will be generated in an interval according to the value of the axis. The autorepeat speed of the first axis will be half the speed of that of the second axis. The keys for the third and fourth axis are generated once when the axis moves out of the deadzone and when it moves back into the deadzone. X.Org will autorepeat those keys according to current keyboard settings.

XI2 Events¶

If you only care about raw valuator events instead of using the joystick to control the cursor, consider using the evdev(4) input driver. If you still use the joystick driver for raw events, make sure to unmap all axes/buttons and add the valuator option to the axes:

  Option  "MapAxis1"      "mode=none valuator"
  Option  "MapAxis2"      "mode=none valuator"
  Option  "MapAxis3"      "mode=none valuator"
  Option  "MapAxis4"      "mode=none valuator"
  ...
  Option  "MapButton1"      "button=1"
  Option  "MapButton2"      "button=2"
  Option  "MapButton3"      "button=3"
  Option  "MapButton4"      "button=4"
  Option  "MapButton5"      "button=5"
  ...

Remember, that valuators 0 and 1 are reserved for pointer movement, additional axes will start with valuator 2.

You might also want to set the device "floating" to stop it from reporting core events:

  Option  "Floating"      "true"

NOTES¶

It is not recommended to enable the joystick input driver by default unless explicitly requested by the user.

Configuration through InputClass sections is recommended in X servers 1.8 and later. See xorg.conf.d(5) for more details. An example xorg.conf.d(5) snipped is provided in ${sourcecode}/config/50-joystick-all.conf

Configuration through hal fdi files is recommended in X servers 1.5, 1.6 and 1.7. An example hal policy file is still provided in ${sourcecode}/config/50-x11-input-joystick.fdi to be placed in /etc/hal/fdi/policy.

SEE ALSO¶

Xorg(1), xorg.conf(5), xorg.conf.d(5), Xserver(1), X(7), xmodmap(1)

AUTHORS¶

Sascha Hlusiak (2007-2012),
Frederic Lepied (1995-1999)