Provided by: xserver-xorg-input-joystick_1.6.3-1.1_amd64 bug

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:

              none   Don't do anything

              "button=<number>"
                     Generate a pointer button event with button number (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,
                     ...  Negative values invert the direction. Default: 1.0

              "amplify=<factor>"
                     Amplifies the movement of all axes by the given factor when this  button  is
                     held down. Different factors can be combined.

              "key=<scancode>[,<scancode>[,<scancode>[,<scancode>]]]
                     When  button  is  pressed,  a  series  of  keydown events with the specified
                     scancodes is generated. When the button is released, matching  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.

                     You may also set the device floating from client space to  prevent  it  from
                     generating core events.

       Option "MapAxis<number>" "string"
              Sets  the  mapping  of the axis to the desired action. Axis counting starts with 1,
              the parameter may contain:

              "mode=<string>"
                     Where <string> can be one of:

                     none, relative, accelerated, absolute

              "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). Please consider using the evdev(4) input driver if you  are  only
                     interested in XI2 features.

                     The range of the valuators is always -32767 to 32768.  Neither mode nor axis
                     needs to be set to generate extra valuator events. The axis will be labelled
                     according to its physical axis number, beginning with 1 , e.g.  "Axis 1" for
                     the first axis (being the 3rd valuator).  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, matching keyup events in opposite order 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  (left  or  up), keyhigh defines the keys to be generated when the
                     axis is moved in positive direction (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: 5000

       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"
       will generate Alt_L+Tab when the button is pressed.

         Option "MapButton1"     "key=50,40"
       will generate a Shift_L+d which will result in an uppercase d.

         Option "MapButton1"     "key=65"
       will result in a space key.

         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"
       will  map  the  first  and  third axis to the arrow keys left and right and the second and
       fourth axis to the arrow keys up and down.

       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 explicitely
       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)