xref: /linux/Documentation/input/joydev/joystick.rst (revision 4f2c0a4acffbec01079c28f839422e64ddeff004)
1.. include:: <isonum.txt>
2
3.. _joystick-doc:
4
5Introduction
6============
7
8The joystick driver for Linux provides support for a variety of joysticks
9and similar devices. It is based on a larger project aiming to support all
10input devices in Linux.
11
12The mailing list for the project is:
13
14	linux-input@vger.kernel.org
15
16send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it.
17
18Usage
19=====
20
21For basic usage you just choose the right options in kernel config and
22you should be set.
23
24Utilities
25---------
26
27For testing and other purposes (for example serial devices), there is a set
28of utilities, such as ``jstest``, ``jscal``, and ``evtest``,
29usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.
30
31``inputattach`` utility is required if your joystick is connected to a
32serial port.
33
34Device nodes
35------------
36
37For applications to be able to use the joysticks, device nodes should be
38created in /dev. Normally it is done automatically by the system, but
39it 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
53For testing with inpututils it's also convenient to create these::
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
60Modules needed
61--------------
62
63For all joystick drivers to function, you'll need the userland interface
64module in kernel, either loaded or compiled in::
65
66	modprobe joydev
67
68For gameport joysticks, you'll have to load the gameport driver as well::
69
70	modprobe ns558
71
72And for serial port joysticks, you'll need the serial input line
73discipline module loaded and the inputattach utility started::
74
75	modprobe serport
76	inputattach -xxx /dev/tts/X &
77
78In addition to that, you'll need the joystick driver module itself, most
79usually you'll have an analog joystick::
80
81	modprobe analog
82
83For automatic module loading, something like this might work - tailor to
84your 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
91Verifying that it works
92-----------------------
93
94For testing the joystick driver functionality, there is the jstest
95program in the utilities package. You run it by typing::
96
97	jstest /dev/input/js0
98
99And it should show a line with the joystick values, which update as you
100move the stick, and press its buttons. The axes should all be zero when the
101joystick is in the center position. They should not jitter by themselves to
102other close values, and they also should be steady in any other position of
103the stick. They should have the full range from -32767 to 32767. If all this
104is met, then it's all fine, and you can play the games. :)
105
106If it's not, then there might be a problem. Try to calibrate the joystick,
107and if it still doesn't work, read the drivers section of this file, the
108troubleshooting section, and the FAQ.
109
110Calibration
111-----------
112
113For most joysticks you won't need any manual calibration, since the
114joystick should be autocalibrated by the driver automagically. However, with
115some analog joysticks, that either do not use linear resistors, or if you
116want better precision, you can use the jscal program::
117
118	jscal -c /dev/input/js0
119
120included in the joystick package to set better correction coefficients than
121what the driver would choose itself.
122
123After calibrating the joystick you can verify if you like the new
124calibration using the jstest command, and if you do, you then can save the
125correction coefficients into a file::
126
127	jscal -p /dev/input/js0 > /etc/joystick.cal
128
129And add a line to your rc script executing that file::
130
131	source /etc/joystick.cal
132
133This way, after the next reboot your joystick will remain calibrated. You
134can also add the ``jscal -p`` line to your shutdown script.
135
136Hardware-specific driver information
137====================================
138
139In this section each of the separate hardware specific drivers is described.
140
141Analog joysticks
142----------------
143
144The analog.c driver uses the standard analog inputs of the gameport, and thus
145supports all standard joysticks and gamepads. It uses a very advanced
146routine for this, allowing for data precision that can't be found on any
147other system.
148
149It also supports extensions like additional hats and buttons compatible
150with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
151Cyborg 'digital' joysticks are also supported by this driver, because
152they're basically souped up CHF sticks.
153
154However the only types that can be autodetected are:
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
161For other joystick types (more/less axes, hats, and buttons) support
162you'll need to specify the types either on the kernel command line or on the
163module command line, when inserting analog into the kernel. The
164parameters are::
165
166	analog.map=<type1>,<type2>,<type3>,....
167
168'type' is type of the joystick from the table below, defining joysticks
169present on gameports in the system, starting with gameport0, second 'type'
170entry defining joystick on gameport1 and so on.
171
172	========= =====================================================
173	Type      Meaning
174	========= =====================================================
175	none      No analog joystick on that port
176	auto      Autodetect joystick
177	2btn      2-button n-axis joystick
178	y-joy     Two 2-button 2-axis joysticks on an Y-cable
179	y-pad     Two 2-button 2-axis gamepads on an Y-cable
180	fcs       Thrustmaster FCS compatible joystick
181	chf       Joystick with a CH Flightstick compatible hat
182	fullchf   CH Flightstick compatible with two hats and 6 buttons
183	gamepad   4/6-button n-axis gamepad
184	gamepad8  8-button 2-axis gamepad
185	========= =====================================================
186
187In case your joystick doesn't fit in any of the above categories, you can
188specify the type as a number by combining the bits in the table below. This
189is not recommended unless you really know what are you doing. It's not
190dangerous, 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
225Microsoft SideWinder joysticks
226------------------------------
227
228Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
229module. 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, chained)
236* Microsoft SideWinder Precision Pro
237* Microsoft SideWinder Precision Pro USB
238
239are autodetected, and thus no module parameters are needed.
240
241There is one caveat with the 3D Pro. There are 9 buttons reported,
242although the joystick has only 8. The 9th button is the mode switch on the
243rear side of the joystick. However, moving it, you'll reset the joystick,
244and make it unresponsive for about a one third of a second. Furthermore, the
245joystick will also re-center itself, taking the position it was in during
246this time as a new center position. Use it if you want, but think first.
247
248The SideWinder Standard is not a digital joystick, and thus is supported
249by the analog driver described above.
250
251Logitech ADI devices
252--------------------
253
254Logitech ADI protocol is supported by the adi.c module. It should support
255any Logitech device using this protocol. This includes, but is not limited
256to:
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
268ADI devices are autodetected, and the driver supports up to two (any
269combination of) devices on a single gameport, using a Y-cable or chained
270together.
271
272Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
273Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
274handled by the analog driver described above. Logitech WingMan Warrior and
275Logitech Magellan are supported by serial drivers described below.  Logitech
276WingMan Force and Logitech WingMan Formula Force are supported by the
277I-Force driver described below. Logitech CyberMan is not supported yet.
278
279Gravis GrIP
280-----------
281
282Gravis GrIP protocol is supported by the grip.c module. It currently
283supports:
284
285* Gravis GamePad Pro
286* Gravis BlackHawk Digital
287* Gravis Xterminator
288* Gravis Xterminator DualControl
289
290All these devices are autodetected, and you can even use any combination
291of up to two of these pads either chained together or using a Y-cable on a
292single gameport.
293
294GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
295supported by the stinger driver. Other Gravis joysticks are supported by the
296analog driver.
297
298FPGaming A3D and MadCatz A3D
299----------------------------
300
301The Assassin 3D protocol created by FPGaming, is used both by FPGaming
302themselves and is licensed to MadCatz. A3D devices are supported by the
303a3d.c module. It currently supports:
304
305* FPGaming Assassin 3D
306* MadCatz Panther
307* MadCatz Panther XL
308
309All these devices are autodetected. Because the Assassin 3D and the Panther
310allow connecting analog joysticks to them, you'll need to load the analog
311driver as well to handle the attached joysticks.
312
313The trackball should work with USB mousedev module as a normal mouse. See
314the USB documentation for how to setup a USB mouse.
315
316ThrustMaster DirectConnect (BSP)
317--------------------------------
318
319The TM DirectConnect (BSP) protocol is supported by the tmdc.c
320module. 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
326Devices not directly supported, but hopefully working are:
327
328* ThrustMaster FragMaster
329* ThrustMaster Attack Throttle
330
331If you have one of these, contact me.
332
333TMDC devices are autodetected, and thus no parameters to the module
334are needed. Up to two TMDC devices can be connected to one gameport, using
335a Y-cable.
336
337Creative Labs Blaster
338---------------------
339
340The Blaster protocol is supported by the cobra.c module. It supports only
341the:
342
343* Creative Blaster GamePad Cobra
344
345Up to two of these can be used on a single gameport, using a Y-cable.
346
347Genius Digital joysticks
348------------------------
349
350The Genius digitally communicating joysticks are supported by the gf2k.c
351module. This includes:
352
353* Genius Flight2000 F-23 joystick
354* Genius Flight2000 F-31 joystick
355* Genius G-09D gamepad
356
357Other Genius digital joysticks are not supported yet, but support can be
358added fairly easily.
359
360InterAct Digital joysticks
361--------------------------
362
363The InterAct digitally communicating joysticks are supported by the
364interact.c module. This includes:
365
366* InterAct HammerHead/FX gamepad
367* InterAct ProPad8 gamepad
368
369Other InterAct digital joysticks are not supported yet, but support can be
370added fairly easily.
371
372PDPI Lightning 4 gamecards
373--------------------------
374
375PDPI Lightning 4 gamecards are supported by the lightning.c module.
376Once the module is loaded, the analog driver can be used to handle the
377joysticks. Digitally communicating joystick will work only on port 0, while
378using Y-cables, you can connect up to 8 analog joysticks to a single L4
379card, 16 in case you have two in your system.
380
381Trident 4DWave / Aureal Vortex
382------------------------------
383
384Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipset
385provide an "Enhanced Game Port" mode where the soundcard handles polling the
386joystick.  This mode is supported by the pcigame.c module. Once loaded the
387analog driver can use the enhanced features of these gameports..
388
389Crystal SoundFusion
390-------------------
391
392Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
393Port", much like the 4DWave or Vortex above. This, and also the normal mode
394for the port of the SoundFusion is supported by the cs461x.c module.
395
396SoundBlaster Live!
397------------------
398
399The Live! has a special PCI gameport, which, although it doesn't provide
400any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
401its ISA counterparts. It also requires special support, hence the
402emu10k1-gp.c module for it instead of the normal ns558.c one.
403
404SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
405------------------------------------------------------------------------
406
407These PCI soundcards have specific gameports. They are handled by the
408sound drivers themselves. Make sure you select gameport support in the
409joystick menu and sound card support in the sound menu for your appropriate
410card.
411
412Amiga
413-----
414
415Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
416driver. Since they can't be autodetected, the driver has a command line:
417
418	amijoy.map=<a>,<b>
419
420a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
421the Amiga.
422
423	====== ===========================
424	Value  Joystick type
425	====== ===========================
426	  0    None
427	  1    1-button digital joystick
428	====== ===========================
429
430No more joystick types are supported now, but that should change in the
431future if I get an Amiga in the reach of my fingers.
432
433Game console and 8-bit pads and joysticks
434-----------------------------------------
435
436These pads and joysticks are not designed for PCs and other computers
437Linux runs on, and usually require a special connector for attaching
438them through a parallel port.
439
440See :ref:`joystick-parport` for more info.
441
442SpaceTec/LabTec devices
443-----------------------
444
445SpaceTec serial devices communicate using the SpaceWare protocol. It is
446supported by the spaceorb.c and spaceball.c drivers. The devices currently
447supported by spaceorb.c are:
448
449* SpaceTec SpaceBall Avenger
450* SpaceTec SpaceOrb 360
451
452Devices currently supported by spaceball.c are:
453
454* SpaceTec SpaceBall 4000 FLX
455
456In addition to having the spaceorb/spaceball and serport modules in the
457kernel, you also need to attach a serial port to it. To do that, run the
458inputattach program::
459
460	inputattach --spaceorb /dev/tts/x &
461
462or::
463
464	inputattach --spaceball /dev/tts/x &
465
466where /dev/tts/x is the serial port which the device is connected to. After
467doing this, the device will be reported and will start working.
468
469There is one caveat with the SpaceOrb. The button #6, the one on the bottom
470side of the orb, although reported as an ordinary button, causes internal
471recentering of the spaceorb, moving the zero point to the position in which
472the ball is at the moment of pressing the button. So, think first before
473you bind it to some other function.
474
475SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
476
477Logitech SWIFT devices
478----------------------
479
480The SWIFT serial protocol is supported by the warrior.c module. It
481currently supports only the:
482
483* Logitech WingMan Warrior
484
485but in the future, Logitech CyberMan (the original one, not CM2) could be
486supported as well. To use the module, you need to run inputattach after you
487insert/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 attached to.
492
493Magellan / Space Mouse
494----------------------
495
496The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
497Systems), for many other companies (Logitech, HP, ...) is supported by the
498joy-magellan module. It currently supports only the:
499
500* Magellan 3D
501* Space Mouse
502
503models; the additional buttons on the 'Plus' versions are not supported yet.
504
505To use it, you need to attach the serial port to the driver using the::
506
507	inputattach --magellan /dev/tts/x &
508
509command. After that the Magellan will be detected, initialized, will beep,
510and the /dev/input/jsX device should become usable.
511
512I-Force devices
513---------------
514
515All I-Force devices are supported by the iforce module. This includes:
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
527To use it, you need to attach the serial port to the driver using the::
528
529	inputattach --iforce /dev/tts/x &
530
531command. After that the I-Force device will be detected, and the
532/dev/input/jsX device should become usable.
533
534In case you're using the device via the USB port, the inputattach command
535isn't needed.
536
537The I-Force driver now supports force feedback via the event interface.
538
539Please note that Logitech WingMan 3D devices are _not_ supported by this
540module, rather by hid. Force feedback is not supported for those devices.
541Logitech gamepads are also hid devices.
542
543Gravis Stinger gamepad
544----------------------
545
546The Gravis Stinger serial port gamepad, designed for use with laptop
547computers, is supported by the stinger.c module. To use it, attach the
548serial port to the driver using::
549
550	inputattach --stinger /dev/tty/x &
551
552where x is the number of the serial port.
553
554Troubleshooting
555===============
556
557There is quite a high probability that you run into some problems. For
558testing whether the driver works, if in doubt, use the jstest utility in
559some of its modes. The most useful modes are "normal" - for the 1.x
560interface, and "old" for the "0.x" interface. You run it by typing::
561
562	jstest --normal /dev/input/js0
563	jstest --old    /dev/input/js0
564
565Additionally you can do a test with the evtest utility::
566
567	evtest /dev/input/event0
568
569Oh, and read the FAQ! :)
570
571FAQ
572===
573
574:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
575    cause?
576:A: The device files don't exist. Create them (see section 2.2).
577
578:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
579    or pad that uses a 9-pin D-type Cannon connector to the serial port of my
580    PC?
581:A: Yes, it is possible, but it'll burn your serial port or the pad. It
582    won't work, of course.
583
584:Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
585:A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
586    for them.
587