Name

Synopsis

Section "InputDevice"
  Identifier "devname"
  Driver "joystick"
  Option "Device"   "devpath"
  ...
EndSection

Description

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

The driver reports cursor movement as well as raw axis values through valuators.

Supported Hardware

Configuration Details

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.

For Linux, joysticks are mostly accessible as /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"

If compiled with debugging information, controls the verbosity of the driver. The higher the DebugLevel, the more output is produced. Default: 0

Option "MapButton<number>" "string"

Sets the mapping of the joystick button to the desired action. Counting of buttons starts with 1, Possible options are:

none

This joystick button won't do anything.

"button=<number>"

The joystick button will generate a click with the specified button (starting with 1).

"axis=[<factor>]<axis>"

Where <axis> is one of: x, y, zx, zy

and <factor> is an optional amplifier of the axis, like -, +, -5, 0.4, 1.3, ... Use positive and negative values to control the direction. Default: 1.0

"amplify=<factor>"

Amplifies the movement of all axes by the given factor when pressed. Different factors can be combined.

"key=<scancode>[,<scancode>[,<scancode>[,<scancode>]]]

When button is pressed, a series of keydown events with the specified scancode is generated. When the button is released, keyup events in the opposite order are generated. You can specify up to 4 scancodes per button.

See special section about key events below.

"disable-mouse"

"disable-keys"

"disable-all"

Disables either the generation of mouse events, key events or the generation of all X events by the driver. Press button again to allow the driver to generate events again.

Option "MapAxis<number>" "string"

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

"mode=<string>"

Where <string> can be one of:

none, relative, accelerated, absolute

Every axis which's mode is not none will be reported as an additional valuator.

"valuator"

Send extra valuator events for this axis. The valuators will be numbered ascending, starting with 2 (valuator 0 and 1 are reserved for pointer movement). The range of the valuators is always -32767 to 32768. Neither mode nor axis needs to be set to generate extra valuator events. Default: not set.

"axis=[<factor>]<axis>"

Where <axis> is one of: x, y, zx, zy, key (see keylow/keyhigh)

and <factor> is an optional amplifier of the axis, like -, +, -5, 0.4, 1.3, ... Negative values will invert the movement. Default: 1.0

"keylow= <scancode>[,<scancode>[,<scancode>[,<scancode>]]]

"keyhigh=<scancode>[,<scancode>[,<scancode>[,<scancode>]]]

When the axis is moved out of the deadzone, a series of keydown events according to the direction of the movement is generated. When the axis is released, keyup events will be generated. You can specify up to 4 scancodes for each direction.

keylow defines the keys to be generated when the axis is moved in negative direction (ie. left or up), keyhigh defines the keys to be generated when the axis is moved in positive direction (ie. right or down).

If mode is set to relative: The driver will emulate autorepeat according to the current value of the axis. A keydown and subsequent keyup event will be generated in short time intervals. To modify that interval and the autorepeat speed, supply the "axis=[<factor>]KEY" parameter.

If mode is set to accelerated: Keydown and keyup events will be generated repeatedly. The time between a keydown and a keyup event corresponds to the deflection of the axis. If the axis is deflected by 30%, the key will be considered to be down 300ms out of 1 second. The exact intervals may vary and can be adjusted with the amplify parameter. If the axis is deflected by 100%, there will only be one keydown event, so the key is considered down all the time. The keys will be autorepeated according to the Xorg keyboard settings.

See special section about key events below.

"deadzone=<number>"

Sets the unresponsive range of the axis to <number>. This can be between 0 and 30000. Default:

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:

Default Configuration

  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

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

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

This example maps four buttons to the four half axes, so you can use them like a pad. The movement will get 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 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

To lookup keycodes for KeySyms, you can use xmodmap -pk. You can 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 is useful to use modificators. Make sure you use modificators that are necessary to get a certain keysym.

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"

Notes

There is an example hal policy in ${sourcecode}/config/50-x11-input-joystick.fdi which will take care of hotplugging. Place it in /etc/hal/fdi/policy and customize it to your needs. Pass custom options to the driver using x11_options properties. This requires xorg-server-1.5 or higher.

Make sure you add the "SendCoreEvents" keyword to the device entry of your ServerLayout section of the xorg.conf file, otherwise the device won't report core pointer and core key events.

Example:

    InputDevice     "Joystick1"     "SendCoreEvents"

See Also

Authors

Table of Contents

• Name
• Synopsis
• Description
• Supported Hardware
• Configuration Details
• Default Configuration
• Accelerated Axis Configuration
• Absolute Axis Configuration
• Generating Key Events
• Notes
• See Also
• Authors