Documentation/input/joydev/joystick.rst

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