1 Linux Joystick driver v2.0.0 2 (c) 1996-2000 Vojtech Pavlik <vojtech@suse.cz> 3 Sponsored by SuSE 4 $Id: joystick.txt,v 1.1.1.1 2008/10/15 03:25:56 james26_jang Exp $ 5---------------------------------------------------------------------------- 6 70. Disclaimer 8~~~~~~~~~~~~~ 9 This program is free software; you can redistribute it and/or modify it 10under the terms of the GNU General Public License as published by the Free 11Software Foundation; either version 2 of the License, or (at your option) 12any later version. 13 14 This program is distributed in the hope that it will be useful, but 15WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 16or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 17more details. 18 19 You should have received a copy of the GNU General Public License along 20with this program; if not, write to the Free Software Foundation, Inc., 59 21Temple 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@suse.cz>, or by paper mail: Vojtech Pavlik, 25Ucitelska 1576, Prague 8, 182 00 Czech Republic 26 27 For your convenience, the GNU General Public License version 2 is included 28in the package: See the file COPYING. 29 301. Intro 31~~~~~~~~ 32 The joystick driver for Linux provides support for a variety of joysticks 33and similar devices. It is based on a larger project aiming to support all 34input devices in Linux. 35 36 Should you encounter any problems while using the driver, or joysticks 37this driver can't make complete use of, I'm very interested in hearing about 38them. 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 49send "subscribe linux-joystick Your Name" to subscribe to it. 50 512. Usage 52~~~~~~~~ 53 For basic usage you just choose the right options in kernel config and 54you should be set. 55 562.1 inpututils 57~~~~~~~~~~~~~~ 58For testing and other purposes (for example serial devices), a set of 59utilities is available at the abovementioned website. I suggest you download 60and install it before going on. 61 622.2 Device nodes 63~~~~~~~~~~~~~~~~ 64For applications to be able to use the joysticks, in you don't use devfs, 65you'll have to manually create these nodes in /dev: 66 67cd /dev 68rm js* 69mkdir input 70mknod input/js0 c 13 0 71mknod input/js1 c 13 1 72mknod input/js2 c 13 2 73mknod input/js3 c 13 3 74ln -s input/js0 js0 75ln -s input/js1 js1 76ln -s input/js2 js2 77ln -s input/js3 js3 78 79For testing with inpututils it's also convenient to create these: 80 81mknod input/event0 c 13 64 82mknod input/event1 c 13 65 83mknod input/event2 c 13 66 84mknod input/event3 c 13 67 85 862.4 Modules needed 87~~~~~~~~~~~~~~~~~~ 88 For all joystick drivers to function, you'll need the userland interface 89module 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 98discipline 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 104usually you'll have an analog joystick: 105 106 modprobe analog 107 108 For automatic module loading, something like this might work - tailor to 109your needs: 110 111 alias tty-ldisc-2 serport 112 alias char-major-13 input 113 above input joydev ns558 analog 114 options analog js=gameport 115 1162.5 Verifying that it works 117~~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 For testing the joystick driver functionality, there is the jstest 119program 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 124move the stick, and press its buttons. The axes should all be zero when the 125joystick is in the center position. They should not jitter by themselves to 126other close values, and they also should be steady in any other position of 127the stick. They should have the full range from -32767 to 32767. If all this 128is 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, 131and if it still doesn't work, read the drivers section of this file, the 132troubleshooting section, and the FAQ. 133 1342.6. Calibration 135~~~~~~~~~~~~~~~~ 136 For most joysticks you won't need any manual calibration, since the 137joystick should be autocalibrated by the driver automagically. However, with 138some analog joysticks, that either do not use linear resistors, or if you 139want 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 144what the driver would choose itself. 145 146 After calibrating the joystick you can verify if you like the new 147calibration using the jstest command, and if you do, you then can save the 148correction 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 157can also add the jscal -p line to your shutdown script. 158 159 1603. HW specific driver information 161~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 162In this section each of the separate hardware specific drivers is described. 163 1643.1 Analog joysticks 165~~~~~~~~~~~~~~~~~~~~ 166 The analog.c uses the standard analog inputs of the gameport, and thus 167supports all standard joysticks and gamepads. It uses a very advanced 168routine for this, allowing for data precision that can't be found on any 169other system. 170 171 It also supports extensions like additional hats and buttons compatible 172with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek 173Cyborg 'digital' joysticks are also supported by this driver, because 174they'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 184you'll need to specify the types either on the kernel command line or on the 185module command line, when inserting analog.o into the kernel. The 186parameters are: 187 188 js=type,type,type,.... 189 190 'type' is type of the joystick from the table below, defining joysticks 191present on gameports in the system, starting with gameport0, second 'type' 192entry 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 208specify the type as a number by combining the bits in the table below. This 209is not recommended unless you really know what are you doing. It's not 210dangerous, 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 2433.2 Microsoft SideWinder joysticks 244~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 245 Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c 246module. 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, 259although the joystick has only 8. The 9th button is the mode switch on the 260rear side of the joystick. However, moving it, you'll reset the joystick, 261and make it unresponsive for about a one third of a second. Furthermore, the 262joystick will also re-center itself, taking the position it was in during 263this 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 266by the analog driver described above. 267 2683.3 Logitech ADI devices 269~~~~~~~~~~~~~~~~~~~~~~~~ 270 Logitech ADI protocol is supported by the adi.c module. It should support 271any Logitech device using this protocol. This includes, but is not limited 272to: 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 285combination of) devices on a single gameport, using an Y-cable or chained 286together. 287 288 Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan 289Extreme and Logitech WingMan ThunderPad are not digital joysticks and are 290handled by the analog driver described above. Logitech WingMan Warrior and 291Logitech Magellan are supported by serial drivers described below. Logitech 292WingMan Force and Logitech WingMan Formula Force are supported by the 293I-Force driver described below. Logitech CyberMan is not supported yet. 294 2953.4 Gravis GrIP 296~~~~~~~~~~~~~~~ 297 Gravis GrIP protocol is supported by the grip.c module. It currently 298supports: 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 306of up to two of these pads either chained together or using an Y-cable on a 307single gameport. 308 309GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is 310supported by the stinger driver. Other Gravis joysticks are supported by the 311analog driver. 312 3133.5 FPGaming A3D and MadCatz A3D 314~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 315 The Assassin 3D protocol created by FPGaming, is used both by FPGaming 316themselves and is licensed to MadCatz. A3D devices are supported by the 317a3d.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 324allow connecting analog joysticks to them, you'll need to load the analog 325driver as well to handle the attached joysticks. 326 327 The trackball should work with USB mousedev module as a normal mouse. See 328the USB documentation for how to setup an USB mouse. 329 3303.6 ThrustMaster DirectConnect (BSP) 331~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 332 The TM DirectConnect (BSP) protocol is supported by the tmdc.c 333module. 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 347are needed. Up to two TMDC devices can be connected to one gameport, using 348an Y-cable. 349 3503.7 Creative Labs Blaster 351~~~~~~~~~~~~~~~~~~~~~~~~~ 352 The Blaster protocol is supported by the cobra.c module. It supports only 353the: 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 3593.8 Genius Digital joysticks 360~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 361 The Genius digitally communicating joysticks are supported by the gf2k.c 362module. 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 369added fairly easily. 370 3713.9 InterAct Digital joysticks 372~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 373 The InterAct digitally communicating joysticks are supported by the 374interact.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 380added fairly easily. 381 3823.10 PDPI Lightning 4 gamecards 383~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 384 PDPI Lightning 4 gamecards are supported by the lightning.c module. 385Once the module is loaded, the analog driver can be used to handle the 386joysticks. Digitally communicating joystick will work only on port 0, while 387using Y-cables, you can connect up to 8 analog joysticks to a single L4 388card, 16 in case you have two in your system. 389 3903.11 Trident 4DWave / Aureal Vortex 391~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 392 Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets 393provide an "Enhanced Game Port" mode where the soundcard handles polling the 394joystick. This mode is supported by the pcigame.c module. Once loaded the 395analog driver can use the enhanced features of these gameports.. 396 3973.13 Crystal SoundFusion 398~~~~~~~~~~~~~~~~~~~~~~~~ 399 Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game 400Port", much like the 4DWave or Vortex above. This, and also the normal mode 401for the port of the SoundFusion is supported by the cs461x.c module. 402 4033.14 SoundBlaster Live! 404~~~~~~~~~~~~~~~~~~~~~~~~ 405 The Live! has a special PCI gameport, which, although it doesn't provide 406any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than 407it's ISA counterparts. It also requires special support, hence the 408emu10k1-gp.c module for it instead of the normal ns558.c one. 409 4103.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 413sound drivers themselves. Make sure you select gameport support in the 414joystick menu and sound card support in the sound menu for your appropriate 415card. 416 4173.16 Amiga 418~~~~~~~~~~ 419 Amiga joysticks, connected to an Amiga, are supported by the amijoy.c 420driver. Since they can't be autodetected, the driver has a command line. 421 422 amijoy=a,b 423 424 a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of 425the 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 433future if I get an Amiga in the reach of my fingers. 434 4353.17 Game console and 8-bit pads and joysticks 436~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 437See joystick-parport.txt for more info. 438 4393.18 SpaceTec/LabTec devices 440~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 441 SpaceTec serial devices communicate using the SpaceWare protocol. It is 442supported by the spaceorb.c and spaceball.c drivers. The devices currently 443supported by spaceorb.c are: 444 445* SpaceTec SpaceBall Avenger 446* SpaceTec SpaceOrb 360 447 448Devices 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 453kernel, you also need to attach a serial port to it. to do that, run the 454inputattach program: 455 456 inputattach --spaceorb /dev/tts/x & 457or 458 inputattach --spaceball /dev/tts/x & 459 460where /dev/tts/x is the serial port which the device is connected to. After 461doing 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 464side of the orb, although reported as an ordinary button, causes internal 465recentering of the spaceorb, moving the zero point to the position in which 466the ball is at the moment of pressing the button. So, think first before 467you bind it to some other function. 468 469SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet. 470 4713.19 Logitech SWIFT devices 472~~~~~~~~~~~~~~~~~~~~~~~~~~~ 473 The SWIFT serial protocol is supported by the warrior.c module. It 474currently supports only the: 475 476* Logitech WingMan Warrior 477 478but in the future, Logitech CyberMan (the original one, not CM2) could be 479supported as well. To use the module, you need to run inputattach after you 480insert/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 4863.20 Magellan / Space Mouse 487~~~~~~~~~~~~~~~~~~~~~~~~~~~ 488 The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space 489Systems), for many other companies (Logitech, HP, ...) is supported by the 490joy-magellan module. It currently supports only the: 491 492* Magellan 3D 493* Space Mouse 494 495models, 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 501command. After that the Magellan will be detected, initialized, will beep, 502and the /dev/input/jsX device should become usable. 503 5043.21 I-Force devices 505~~~~~~~~~~~~~~~~~~~~ 506 All I-Force devices are supported by the iforce.c module. This includes: 507 508* AVB Mag Turbo Force 509* AVB Top Shot Pegasus 510* Logitech WingMan Force 511* Logitech WingMan Force 3D 512* Logitech WingMan Force Wheel 513* Logitech WingMan Strike Force 3D 514* Guillemot Race Leader Force Feedback 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 520command. 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 524isn't needed. 525 526 The I-Force driver now supports force feedback via the event interface. 527 5283.22 Gravis Stinger gamepad 529~~~~~~~~~~~~~~~~~~~~~~~~~~~ 530 The Gravis Stinger serial port gamepad, designed for use with laptop 531computers, is supported by the stinger.c module. To use it, attach the 532serial port to the driver using: 533 534 inputattach --stinger /dev/tty/x & 535 536where x is the number of the serial port. 537 5384. Troubleshooting 539~~~~~~~~~~~~~~~~~~ 540 There is quite a high probability that you run into some problems. For 541testing whether the driver works, if in doubt, use the jstest utility in 542some of its modes. The most useful modes are "normal" - for the 1.x 543interface, and "old" for the "0.x" interface. You run it by typing: 544 545 jstest --normal /dev/input/js0 546 jstest --old /dev/input/js0 547 548 Additionally you can do a test with the evtest utility: 549 550 evtest /dev/input/event0 551 552 Oh, and read the FAQ! :) 553 5545. FAQ 555~~~~~~ 556Q: Running 'jstest /dev/js0' results in "File not found" error. What's the 557 cause? 558A: The device files don't exist. Create them (see section 2.2). 559 560Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick 561 or pad that uses a 9-pin D-type cannon connector to the serial port of my 562 PC? 563A: Yes, it is possible, but it'll burn your serial port or the pad. It 564 won't work, of course. 565 566Q: My joystick doesn't work with Quake / Quake 2. What's the cause? 567A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses 568 for them. 569 5706. Programming Interface 571~~~~~~~~~~~~~~~~~~~~~~~~ 572 The 1.0 driver uses a new, event based approach to the joystick driver. 573Instead of the user program polling for the joystick values, the joystick 574driver now reports only any changes of its state. See joystick-api.txt, 575joystick.h and jstest.c included in the joystick package for more 576information. The joystick device can be used in either blocking or 577nonblocking mode and supports select() calls. 578 579 For backward compatibility the old (v0.x) interface is still included. 580Any call to the joystick driver using the old interface will return values 581that are compatible to the old interface. This interface is still limited 582to 2 axes, and applications using it usually decode only 2 buttons, although 583the driver provides up to 32. 584