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