Provided by: xserver-xorg-input-joystick_1.4.0-0ubuntu1_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.

              "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= <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.

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

AUTHORS

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