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