joystick(4)joystick(4)NAMEjoystick - Joystick input driver
SYNOPSIS
Section "InputDevice"
Identifier "devname"
Driver "joystick"
Option "Device" "devpath"
...
EndSection
DESCRIPTIONjoystick 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 speci‐
fied 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 gener‐
ated. 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 key‐
low/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" parame‐
ter.
If mode is set to accelerated: One keydown event is gen‐
erated, 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 accelera‐
tion 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 use‐
ful 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 ALSOXorg(1), xorg.conf(5), Xserver(1), X(7), xmodmap(1)AUTHORS
Sascha Hlusiak (2007-2008),
Frederic Lepied (1995-1999)
X Version 11 xf86-input-joystick 1.4.0 joystick(4)
