Man Linux: Main Page and Category List

NAME

       joystick - Joystick input driver

SYNOPSIS

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

DESCRIPTION

       joystick  is  an  Xorg input driver for Joysticks. There are 3 backends
       available that are used in the following order, if support was found:

       - 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

       In  general, every by the kernel supported joystick should be supported
       through the joystick driver. The driver assumes that  the  joystick  is
       calibrated  and  reports axis values between -32768 and 32768.  See the
       Linux kernel documentation for a complete list of supported devices.

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.

              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: 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  pad,  which
       reports  only three states: negative, center, positive. It will produce
       a smooth acceleration of the movement when the axis is  deflected.  The
       speed  will  be  affected  by  the  factor  of  the  axis,  but not the
       acceleration speed.

       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

       With the absolute axis mode, the position of the cursor will  be  fixed
       to  the  position, according to the deflection of the axis.  This fixed
       position is calculated around the previous position of the cursor.  You
       can specify the range in pixels, the cursor can move. The default range
       is the width of the screen, when mapped to the x-axis and the height of
       the  screen,  when mapped to the y-axis. This mode can be combines with
       the other modes without problems.

       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 the specified scancodes when the joystick button is pressed
       or the axis changed it's position. When the  button/axis  is  released,
       the keys are released in the reverse order.

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

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

         Option "MapButton1"     "key=65"
       is for the 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.

NOTES

       The driver does not do hotplugging on it's own. The joystick  needs  to
       be plugged in when the driver is loaded.  If the joystick is unplugged,
       the device will be automatically deactivated.

       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

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

AUTHORS

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