summaryrefslogtreecommitdiff
path: root/man/joystick.man
blob: b401de5fa323ad64f19ec2e168526d57d2c9bc27 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
.\" shorthand for double quote that works everywhere.
.ds q \N'34'
.TH joystick __drivermansuffix__ __vendorversion__
.SH NAME
joystick \- Joystick input driver
.SH SYNOPSIS
Snipped for xorg.conf.d(5):

.nf
.B "Section \*qInputClass\*q"
.BI "  Identifier \*q" joystick-all \*q
.BI  "  Driver \*q" joystick \*q
.BI "  Option \*qMatchIsJoystick\*q   \*q" on \*q
.BI "  Option \*qMatchDevicePath \*q" /dev/input/event* \*q
\ \ ...
.B EndSection
.fi


.SH DESCRIPTION
.B joystick
is an __xservername__ input driver for Joysticks. There are 3 backends available that are used in the following order, if support was found:

.nf
.B - Linux's evdev interface
.B - Linux's joystick interface
.B - BSD's usbhid interface
.fi

The driver reports cursor movement
as well as raw axis values through valuators. 

.SH SUPPORTED HARDWARE
In general, every by the kernel supported joystick should be supported through the
.B joystick
driver. The driver assumes that the joystick is calibrated and reports axis values
between 
.IR "-32768 " and " 32768" .
See the Linux kernel documentation for a complete list of supported devices. 

.SH CONFIGURATION DETAILS
Please refer to __xconfigfile__(__filemansuffix__) for general configuration
details.  This section only covers configuration details specific to this
driver.
.PP
The following Driver
.B Options
are supported:
.TP 7
.BI "Option \*qDevice\*q \*q" string \*q
.TP 7
.BI "Option \*qPath\*q \*q" string \*q
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
.IR /dev/input/jsX " or " /dev/input/eventX .

In *BSD, joysticks are usually recognized as 
.IR /dev/uhidX .
.TP 7
.BI "Option \*qAutoRepeat\*q \*q" "delay rate" \*q
Sets the auto repeat behaviour for key events.
.I delay
is the time in milliseconds before a key starts repeating.
.I rate
is the number of times a key repeats per second.  Default: Xorg default
.TP 7
.BI "Option \*qDebugLevel\*q \*q" integer \*q
If compiled with debugging information, controls the verbosity of the driver.
The higher the DebugLevel, the more output is produced.
Default: 0
.TP 7
.BI "Option \*qMapButton<number>\*q \*q" string \*q
Sets the mapping of the joystick button to the desired action. Counting of buttons starts with 
.IR 1 ,
Possible options are:
.RS 7
.TP 7
.B "none"
This joystick button won't do anything.
.TP 7
.BI "\*qbutton="<number> \*q
The joystick button will generate a click with the specified button (starting with 1).
.TP 7
.BI "\*qaxis="[<factor>]<axis> \*q
Where
.I <axis>
is one of:
.B x, y, zx, zy

and 
.I <factor>
is an optional amplifier of the axis, like
.B -, +, -5, 0.4, 1.3, ...
Use positive and negative values to control the direction. Default: 1.0
.TP 7
.BI "\*qamplify="<factor> \*q
Amplifies the movement of all axes by the given factor when pressed. Different
factors can be combined.
.TP 7
.BI "\*qkey="<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.
.TP 7
.B "\*qdisable-mouse\*q"
.TP 7
.B "\*qdisable-keys\*q"
.TP 7
.B "\*qdisable-all\*q"
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.
.RE
.PP
.TP 7
.BI "Option \*qMapAxis<number>\*q \*q" string \*q
Sets the mapping of the axis to the desired action. Counting of axes starts with
.IR 1 ,
the parameter may contain:
.RS 7
.TP 7
.BI "\*qmode="<string> \*q
Where
.I <string>
can be one of:

.B none, relative, accelerated, absolute

Every axis which's mode is not
.B none
will be reported as an additional valuator.
.TP 7
.B \*qvaluator\*q
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 
.IR -32767 " to " 32768 .
Neither
.B mode
nor
.B axis
needs to be set to generate extra valuator events. The axis will be labelled according to it's physical axis number, beginning with 
.I 1
, i.e.
.I \*qAxis 1\*q
for the first axis (being the 3rd valuator).
Default: not set.
.TP 7
.BI "\*qaxis="[<factor>]<axis> \*q
Where
.I <axis>
is one of:
.B x, y, zx, zy, key (see keylow/keyhigh)

and 
.I <factor>
is an optional amplifier of the axis, like
.B -, +, -5, 0.4, 1.3, ...
Negative values will invert the movement. Default: 1.0
.TP 7
.BI "\*qkeylow= "<scancode>[,<scancode>[,<scancode>[,<scancode>]]]
.TP 7
.BI "\*qkeyhigh="<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. 

.B keylow
defines the keys to be generated when the axis is moved in negative direction (ie. left or up),
.B keyhigh
defines the keys to be generated when the axis is moved in positive direction (ie. right or down).

If 
.B mode
is set to 
.IR 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
.BI "\*qaxis="[<factor>]KEY \*q
parameter.

If 
.B mode
is set to 
.IR 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
.I 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.
.TP 7
.BI "\*qdeadzone="<number> \*q
Sets the unresponsive range of the axis to
.IR <number> .
This can be between
.IR "0" " and " "30000" .
Default: 5000
.RE
.PP
.TP 7
.BI "Option \*qStartKeysEnabled\*q \*q" "boolean" \*q
Set to
.I False
to disable key event generation after startup. You can toggle key event generation with the 
.I disable-keys
button mapping. Default: enabled
.TP 7
.BI "Option \*qStartMouseEnabled\*q \*q" "boolean" \*q
Set to
.I False
to disable mouse event generation after startup. You can toggle mouse event generation with the 
.I disable-mouse
button mapping. Default: enabled
.RE
.PP


.SH "DEFAULT CONFIGURATION"
The default configuration is as follows:

.nf
.BI "  Option \*qDebugLevel\*q        \*q" 0 \*q
.BI "  Option \*qStartKeysEnabled\*q  \*q" True \*q
.BI "  Option \*qStartMouseEnabled\*q \*q" True \*q
.BI "  Option \*qMapButton1\*q        \*q" button=1 \*q
.BI "  Option \*qMapButton2\*q        \*q" button=2 \*q
.BI "  Option \*qMapButton3\*q        \*q" button=3 \*q
.BI "  Option \*qMapButton4\*q        \*q" none \*q
\ \ ...
.BI "  Option \*qMapAxis1\*q          \*q" "mode=relative    axis=+1x  deadzone=5000" \*q
.BI "  Option \*qMapAxis2\*q          \*q" "mode=relative    axis=+1y  deadzone=5000" \*q
.BI "  Option \*qMapAxis3\*q          \*q" "mode=relative    axis=+1zx deadzone=5000" \*q
.BI "  Option \*qMapAxis4\*q          \*q" "mode=relative    axis=+1zy deadzone=5000" \*q
.BI "  Option \*qMapAxis5\*q          \*q" "mode=accelerated axis=+1x  deadzone=5000" \*q
.BI "  Option \*qMapAxis6\*q          \*q" "mode=accelerated axis=+1y  deadzone=5000" \*q
.BI "  Option \*qMapAxis7\*q          \*q" "mode=none" \*q
\ \ ...
.fi

.SH "ACCELERATED AXIS CONFIGURATION"
.B Accelerated
mode should be selected, if the axis is a
.IR 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:
.nf
.BI "  Option \*qMapAxis1\*q     \*q" "mode=accelerated axis=-0.5zy" \*q
.fi

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:
.nf
.BI "  Option \*qMapButton1\*q     \*q" "axis=+0.5x" \*q
.BI "  Option \*qMapButton2\*q     \*q" "axis=-0.5x" \*q
.BI "  Option \*qMapButton3\*q     \*q" "axis=+0.5y" \*q
.BI "  Option \*qMapButton4\*q     \*q" "axis=-0.5y" \*q
.fi

.SH "ABSOLUTE AXIS CONFIGURATION"
With the
.B 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
.I width
of the screen, when mapped to the x-axis and the
.I 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:
.nf 
.BI "  Option \*qMapAxis1\*q     \*q" "mode=absolute axis=x" \*q
.BI "  Option \*qMapAxis2\*q     \*q" "mode=absolute axis=200y" \*q
.fi

.SH "GENERATING KEY EVENTS"
Providing a \*qkey=<scancode>[,<scancode>[...]]\*q 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
.BR "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:
.nf
.BI "  Option \*qMapButton1\*q     \*q" "key=64,23" \*q
.fi
will generate
.I "Alt_L+Tab"
when the button is pressed.

.nf
.BI "  Option \*qMapButton1\*q     \*q" "key=50,40" \*q
.fi
will generate a Shift_L+d which will be an uppercase 
.IR d .

.nf
.BI "  Option \*qMapButton1\*q     \*q" "key=65" \*q
.fi
is for the  
.IR "space " key.

.nf
.BI "  Option  \*qMapAxis1\*q      \*q" "mode=relative    keylow=113  keyhigh=114 axis=0.5key" \*q
.BI "  Option  \*qMapAxis2\*q      \*q" "mode=relative    keylow=111  keyhigh=116" \*q
.BI "  Option  \*qMapAxis3\*q      \*q" "mode=accelerated keylow=113  keyhigh=114" \*q
.BI "  Option  \*qMapAxis4\*q      \*q" "mode=accelerated keylow=111  keyhigh=116" \*q
.fi
will map the first and third axis to the arrow keys
.IR left " and " right
and the second and fourth axis to the arrow keys
.IR 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.

.SH "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:

.nf
.BI "  Option  \*qMapAxis1\*q      \*q" "mode=none valuator" \*q
.BI "  Option  \*qMapAxis2\*q      \*q" "mode=none valuator" \*q
.BI "  Option  \*qMapAxis3\*q      \*q" "mode=none valuator" \*q
.BI "  Option  \*qMapAxis4\*q      \*q" "mode=none valuator" \*q
\ \ ...
.BI "  Option  \*qMapButton1\*q      \*q" "button=1" \*q
.BI "  Option  \*qMapButton2\*q      \*q" "button=2" \*q
.BI "  Option  \*qMapButton3\*q      \*q" "button=3" \*q
.BI "  Option  \*qMapButton4\*q      \*q" "button=4" \*q
.BI "  Option  \*qMapButton5\*q      \*q" "button=5" \*q
\ \ ...
.fi

You might also want to set the device "floating" to stop it from reporting core events:
.nf
.BI "  Option  \*qFloating\*q      \*q" "true" \*q
.fi

.SH "NOTES"
Configuration through
.I 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 
.I ${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 
.I ${sourcecode}/config/50-x11-input-joystick.fdi
to be placed in
.IR /etc/hal/fdi/policy .


.SH "SEE ALSO"
__xservername__(__appmansuffix__), __xconfigfile__(__filemansuffix__), xorg.conf.d(5), Xserver(__appmansuffix__), X(__miscmansuffix__), xmodmap(1)
.SH AUTHORS
Sascha Hlusiak (2007-2011),
.fi
Frederic Lepied (1995-1999)