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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.