blob: 8007b7ca87bf751a06b800967c493e90092d3324 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 Linux Joystick driver v2.0.0
2 (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz>
3 Sponsored by SuSE
Linus Torvalds1da177e2005-04-16 15:20:36 -07004----------------------------------------------------------------------------
5
60. Disclaimer
7~~~~~~~~~~~~~
8 This program is free software; you can redistribute it and/or modify it
9under the terms of the GNU General Public License as published by the Free
10Software Foundation; either version 2 of the License, or (at your option)
11any later version.
12
13 This program is distributed in the hope that it will be useful, but
14WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
16more details.
17
18 You should have received a copy of the GNU General Public License along
19with this program; if not, write to the Free Software Foundation, Inc., 59
20Temple Place, Suite 330, Boston, MA 02111-1307 USA
21
22 Should you need to contact me, the author, you can do so either by e-mail
23- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
24Simunkova 1594, Prague 8, 182 00 Czech Republic
25
26 For your convenience, the GNU General Public License version 2 is included
27in the package: See the file COPYING.
28
291. Intro
30~~~~~~~~
31 The joystick driver for Linux provides support for a variety of joysticks
32and similar devices. It is based on a larger project aiming to support all
33input devices in Linux.
34
35 Should you encounter any problems while using the driver, or joysticks
36this driver can't make complete use of, I'm very interested in hearing about
37them. Bug reports and success stories are also welcome.
38
39 The input project website is at:
40
Linus Torvalds1da177e2005-04-16 15:20:36 -070041 http://atrey.karlin.mff.cuni.cz/~vojtech/input/
42
43 There is also a mailing list for the driver at:
44
45 listproc@atrey.karlin.mff.cuni.cz
46
47send "subscribe linux-joystick Your Name" to subscribe to it.
48
492. Usage
50~~~~~~~~
51 For basic usage you just choose the right options in kernel config and
52you should be set.
53
542.1 inpututils
55~~~~~~~~~~~~~~
56For testing and other purposes (for example serial devices), a set of
57utilities is available at the abovementioned website. I suggest you download
58and install it before going on.
59
602.2 Device nodes
61~~~~~~~~~~~~~~~~
Adrian Bunkbf6ee0a2006-10-03 22:17:48 +020062For applications to be able to use the joysticks,
Linus Torvalds1da177e2005-04-16 15:20:36 -070063you'll have to manually create these nodes in /dev:
64
65cd /dev
66rm js*
67mkdir input
68mknod input/js0 c 13 0
69mknod input/js1 c 13 1
70mknod input/js2 c 13 2
71mknod input/js3 c 13 3
72ln -s input/js0 js0
73ln -s input/js1 js1
74ln -s input/js2 js2
75ln -s input/js3 js3
76
77For testing with inpututils it's also convenient to create these:
78
79mknod input/event0 c 13 64
80mknod input/event1 c 13 65
81mknod input/event2 c 13 66
82mknod input/event3 c 13 67
83
842.4 Modules needed
85~~~~~~~~~~~~~~~~~~
86 For all joystick drivers to function, you'll need the userland interface
87module in kernel, either loaded or compiled in:
88
89 modprobe joydev
90
91 For gameport joysticks, you'll have to load the gameport driver as well;
92
93 modprobe ns558
94
95 And for serial port joysticks, you'll need the serial input line
96discipline module loaded and the inputattach utility started:
97
98 modprobe serport
99 inputattach -xxx /dev/tts/X &
100
101 In addition to that, you'll need the joystick driver module itself, most
102usually you'll have an analog joystick:
103
104 modprobe analog
105
106 For automatic module loading, something like this might work - tailor to
107your needs:
108
109 alias tty-ldisc-2 serport
110 alias char-major-13 input
111 above input joydev ns558 analog
112 options analog map=gamepad,none,2btn
113
1142.5 Verifying that it works
115~~~~~~~~~~~~~~~~~~~~~~~~~~~
116 For testing the joystick driver functionality, there is the jstest
117program in the utilities package. You run it by typing:
118
119 jstest /dev/js0
120
121 And it should show a line with the joystick values, which update as you
122move the stick, and press its buttons. The axes should all be zero when the
123joystick is in the center position. They should not jitter by themselves to
124other close values, and they also should be steady in any other position of
125the stick. They should have the full range from -32767 to 32767. If all this
126is met, then it's all fine, and you can play the games. :)
127
128 If it's not, then there might be a problem. Try to calibrate the joystick,
129and if it still doesn't work, read the drivers section of this file, the
130troubleshooting section, and the FAQ.
131
1322.6. Calibration
133~~~~~~~~~~~~~~~~
134 For most joysticks you won't need any manual calibration, since the
135joystick should be autocalibrated by the driver automagically. However, with
136some analog joysticks, that either do not use linear resistors, or if you
137want better precision, you can use the jscal program
138
139 jscal -c /dev/js0
140
141 included in the joystick package to set better correction coefficients than
142what the driver would choose itself.
143
144 After calibrating the joystick you can verify if you like the new
145calibration using the jstest command, and if you do, you then can save the
146correction coefficients into a file
147
148 jscal -p /dev/js0 > /etc/joystick.cal
149
150 And add a line to your rc script executing that file
151
152 source /etc/joystick.cal
153
154 This way, after the next reboot your joystick will remain calibrated. You
155can also add the jscal -p line to your shutdown script.
156
157
1583. HW specific driver information
159~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160In this section each of the separate hardware specific drivers is described.
161
1623.1 Analog joysticks
163~~~~~~~~~~~~~~~~~~~~
164 The analog.c uses the standard analog inputs of the gameport, and thus
165supports all standard joysticks and gamepads. It uses a very advanced
166routine for this, allowing for data precision that can't be found on any
167other system.
168
169 It also supports extensions like additional hats and buttons compatible
170with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
171Cyborg 'digital' joysticks are also supported by this driver, because
172they're basically souped up CHF sticks.
173
174 However the only types that can be autodetected are:
175
176* 2-axis, 4-button joystick
177* 3-axis, 4-button joystick
178* 4-axis, 4-button joystick
179* Saitek Cyborg 'digital' joysticks
180
181 For other joystick types (more/less axes, hats, and buttons) support
182you'll need to specify the types either on the kernel command line or on the
183module command line, when inserting analog into the kernel. The
184parameters are:
185
186 analog.map=<type1>,<type2>,<type3>,....
187
188 'type' is type of the joystick from the table below, defining joysticks
189present on gameports in the system, starting with gameport0, second 'type'
190entry defining joystick on gameport1 and so on.
191
192 Type | Meaning
193 -----------------------------------
194 none | No analog joystick on that port
195 auto | Autodetect joystick
196 2btn | 2-button n-axis joystick
197 y-joy | Two 2-button 2-axis joysticks on an Y-cable
198 y-pad | Two 2-button 2-axis gamepads on an Y-cable
199 fcs | Thrustmaster FCS compatible joystick
200 chf | Joystick with a CH Flightstick compatible hat
201 fullchf | CH Flightstick compatible with two hats and 6 buttons
202 gamepad | 4/6-button n-axis gamepad
203 gamepad8 | 8-button 2-axis gamepad
204
205 In case your joystick doesn't fit in any of the above categories, you can
206specify the type as a number by combining the bits in the table below. This
207is not recommended unless you really know what are you doing. It's not
208dangerous, but not simple either.
209
210 Bit | Meaning
211 --------------------------
212 0 | Axis X1
213 1 | Axis Y1
214 2 | Axis X2
215 3 | Axis Y2
216 4 | Button A
217 5 | Button B
218 6 | Button C
219 7 | Button D
220 8 | CHF Buttons X and Y
221 9 | CHF Hat 1
222 10 | CHF Hat 2
223 11 | FCS Hat
224 12 | Pad Button X
225 13 | Pad Button Y
226 14 | Pad Button U
227 15 | Pad Button V
228 16 | Saitek F1-F4 Buttons
229 17 | Saitek Digital Mode
230 19 | GamePad
231 20 | Joy2 Axis X1
232 21 | Joy2 Axis Y1
233 22 | Joy2 Axis X2
234 23 | Joy2 Axis Y2
235 24 | Joy2 Button A
236 25 | Joy2 Button B
237 26 | Joy2 Button C
238 27 | Joy2 Button D
239 31 | Joy2 GamePad
240
2413.2 Microsoft SideWinder joysticks
242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243 Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
244module. All currently supported joysticks:
245
246* Microsoft SideWinder 3D Pro
247* Microsoft SideWinder Force Feedback Pro
248* Microsoft SideWinder Force Feedback Wheel
249* Microsoft SideWinder FreeStyle Pro
250* Microsoft SideWinder GamePad (up to four, chained)
251* Microsoft SideWinder Precision Pro
252* Microsoft SideWinder Precision Pro USB
253
254 are autodetected, and thus no module parameters are needed.
255
256 There is one caveat with the 3D Pro. There are 9 buttons reported,
257although the joystick has only 8. The 9th button is the mode switch on the
258rear side of the joystick. However, moving it, you'll reset the joystick,
259and make it unresponsive for about a one third of a second. Furthermore, the
260joystick will also re-center itself, taking the position it was in during
261this time as a new center position. Use it if you want, but think first.
262
263 The SideWinder Standard is not a digital joystick, and thus is supported
264by the analog driver described above.
265
2663.3 Logitech ADI devices
267~~~~~~~~~~~~~~~~~~~~~~~~
268 Logitech ADI protocol is supported by the adi.c module. It should support
269any Logitech device using this protocol. This includes, but is not limited
270to:
271
272* Logitech CyberMan 2
273* Logitech ThunderPad Digital
274* Logitech WingMan Extreme Digital
275* Logitech WingMan Formula
276* Logitech WingMan Interceptor
277* Logitech WingMan GamePad
278* Logitech WingMan GamePad USB
279* Logitech WingMan GamePad Extreme
280* Logitech WingMan Extreme Digital 3D
281
282 ADI devices are autodetected, and the driver supports up to two (any
283combination of) devices on a single gameport, using an Y-cable or chained
284together.
285
286 Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
287Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
288handled by the analog driver described above. Logitech WingMan Warrior and
289Logitech Magellan are supported by serial drivers described below. Logitech
290WingMan Force and Logitech WingMan Formula Force are supported by the
291I-Force driver described below. Logitech CyberMan is not supported yet.
292
2933.4 Gravis GrIP
294~~~~~~~~~~~~~~~
295 Gravis GrIP protocol is supported by the grip.c module. It currently
296supports:
297
298* Gravis GamePad Pro
299* Gravis BlackHawk Digital
300* Gravis Xterminator
301* Gravis Xterminator DualControl
302
303 All these devices are autodetected, and you can even use any combination
304of up to two of these pads either chained together or using an Y-cable on a
305single gameport.
306
307GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
308supported by the stinger driver. Other Gravis joysticks are supported by the
309analog driver.
310
3113.5 FPGaming A3D and MadCatz A3D
312~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
313 The Assassin 3D protocol created by FPGaming, is used both by FPGaming
314themselves and is licensed to MadCatz. A3D devices are supported by the
315a3d.c module. It currently supports:
316
317* FPGaming Assassin 3D
318* MadCatz Panther
319* MadCatz Panther XL
320
321 All these devices are autodetected. Because the Assassin 3D and the Panther
322allow connecting analog joysticks to them, you'll need to load the analog
323driver as well to handle the attached joysticks.
324
325 The trackball should work with USB mousedev module as a normal mouse. See
326the USB documentation for how to setup an USB mouse.
327
3283.6 ThrustMaster DirectConnect (BSP)
329~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330 The TM DirectConnect (BSP) protocol is supported by the tmdc.c
331module. This includes, but is not limited to:
332
333* ThrustMaster Millenium 3D Inceptor
334* ThrustMaster 3D Rage Pad
335* ThrustMaster Fusion Digital Game Pad
336
337 Devices not directly supported, but hopefully working are:
338
339* ThrustMaster FragMaster
340* ThrustMaster Attack Throttle
341
342 If you have one of these, contact me.
343
344 TMDC devices are autodetected, and thus no parameters to the module
345are needed. Up to two TMDC devices can be connected to one gameport, using
346an Y-cable.
347
3483.7 Creative Labs Blaster
349~~~~~~~~~~~~~~~~~~~~~~~~~
350 The Blaster protocol is supported by the cobra.c module. It supports only
351the:
352
353* Creative Blaster GamePad Cobra
354
355 Up to two of these can be used on a single gameport, using an Y-cable.
356
3573.8 Genius Digital joysticks
358~~~~~~~~~~~~~~~~~~~~~~~~~~~~
359 The Genius digitally communicating joysticks are supported by the gf2k.c
360module. This includes:
361
362* Genius Flight2000 F-23 joystick
363* Genius Flight2000 F-31 joystick
364* Genius G-09D gamepad
365
366 Other Genius digital joysticks are not supported yet, but support can be
367added fairly easily.
368
3693.9 InterAct Digital joysticks
370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371 The InterAct digitally communicating joysticks are supported by the
372interact.c module. This includes:
373
374* InterAct HammerHead/FX gamepad
375* InterAct ProPad8 gamepad
376
377 Other InterAct digital joysticks are not supported yet, but support can be
378added fairly easily.
379
3803.10 PDPI Lightning 4 gamecards
381~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
382 PDPI Lightning 4 gamecards are supported by the lightning.c module.
383Once the module is loaded, the analog driver can be used to handle the
384joysticks. Digitally communicating joystick will work only on port 0, while
385using Y-cables, you can connect up to 8 analog joysticks to a single L4
386card, 16 in case you have two in your system.
387
3883.11 Trident 4DWave / Aureal Vortex
389~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
390 Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
391provide an "Enhanced Game Port" mode where the soundcard handles polling the
392joystick. This mode is supported by the pcigame.c module. Once loaded the
393analog driver can use the enhanced features of these gameports..
394
3953.13 Crystal SoundFusion
396~~~~~~~~~~~~~~~~~~~~~~~~
397 Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
398Port", much like the 4DWave or Vortex above. This, and also the normal mode
399for the port of the SoundFusion is supported by the cs461x.c module.
400
4013.14 SoundBlaster Live!
402~~~~~~~~~~~~~~~~~~~~~~~~
403 The Live! has a special PCI gameport, which, although it doesn't provide
404any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
Francis Galieguea33f3222010-04-23 00:08:02 +0200405its ISA counterparts. It also requires special support, hence the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700406emu10k1-gp.c module for it instead of the normal ns558.c one.
407
4083.15 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
409~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
410 These PCI soundcards have specific gameports. They are handled by the
411sound drivers themselves. Make sure you select gameport support in the
412joystick menu and sound card support in the sound menu for your appropriate
413card.
414
4153.16 Amiga
416~~~~~~~~~~
417 Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
418driver. Since they can't be autodetected, the driver has a command line.
419
420 amijoy.map=<a>,<b>
421
422 a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
423the Amiga.
424
425 Value | Joystick type
426 ---------------------
427 0 | None
428 1 | 1-button digital joystick
429
430 No 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
4333.17 Game console and 8-bit pads and joysticks
434~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
435See joystick-parport.txt for more info.
436
4373.18 SpaceTec/LabTec devices
438~~~~~~~~~~~~~~~~~~~~~~~~~~~~
439 SpaceTec serial devices communicate using the SpaceWare protocol. It is
440supported by the spaceorb.c and spaceball.c drivers. The devices currently
441supported by spaceorb.c are:
442
443* SpaceTec SpaceBall Avenger
444* SpaceTec SpaceOrb 360
445
446Devices currently supported by spaceball.c are:
447
448* SpaceTec SpaceBall 4000 FLX
449
450 In addition to having the spaceorb/spaceball and serport modules in the
451kernel, you also need to attach a serial port to it. to do that, run the
452inputattach program:
453
454 inputattach --spaceorb /dev/tts/x &
455or
456 inputattach --spaceball /dev/tts/x &
457
458where /dev/tts/x is the serial port which the device is connected to. After
459doing this, the device will be reported and will start working.
460
461 There is one caveat with the SpaceOrb. The button #6, the on the bottom
462side of the orb, although reported as an ordinary button, causes internal
463recentering of the spaceorb, moving the zero point to the position in which
464the ball is at the moment of pressing the button. So, think first before
465you bind it to some other function.
466
467SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
468
4693.19 Logitech SWIFT devices
470~~~~~~~~~~~~~~~~~~~~~~~~~~~
471 The SWIFT serial protocol is supported by the warrior.c module. It
472currently supports only the:
473
474* Logitech WingMan Warrior
475
476but in the future, Logitech CyberMan (the original one, not CM2) could be
477supported as well. To use the module, you need to run inputattach after you
478insert/compile the module into your kernel:
479
480 inputattach --warrior /dev/tts/x &
481
482/dev/tts/x is the serial port your Warrior is attached to.
483
4843.20 Magellan / Space Mouse
485~~~~~~~~~~~~~~~~~~~~~~~~~~~
486 The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
487Systems), for many other companies (Logitech, HP, ...) is supported by the
488joy-magellan module. It currently supports only the:
489
490* Magellan 3D
491* Space Mouse
492
493models, the additional buttons on the 'Plus' versions are not supported yet.
494
495 To use it, you need to attach the serial port to the driver using the
496
497 inputattach --magellan /dev/tts/x &
498
499command. After that the Magellan will be detected, initialized, will beep,
500and the /dev/input/jsX device should become usable.
501
5023.21 I-Force devices
503~~~~~~~~~~~~~~~~~~~~
504 All I-Force devices are supported by the iforce module. This includes:
505
506* AVB Mag Turbo Force
507* AVB Top Shot Pegasus
508* AVB Top Shot Force Feedback Racing Wheel
509* Logitech WingMan Force
510* Logitech WingMan Force Wheel
511* Guillemot Race Leader Force Feedback
512* Guillemot Force Feedback Racing Wheel
513* Thrustmaster Motor Sport GT
514
515 To use it, you need to attach the serial port to the driver using the
516
517 inputattach --iforce /dev/tts/x &
518
519command. After that the I-Force device will be detected, and the
520/dev/input/jsX device should become usable.
521
522 In case you're using the device via the USB port, the inputattach command
523isn't needed.
524
525 The I-Force driver now supports force feedback via the event interface.
526
527 Please note that Logitech WingMan *3D devices are _not_ supported by this
528module, rather by hid. Force feedback is not supported for those devices.
529Logitech gamepads are also hid devices.
530
5313.22 Gravis Stinger gamepad
532~~~~~~~~~~~~~~~~~~~~~~~~~~~
533 The Gravis Stinger serial port gamepad, designed for use with laptop
534computers, is supported by the stinger.c module. To use it, attach the
535serial port to the driver using:
536
537 inputattach --stinger /dev/tty/x &
538
539where x is the number of the serial port.
540
5414. Troubleshooting
542~~~~~~~~~~~~~~~~~~
543 There is quite a high probability that you run into some problems. For
544testing whether the driver works, if in doubt, use the jstest utility in
545some of its modes. The most useful modes are "normal" - for the 1.x
546interface, and "old" for the "0.x" interface. You run it by typing:
547
548 jstest --normal /dev/input/js0
549 jstest --old /dev/input/js0
550
551 Additionally you can do a test with the evtest utility:
552
553 evtest /dev/input/event0
554
555 Oh, and read the FAQ! :)
556
5575. FAQ
558~~~~~~
559Q: Running 'jstest /dev/js0' results in "File not found" error. What's the
560 cause?
561A: The device files don't exist. Create them (see section 2.2).
562
563Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
564 or pad that uses a 9-pin D-type cannon connector to the serial port of my
565 PC?
566A: Yes, it is possible, but it'll burn your serial port or the pad. It
567 won't work, of course.
568
569Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
570A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
571 for them.
572
5736. Programming Interface
574~~~~~~~~~~~~~~~~~~~~~~~~
575 The 1.0 driver uses a new, event based approach to the joystick driver.
576Instead of the user program polling for the joystick values, the joystick
577driver now reports only any changes of its state. See joystick-api.txt,
578joystick.h and jstest.c included in the joystick package for more
579information. The joystick device can be used in either blocking or
580nonblocking mode and supports select() calls.
581
582 For backward compatibility the old (v0.x) interface is still included.
583Any call to the joystick driver using the old interface will return values
584that are compatible to the old interface. This interface is still limited
585to 2 axes, and applications using it usually decode only 2 buttons, although
586the driver provides up to 32.