Documentation/input/joystick.txt

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