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 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
- "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. The axis will be labelled according to
it's physical axis number, beginning with 1 , i.e. "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, 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.
XI2 Events¶
If you only care about raw events instead of using the joystick as a mouse
replacement, don't forget to unmap and add valuators to all axes and map the
remaining buttons:
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"
...
You might also want to set the device "floating" to stop it from
reporting core events:
Option "Floating" "true"
NOTES¶
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 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-2011),
Frederic Lepied (1995-1999)