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)