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