587 lines · plain
1.. include:: <isonum.txt>2 3.. _joystick-doc:4 5Introduction6============7 8The joystick driver for Linux provides support for a variety of joysticks9and similar devices. It is based on a larger project aiming to support all10input devices in Linux.11 12The mailing list for the project is:13 14 linux-input@vger.kernel.org15 16send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it.17 18Usage19=====20 21For basic usage you just choose the right options in kernel config and22you should be set.23 24Utilities25---------26 27For testing and other purposes (for example serial devices), there is a set28of utilities, such as ``jstest``, ``jscal``, and ``evtest``,29usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.30 31``inputattach`` utility is required if your joystick is connected to a32serial port.33 34Device nodes35------------36 37For applications to be able to use the joysticks, device nodes should be38created in /dev. Normally it is done automatically by the system, but39it can also be done by hand::40 41 cd /dev42 rm js*43 mkdir input44 mknod input/js0 c 13 045 mknod input/js1 c 13 146 mknod input/js2 c 13 247 mknod input/js3 c 13 348 ln -s input/js0 js049 ln -s input/js1 js150 ln -s input/js2 js251 ln -s input/js3 js352 53For testing with inpututils it's also convenient to create these::54 55 mknod input/event0 c 13 6456 mknod input/event1 c 13 6557 mknod input/event2 c 13 6658 mknod input/event3 c 13 6759 60Modules needed61--------------62 63For all joystick drivers to function, you'll need the userland interface64module in kernel, either loaded or compiled in::65 66 modprobe joydev67 68For gameport joysticks, you'll have to load the gameport driver as well::69 70 modprobe ns55871 72And for serial port joysticks, you'll need the serial input line73discipline module loaded and the inputattach utility started::74 75 modprobe serport76 inputattach -xxx /dev/tts/X &77 78In addition to that, you'll need the joystick driver module itself, most79usually you'll have an analog joystick::80 81 modprobe analog82 83For automatic module loading, something like this might work - tailor to84your needs::85 86 alias tty-ldisc-2 serport87 alias char-major-13 input88 above input joydev ns558 analog89 options analog map=gamepad,none,2btn90 91Verifying that it works92-----------------------93 94For testing the joystick driver functionality, there is the jstest95program in the utilities package. You run it by typing::96 97 jstest /dev/input/js098 99And it should show a line with the joystick values, which update as you100move the stick, and press its buttons. The axes should all be zero when the101joystick is in the center position. They should not jitter by themselves to102other close values, and they also should be steady in any other position of103the stick. They should have the full range from -32767 to 32767. If all this104is met, then it's all fine, and you can play the games. :)105 106If it's not, then there might be a problem. Try to calibrate the joystick,107and if it still doesn't work, read the drivers section of this file, the108troubleshooting section, and the FAQ.109 110Calibration111-----------112 113For most joysticks you won't need any manual calibration, since the114joystick should be autocalibrated by the driver automagically. However, with115some analog joysticks, that either do not use linear resistors, or if you116want better precision, you can use the jscal program::117 118 jscal -c /dev/input/js0119 120included in the joystick package to set better correction coefficients than121what the driver would choose itself.122 123After calibrating the joystick you can verify if you like the new124calibration using the jstest command, and if you do, you then can save the125correction coefficients into a file::126 127 jscal -p /dev/input/js0 > /etc/joystick.cal128 129And add a line to your rc script executing that file::130 131 source /etc/joystick.cal132 133This way, after the next reboot your joystick will remain calibrated. You134can also add the ``jscal -p`` line to your shutdown script.135 136Hardware-specific driver information137====================================138 139In this section each of the separate hardware specific drivers is described.140 141Analog joysticks142----------------143 144The analog.c driver uses the standard analog inputs of the gameport, and thus145supports all standard joysticks and gamepads. It uses a very advanced146routine for this, allowing for data precision that can't be found on any147other system.148 149It also supports extensions like additional hats and buttons compatible150with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek151Cyborg 'digital' joysticks are also supported by this driver, because152they're basically souped up CHF sticks.153 154However the only types that can be autodetected are:155 156* 2-axis, 4-button joystick157* 3-axis, 4-button joystick158* 4-axis, 4-button joystick159* Saitek Cyborg 'digital' joysticks160 161For other joystick types (more/less axes, hats, and buttons) support162you'll need to specify the types either on the kernel command line or on the163module command line, when inserting analog into the kernel. The164parameters are::165 166 analog.map=<type1>,<type2>,<type3>,....167 168'type' is type of the joystick from the table below, defining joysticks169present on gameports in the system, starting with gameport0, second 'type'170entry defining joystick on gameport1 and so on.171 172 ========= =====================================================173 Type Meaning174 ========= =====================================================175 none No analog joystick on that port176 auto Autodetect joystick177 2btn 2-button n-axis joystick178 y-joy Two 2-button 2-axis joysticks on an Y-cable179 y-pad Two 2-button 2-axis gamepads on an Y-cable180 fcs Thrustmaster FCS compatible joystick181 chf Joystick with a CH Flightstick compatible hat182 fullchf CH Flightstick compatible with two hats and 6 buttons183 gamepad 4/6-button n-axis gamepad184 gamepad8 8-button 2-axis gamepad185 ========= =====================================================186 187In case your joystick doesn't fit in any of the above categories, you can188specify the type as a number by combining the bits in the table below. This189is not recommended unless you really know what are you doing. It's not190dangerous, but not simple either.191 192 ==== =========================193 Bit Meaning194 ==== =========================195 0 Axis X1196 1 Axis Y1197 2 Axis X2198 3 Axis Y2199 4 Button A200 5 Button B201 6 Button C202 7 Button D203 8 CHF Buttons X and Y204 9 CHF Hat 1205 10 CHF Hat 2206 11 FCS Hat207 12 Pad Button X208 13 Pad Button Y209 14 Pad Button U210 15 Pad Button V211 16 Saitek F1-F4 Buttons212 17 Saitek Digital Mode213 19 GamePad214 20 Joy2 Axis X1215 21 Joy2 Axis Y1216 22 Joy2 Axis X2217 23 Joy2 Axis Y2218 24 Joy2 Button A219 25 Joy2 Button B220 26 Joy2 Button C221 27 Joy2 Button D222 31 Joy2 GamePad223 ==== =========================224 225Microsoft SideWinder joysticks226------------------------------227 228Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c229module. All currently supported joysticks:230 231* Microsoft SideWinder 3D Pro232* Microsoft SideWinder Force Feedback Pro233* Microsoft SideWinder Force Feedback Wheel234* Microsoft SideWinder FreeStyle Pro235* Microsoft SideWinder GamePad (up to four, chained)236* Microsoft SideWinder Precision Pro237* Microsoft SideWinder Precision Pro USB238 239are autodetected, and thus no module parameters are needed.240 241There is one caveat with the 3D Pro. There are 9 buttons reported,242although the joystick has only 8. The 9th button is the mode switch on the243rear side of the joystick. However, moving it, you'll reset the joystick,244and make it unresponsive for about a one third of a second. Furthermore, the245joystick will also re-center itself, taking the position it was in during246this time as a new center position. Use it if you want, but think first.247 248The SideWinder Standard is not a digital joystick, and thus is supported249by the analog driver described above.250 251Logitech ADI devices252--------------------253 254Logitech ADI protocol is supported by the adi.c module. It should support255any Logitech device using this protocol. This includes, but is not limited256to:257 258* Logitech CyberMan 2259* Logitech ThunderPad Digital260* Logitech WingMan Extreme Digital261* Logitech WingMan Formula262* Logitech WingMan Interceptor263* Logitech WingMan GamePad264* Logitech WingMan GamePad USB265* Logitech WingMan GamePad Extreme266* Logitech WingMan Extreme Digital 3D267 268ADI devices are autodetected, and the driver supports up to two (any269combination of) devices on a single gameport, using a Y-cable or chained270together.271 272Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan273Extreme and Logitech WingMan ThunderPad are not digital joysticks and are274handled by the analog driver described above. Logitech WingMan Warrior and275Logitech Magellan are supported by serial drivers described below. Logitech276WingMan Force and Logitech WingMan Formula Force are supported by the277I-Force driver described below. Logitech CyberMan is not supported yet.278 279Gravis GrIP280-----------281 282Gravis GrIP protocol is supported by the grip.c module. It currently283supports:284 285* Gravis GamePad Pro286* Gravis BlackHawk Digital287* Gravis Xterminator288* Gravis Xterminator DualControl289 290All these devices are autodetected, and you can even use any combination291of up to two of these pads either chained together or using a Y-cable on a292single gameport.293 294GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is295supported by the stinger driver. Other Gravis joysticks are supported by the296analog driver.297 298FPGaming A3D and MadCatz A3D299----------------------------300 301The Assassin 3D protocol created by FPGaming, is used both by FPGaming302themselves and is licensed to MadCatz. A3D devices are supported by the303a3d.c module. It currently supports:304 305* FPGaming Assassin 3D306* MadCatz Panther307* MadCatz Panther XL308 309All these devices are autodetected. Because the Assassin 3D and the Panther310allow connecting analog joysticks to them, you'll need to load the analog311driver as well to handle the attached joysticks.312 313The trackball should work with USB mousedev module as a normal mouse. See314the USB documentation for how to setup a USB mouse.315 316ThrustMaster DirectConnect (BSP)317--------------------------------318 319The TM DirectConnect (BSP) protocol is supported by the tmdc.c320module. This includes, but is not limited to:321 322* ThrustMaster Millennium 3D Interceptor323* ThrustMaster 3D Rage Pad324* ThrustMaster Fusion Digital Game Pad325 326Devices not directly supported, but hopefully working are:327 328* ThrustMaster FragMaster329* ThrustMaster Attack Throttle330 331If you have one of these, contact me.332 333TMDC devices are autodetected, and thus no parameters to the module334are needed. Up to two TMDC devices can be connected to one gameport, using335a Y-cable.336 337Creative Labs Blaster338---------------------339 340The Blaster protocol is supported by the cobra.c module. It supports only341the:342 343* Creative Blaster GamePad Cobra344 345Up to two of these can be used on a single gameport, using a Y-cable.346 347Genius Digital joysticks348------------------------349 350The Genius digitally communicating joysticks are supported by the gf2k.c351module. This includes:352 353* Genius Flight2000 F-23 joystick354* Genius Flight2000 F-31 joystick355* Genius G-09D gamepad356 357Other Genius digital joysticks are not supported yet, but support can be358added fairly easily.359 360InterAct Digital joysticks361--------------------------362 363The InterAct digitally communicating joysticks are supported by the364interact.c module. This includes:365 366* InterAct HammerHead/FX gamepad367* InterAct ProPad8 gamepad368 369Other InterAct digital joysticks are not supported yet, but support can be370added fairly easily.371 372PDPI Lightning 4 gamecards373--------------------------374 375PDPI Lightning 4 gamecards are supported by the lightning.c module.376Once the module is loaded, the analog driver can be used to handle the377joysticks. Digitally communicating joystick will work only on port 0, while378using Y-cables, you can connect up to 8 analog joysticks to a single L4379card, 16 in case you have two in your system.380 381Trident 4DWave / Aureal Vortex382------------------------------383 384Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipset385provide an "Enhanced Game Port" mode where the soundcard handles polling the386joystick. This mode is supported by the pcigame.c module. Once loaded the387analog driver can use the enhanced features of these gameports..388 389Crystal SoundFusion390-------------------391 392Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game393Port", much like the 4DWave or Vortex above. This, and also the normal mode394for the port of the SoundFusion is supported by the cs461x.c module.395 396SoundBlaster Live!397------------------398 399The Live! has a special PCI gameport, which, although it doesn't provide400any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than401its ISA counterparts. It also requires special support, hence the402emu10k1-gp.c module for it instead of the normal ns558.c one.403 404SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes405------------------------------------------------------------------------406 407These PCI soundcards have specific gameports. They are handled by the408sound drivers themselves. Make sure you select gameport support in the409joystick menu and sound card support in the sound menu for your appropriate410card.411 412Amiga413-----414 415Amiga joysticks, connected to an Amiga, are supported by the amijoy.c416driver. Since they can't be autodetected, the driver has a command line:417 418 amijoy.map=<a>,<b>419 420a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of421the Amiga.422 423 ====== ===========================424 Value Joystick type425 ====== ===========================426 0 None427 1 1-button digital joystick428 ====== ===========================429 430No more joystick types are supported now, but that should change in the431future if I get an Amiga in the reach of my fingers.432 433Game console and 8-bit pads and joysticks434-----------------------------------------435 436These pads and joysticks are not designed for PCs and other computers437Linux runs on, and usually require a special connector for attaching438them through a parallel port.439 440See :ref:`joystick-parport` for more info.441 442SpaceTec/LabTec devices443-----------------------444 445SpaceTec serial devices communicate using the SpaceWare protocol. It is446supported by the spaceorb.c and spaceball.c drivers. The devices currently447supported by spaceorb.c are:448 449* SpaceTec SpaceBall Avenger450* SpaceTec SpaceOrb 360451 452Devices currently supported by spaceball.c are:453 454* SpaceTec SpaceBall 4000 FLX455 456In addition to having the spaceorb/spaceball and serport modules in the457kernel, you also need to attach a serial port to it. To do that, run the458inputattach program::459 460 inputattach --spaceorb /dev/tts/x &461 462or::463 464 inputattach --spaceball /dev/tts/x &465 466where /dev/tts/x is the serial port which the device is connected to. After467doing this, the device will be reported and will start working.468 469There is one caveat with the SpaceOrb. The button #6, the one on the bottom470side of the orb, although reported as an ordinary button, causes internal471recentering of the spaceorb, moving the zero point to the position in which472the ball is at the moment of pressing the button. So, think first before473you bind it to some other function.474 475SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.476 477Logitech SWIFT devices478----------------------479 480The SWIFT serial protocol is supported by the warrior.c module. It481currently supports only the:482 483* Logitech WingMan Warrior484 485but in the future, Logitech CyberMan (the original one, not CM2) could be486supported as well. To use the module, you need to run inputattach after you487insert/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 493Magellan / Space Mouse494----------------------495 496The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space497Systems), for many other companies (Logitech, HP, ...) is supported by the498joy-magellan module. It currently supports only the:499 500* Magellan 3D501* Space Mouse502 503models; the additional buttons on the 'Plus' versions are not supported yet.504 505To use it, you need to attach the serial port to the driver using the::506 507 inputattach --magellan /dev/tts/x &508 509command. After that the Magellan will be detected, initialized, will beep,510and the /dev/input/jsX device should become usable.511 512I-Force devices513---------------514 515All I-Force devices are supported by the iforce module. This includes:516 517* AVB Mag Turbo Force518* AVB Top Shot Pegasus519* AVB Top Shot Force Feedback Racing Wheel520* Boeder Force Feedback Wheel521* Logitech WingMan Force522* Logitech WingMan Force Wheel523* Guillemot Race Leader Force Feedback524* Guillemot Force Feedback Racing Wheel525* Thrustmaster Motor Sport GT526 527To use it, you need to attach the serial port to the driver using the::528 529 inputattach --iforce /dev/tts/x &530 531command. After that the I-Force device will be detected, and the532/dev/input/jsX device should become usable.533 534In case you're using the device via the USB port, the inputattach command535isn't needed.536 537The I-Force driver now supports force feedback via the event interface.538 539Please note that Logitech WingMan 3D devices are _not_ supported by this540module, rather by hid. Force feedback is not supported for those devices.541Logitech gamepads are also hid devices.542 543Gravis Stinger gamepad544----------------------545 546The Gravis Stinger serial port gamepad, designed for use with laptop547computers, is supported by the stinger.c module. To use it, attach the548serial port to the driver using::549 550 inputattach --stinger /dev/tty/x &551 552where x is the number of the serial port.553 554Troubleshooting555===============556 557There is quite a high probability that you run into some problems. For558testing whether the driver works, if in doubt, use the jstest utility in559some of its modes. The most useful modes are "normal" - for the 1.x560interface, and "old" for the "0.x" interface. You run it by typing::561 562 jstest --normal /dev/input/js0563 jstest --old /dev/input/js0564 565Additionally you can do a test with the evtest utility::566 567 evtest /dev/input/event0568 569Oh, and read the FAQ! :)570 571FAQ572===573 574:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the575 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 joystick579 or pad that uses a 9-pin D-type Cannon connector to the serial port of my580 PC?581:A: Yes, it is possible, but it'll burn your serial port or the pad. It582 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 keypresses586 for them.587