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://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.