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