Provided by: xserver-xorg-input-joystick_1.3.2-1ubuntu1_i386 bug

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:

       - Linuxs evdev interface
       - Linuxs joystick interface
       - BSDs 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=<keysym>[,<keysym>[,<keysym>[,<keysym>]]]
                     When  button  is pressed, a series of keydown events with
                     the specified keysym is generated.  When  the  button  is
                     released,   keyup   events  in  the  opposite  order  are
                     generated. You can specify up to 4 keysyms 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.

              "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= <keysym>[,<keysym>[,<keysym>[,<keysym>]]]

              "keyhigh=<keysym>[,<keysym>[,<keysym>[,<keysym>]]]
                     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 keysyms 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:  One  keydown  event  is
                     generated,  when  the  axis is moved out of the deadzone,
                     the keyup event is generated, when the axis moves back to
                     the  deadzone. The keys will be autorepeated according to
                     the 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=<keysym>[,<keysym>[...]]"  option  will  generate  X
       Events with the specified keysyms 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.

       The keysym parameter can be defined as a numerical value, which can  be
       looked  up in the file /usr/include/X11/keysymdef.h, or as the symbolic
       identifier (case sensitive, without the leading XK_).

       You can specify up to 4 keysyms  per  joystick  button/axis,  which  is
       useful to use modificators. Make sure you use the modificators that are
       necessary to get a certain keysym.

       Examples:
         Option "MapButton1"     "key=0xffe9,0xff09"
         Option "MapButton1"     "key=Alt_L,Tab"
       will generate Alt_L+Tab when the button is pressed.

         Option "MapButton1"     "key=0xffe1,0x0064"
         Option "MapButton1"     "key=Shift_L,d"
       will generate an uppercase d.

         Option "MapButton1"     "key=0x0020"
         Option "MapButton1"     "key=32"
         Option "MapButton1"     "key=space"
       is for the space key.

         Option  "MapAxis1"      "mode=relative    keylow=Left keyhigh=Right axis=0.5key"
         Option  "MapAxis2"      "mode=relative    keylow=Up   keyhigh=Down"
         Option  "MapAxis3"      "mode=accelerated keylow=Left keyhigh=Right"
         Option  "MapAxis4"      "mode=accelerated keylow=Up   keyhigh=Down"
       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.

VALUATORS

       The driver reports relative cursor movement as valuators 0 and 1.

       Every  axis  will  be associated with an additional valuator, reporting
       the absolute raw values of the axis in the range of -32768 to 32768.

       Axes in the mode "none" will be ignored. The mode has no effect on  the
       reported value. The axis does not need to be assigned to a direction.

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. This is HIGHLY
       experimental and you can’t pass any options to the driver, yet.

       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), xorgconfig(1), Xserver(1), X(7), xmodmap(1)

AUTHORS

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