joystick

joystick(4)                 Kernel Interfaces Manual                 joystick(4)



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)



X Version 11                xf86-input-joystick 1.6.2                joystick(4)