1 .. include:: <isonum.txt>
2
3 .. _joystick-doc:
4
5 Introduction
6 ============
7
8 The joystick driver for Linux provides support
9 and similar devices. It is based on a larger p
10 input devices in Linux.
11
12 The mailing list for the project is:
13
14 linux-input@vger.kernel.org
15
16 send "subscribe linux-input" to majordomo@vger
17
18 Usage
19 =====
20
21 For basic usage you just choose the right opti
22 you should be set.
23
24 Utilities
25 ---------
26
27 For testing and other purposes (for example se
28 of utilities, such as ``jstest``, ``jscal``, a
29 usually packaged as ``joystick``, ``input-util
30
31 ``inputattach`` utility is required if your jo
32 serial port.
33
34 Device nodes
35 ------------
36
37 For applications to be able to use the joystic
38 created in /dev. Normally it is done automatic
39 it can also be done by hand::
40
41 cd /dev
42 rm js*
43 mkdir input
44 mknod input/js0 c 13 0
45 mknod input/js1 c 13 1
46 mknod input/js2 c 13 2
47 mknod input/js3 c 13 3
48 ln -s input/js0 js0
49 ln -s input/js1 js1
50 ln -s input/js2 js2
51 ln -s input/js3 js3
52
53 For testing with inpututils it's also convenie
54
55 mknod input/event0 c 13 64
56 mknod input/event1 c 13 65
57 mknod input/event2 c 13 66
58 mknod input/event3 c 13 67
59
60 Modules needed
61 --------------
62
63 For all joystick drivers to function, you'll n
64 module in kernel, either loaded or compiled in
65
66 modprobe joydev
67
68 For gameport joysticks, you'll have to load th
69
70 modprobe ns558
71
72 And for serial port joysticks, you'll need the
73 discipline module loaded and the inputattach u
74
75 modprobe serport
76 inputattach -xxx /dev/tts/X &
77
78 In addition to that, you'll need the joystick
79 usually you'll have an analog joystick::
80
81 modprobe analog
82
83 For automatic module loading, something like t
84 your needs::
85
86 alias tty-ldisc-2 serport
87 alias char-major-13 input
88 above input joydev ns558 analog
89 options analog map=gamepad,none,2btn
90
91 Verifying that it works
92 -----------------------
93
94 For testing the joystick driver functionality,
95 program in the utilities package. You run it b
96
97 jstest /dev/input/js0
98
99 And it should show a line with the joystick va
100 move the stick, and press its buttons. The axe
101 joystick is in the center position. They shoul
102 other close values, and they also should be st
103 the stick. They should have the full range fro
104 is met, then it's all fine, and you can play t
105
106 If it's not, then there might be a problem. Tr
107 and if it still doesn't work, read the drivers
108 troubleshooting section, and the FAQ.
109
110 Calibration
111 -----------
112
113 For most joysticks you won't need any manual c
114 joystick should be autocalibrated by the drive
115 some analog joysticks, that either do not use
116 want better precision, you can use the jscal p
117
118 jscal -c /dev/input/js0
119
120 included in the joystick package to set better
121 what the driver would choose itself.
122
123 After calibrating the joystick you can verify
124 calibration using the jstest command, and if y
125 correction coefficients into a file::
126
127 jscal -p /dev/input/js0 > /etc/joystic
128
129 And add a line to your rc script executing tha
130
131 source /etc/joystick.cal
132
133 This way, after the next reboot your joystick
134 can also add the ``jscal -p`` line to your shu
135
136 Hardware-specific driver information
137 ====================================
138
139 In this section each of the separate hardware
140
141 Analog joysticks
142 ----------------
143
144 The analog.c driver uses the standard analog i
145 supports all standard joysticks and gamepads.
146 routine for this, allowing for data precision
147 other system.
148
149 It also supports extensions like additional ha
150 with CH Flightstick Pro, ThrustMaster FCS or 6
151 Cyborg 'digital' joysticks are also supported
152 they're basically souped up CHF sticks.
153
154 However the only types that can be autodetecte
155
156 * 2-axis, 4-button joystick
157 * 3-axis, 4-button joystick
158 * 4-axis, 4-button joystick
159 * Saitek Cyborg 'digital' joysticks
160
161 For other joystick types (more/less axes, hats
162 you'll need to specify the types either on the
163 module command line, when inserting analog int
164 parameters are::
165
166 analog.map=<type1>,<type2>,<type3>,...
167
168 'type' is type of the joystick from the table
169 present on gameports in the system, starting w
170 entry defining joystick on gameport1 and so on
171
172 ========= ============================
173 Type Meaning
174 ========= ============================
175 none No analog joystick on that p
176 auto Autodetect joystick
177 2btn 2-button n-axis joystick
178 y-joy Two 2-button 2-axis joystick
179 y-pad Two 2-button 2-axis gamepads
180 fcs Thrustmaster FCS compatible
181 chf Joystick with a CH Flightsti
182 fullchf CH Flightstick compatible wi
183 gamepad 4/6-button n-axis gamepad
184 gamepad8 8-button 2-axis gamepad
185 ========= ============================
186
187 In case your joystick doesn't fit in any of th
188 specify the type as a number by combining the
189 is not recommended unless you really know what
190 dangerous, but not simple either.
191
192 ==== =========================
193 Bit Meaning
194 ==== =========================
195 0 Axis X1
196 1 Axis Y1
197 2 Axis X2
198 3 Axis Y2
199 4 Button A
200 5 Button B
201 6 Button C
202 7 Button D
203 8 CHF Buttons X and Y
204 9 CHF Hat 1
205 10 CHF Hat 2
206 11 FCS Hat
207 12 Pad Button X
208 13 Pad Button Y
209 14 Pad Button U
210 15 Pad Button V
211 16 Saitek F1-F4 Buttons
212 17 Saitek Digital Mode
213 19 GamePad
214 20 Joy2 Axis X1
215 21 Joy2 Axis Y1
216 22 Joy2 Axis X2
217 23 Joy2 Axis Y2
218 24 Joy2 Button A
219 25 Joy2 Button B
220 26 Joy2 Button C
221 27 Joy2 Button D
222 31 Joy2 GamePad
223 ==== =========================
224
225 Microsoft SideWinder joysticks
226 ------------------------------
227
228 Microsoft 'Digital Overdrive' protocol is supp
229 module. All currently supported joysticks:
230
231 * Microsoft SideWinder 3D Pro
232 * Microsoft SideWinder Force Feedback Pro
233 * Microsoft SideWinder Force Feedback Wheel
234 * Microsoft SideWinder FreeStyle Pro
235 * Microsoft SideWinder GamePad (up to four, ch
236 * Microsoft SideWinder Precision Pro
237 * Microsoft SideWinder Precision Pro USB
238
239 are autodetected, and thus no module parameter
240
241 There is one caveat with the 3D Pro. There are
242 although the joystick has only 8. The 9th butt
243 rear side of the joystick. However, moving it,
244 and make it unresponsive for about a one third
245 joystick will also re-center itself, taking th
246 this time as a new center position. Use it if
247
248 The SideWinder Standard is not a digital joyst
249 by the analog driver described above.
250
251 Logitech ADI devices
252 --------------------
253
254 Logitech ADI protocol is supported by the adi.
255 any Logitech device using this protocol. This
256 to:
257
258 * Logitech CyberMan 2
259 * Logitech ThunderPad Digital
260 * Logitech WingMan Extreme Digital
261 * Logitech WingMan Formula
262 * Logitech WingMan Interceptor
263 * Logitech WingMan GamePad
264 * Logitech WingMan GamePad USB
265 * Logitech WingMan GamePad Extreme
266 * Logitech WingMan Extreme Digital 3D
267
268 ADI devices are autodetected, and the driver s
269 combination of) devices on a single gameport,
270 together.
271
272 Logitech WingMan Joystick, Logitech WingMan At
273 Extreme and Logitech WingMan ThunderPad are no
274 handled by the analog driver described above.
275 Logitech Magellan are supported by serial driv
276 WingMan Force and Logitech WingMan Formula For
277 I-Force driver described below. Logitech Cyber
278
279 Gravis GrIP
280 -----------
281
282 Gravis GrIP protocol is supported by the grip.
283 supports:
284
285 * Gravis GamePad Pro
286 * Gravis BlackHawk Digital
287 * Gravis Xterminator
288 * Gravis Xterminator DualControl
289
290 All these devices are autodetected, and you ca
291 of up to two of these pads either chained toge
292 single gameport.
293
294 GrIP MultiPort isn't supported yet. Gravis Sti
295 supported by the stinger driver. Other Gravis
296 analog driver.
297
298 FPGaming A3D and MadCatz A3D
299 ----------------------------
300
301 The Assassin 3D protocol created by FPGaming,
302 themselves and is licensed to MadCatz. A3D dev
303 a3d.c module. It currently supports:
304
305 * FPGaming Assassin 3D
306 * MadCatz Panther
307 * MadCatz Panther XL
308
309 All these devices are autodetected. Because th
310 allow connecting analog joysticks to them, you
311 driver as well to handle the attached joystick
312
313 The trackball should work with USB mousedev mo
314 the USB documentation for how to setup a USB m
315
316 ThrustMaster DirectConnect (BSP)
317 --------------------------------
318
319 The TM DirectConnect (BSP) protocol is support
320 module. This includes, but is not limited to:
321
322 * ThrustMaster Millennium 3D Interceptor
323 * ThrustMaster 3D Rage Pad
324 * ThrustMaster Fusion Digital Game Pad
325
326 Devices not directly supported, but hopefully
327
328 * ThrustMaster FragMaster
329 * ThrustMaster Attack Throttle
330
331 If you have one of these, contact me.
332
333 TMDC devices are autodetected, and thus no par
334 are needed. Up to two TMDC devices can be conn
335 a Y-cable.
336
337 Creative Labs Blaster
338 ---------------------
339
340 The Blaster protocol is supported by the cobra
341 the:
342
343 * Creative Blaster GamePad Cobra
344
345 Up to two of these can be used on a single gam
346
347 Genius Digital joysticks
348 ------------------------
349
350 The Genius digitally communicating joysticks a
351 module. This includes:
352
353 * Genius Flight2000 F-23 joystick
354 * Genius Flight2000 F-31 joystick
355 * Genius G-09D gamepad
356
357 Other Genius digital joysticks are not support
358 added fairly easily.
359
360 InterAct Digital joysticks
361 --------------------------
362
363 The InterAct digitally communicating joysticks
364 interact.c module. This includes:
365
366 * InterAct HammerHead/FX gamepad
367 * InterAct ProPad8 gamepad
368
369 Other InterAct digital joysticks are not suppo
370 added fairly easily.
371
372 PDPI Lightning 4 gamecards
373 --------------------------
374
375 PDPI Lightning 4 gamecards are supported by th
376 Once the module is loaded, the analog driver c
377 joysticks. Digitally communicating joystick wi
378 using Y-cables, you can connect up to 8 analog
379 card, 16 in case you have two in your system.
380
381 Trident 4DWave / Aureal Vortex
382 ------------------------------
383
384 Soundcards with a Trident 4DWave DX/NX or Aure
385 provide an "Enhanced Game Port" mode where the
386 joystick. This mode is supported by the pciga
387 analog driver can use the enhanced features of
388
389 Crystal SoundFusion
390 -------------------
391
392 Soundcards with Crystal SoundFusion chipsets p
393 Port", much like the 4DWave or Vortex above. T
394 for the port of the SoundFusion is supported b
395
396 SoundBlaster Live!
397 ------------------
398
399 The Live! has a special PCI gameport, which, a
400 any "Enhanced" stuff like 4DWave and friends,
401 its ISA counterparts. It also requires special
402 emu10k1-gp.c module for it instead of the norm
403
404 SoundBlaster 64 and 128 - ES1370 and ES1371, E
405 ----------------------------------------------
406
407 These PCI soundcards have specific gameports.
408 sound drivers themselves. Make sure you select
409 joystick menu and sound card support in the so
410 card.
411
412 Amiga
413 -----
414
415 Amiga joysticks, connected to an Amiga, are su
416 driver. Since they can't be autodetected, the
417
418 amijoy.map=<a>,<b>
419
420 a and b define the joysticks connected to the
421 the Amiga.
422
423 ====== ===========================
424 Value Joystick type
425 ====== ===========================
426 0 None
427 1 1-button digital joystick
428 ====== ===========================
429
430 No more joystick types are supported now, but
431 future if I get an Amiga in the reach of my fi
432
433 Game console and 8-bit pads and joysticks
434 -----------------------------------------
435
436 These pads and joysticks are not designed for
437 Linux runs on, and usually require a special c
438 them through a parallel port.
439
440 See :ref:`joystick-parport` for more info.
441
442 SpaceTec/LabTec devices
443 -----------------------
444
445 SpaceTec serial devices communicate using the
446 supported by the spaceorb.c and spaceball.c dr
447 supported by spaceorb.c are:
448
449 * SpaceTec SpaceBall Avenger
450 * SpaceTec SpaceOrb 360
451
452 Devices currently supported by spaceball.c are
453
454 * SpaceTec SpaceBall 4000 FLX
455
456 In addition to having the spaceorb/spaceball a
457 kernel, you also need to attach a serial port
458 inputattach program::
459
460 inputattach --spaceorb /dev/tts/x &
461
462 or::
463
464 inputattach --spaceball /dev/tts/x &
465
466 where /dev/tts/x is the serial port which the
467 doing this, the device will be reported and wi
468
469 There is one caveat with the SpaceOrb. The but
470 side of the orb, although reported as an ordin
471 recentering of the spaceorb, moving the zero p
472 the ball is at the moment of pressing the butt
473 you bind it to some other function.
474
475 SpaceTec SpaceBall 2003 FLX and 3003 FLX are n
476
477 Logitech SWIFT devices
478 ----------------------
479
480 The SWIFT serial protocol is supported by the
481 currently supports only the:
482
483 * Logitech WingMan Warrior
484
485 but in the future, Logitech CyberMan (the orig
486 supported as well. To use the module, you need
487 insert/compile the module into your kernel::
488
489 inputattach --warrior /dev/tts/x &
490
491 /dev/tts/x is the serial port your Warrior is
492
493 Magellan / Space Mouse
494 ----------------------
495
496 The Magellan (or Space Mouse), manufactured by
497 Systems), for many other companies (Logitech,
498 joy-magellan module. It currently supports onl
499
500 * Magellan 3D
501 * Space Mouse
502
503 models; the additional buttons on the 'Plus' v
504
505 To use it, you need to attach the serial port
506
507 inputattach --magellan /dev/tts/x &
508
509 command. After that the Magellan will be detec
510 and the /dev/input/jsX device should become us
511
512 I-Force devices
513 ---------------
514
515 All I-Force devices are supported by the iforc
516
517 * AVB Mag Turbo Force
518 * AVB Top Shot Pegasus
519 * AVB Top Shot Force Feedback Racing Wheel
520 * Boeder Force Feedback Wheel
521 * Logitech WingMan Force
522 * Logitech WingMan Force Wheel
523 * Guillemot Race Leader Force Feedback
524 * Guillemot Force Feedback Racing Wheel
525 * Thrustmaster Motor Sport GT
526
527 To use it, you need to attach the serial port
528
529 inputattach --iforce /dev/tts/x &
530
531 command. After that the I-Force device will be
532 /dev/input/jsX device should become usable.
533
534 In case you're using the device via the USB po
535 isn't needed.
536
537 The I-Force driver now supports force feedback
538
539 Please note that Logitech WingMan 3D devices a
540 module, rather by hid. Force feedback is not s
541 Logitech gamepads are also hid devices.
542
543 Gravis Stinger gamepad
544 ----------------------
545
546 The Gravis Stinger serial port gamepad, design
547 computers, is supported by the stinger.c modul
548 serial port to the driver using::
549
550 inputattach --stinger /dev/tty/x &
551
552 where x is the number of the serial port.
553
554 Troubleshooting
555 ===============
556
557 There is quite a high probability that you run
558 testing whether the driver works, if in doubt,
559 some of its modes. The most useful modes are "
560 interface, and "old" for the "0.x" interface.
561
562 jstest --normal /dev/input/js0
563 jstest --old /dev/input/js0
564
565 Additionally you can do a test with the evtest
566
567 evtest /dev/input/event0
568
569 Oh, and read the FAQ! :)
570
571 FAQ
572 ===
573
574 :Q: Running 'jstest /dev/input/js0' results in
575 cause?
576 :A: The device files don't exist. Create them
577
578 :Q: Is it possible to connect my old Atari/Com
579 or pad that uses a 9-pin D-type Cannon con
580 PC?
581 :A: Yes, it is possible, but it'll burn your s
582 won't work, of course.
583
584 :Q: My joystick doesn't work with Quake / Quak
585 :A: Quake / Quake 2 don't support joystick. Us
586 for them.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.