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/input/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/input/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/input/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/input/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