0001 .. include:: <isonum.txt>
0002
0003 .. _joystick-doc:
0004
0005 Introduction
0006 ============
0007
0008 The joystick driver for Linux provides support for a variety of joysticks
0009 and similar devices. It is based on a larger project aiming to support all
0010 input devices in Linux.
0011
0012 The mailing list for the project is:
0013
0014 linux-input@vger.kernel.org
0015
0016 send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it.
0017
0018 Usage
0019 =====
0020
0021 For basic usage you just choose the right options in kernel config and
0022 you should be set.
0023
0024 Utilities
0025 ---------
0026
0027 For testing and other purposes (for example serial devices), there is a set
0028 of utilities, such as ``jstest``, ``jscal``, and ``evtest``,
0029 usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.
0030
0031 ``inputattach`` utility is required if your joystick is connected to a
0032 serial port.
0033
0034 Device nodes
0035 ------------
0036
0037 For applications to be able to use the joysticks, device nodes should be
0038 created in /dev. Normally it is done automatically by the system, but
0039 it can also be done by hand::
0040
0041 cd /dev
0042 rm js*
0043 mkdir input
0044 mknod input/js0 c 13 0
0045 mknod input/js1 c 13 1
0046 mknod input/js2 c 13 2
0047 mknod input/js3 c 13 3
0048 ln -s input/js0 js0
0049 ln -s input/js1 js1
0050 ln -s input/js2 js2
0051 ln -s input/js3 js3
0052
0053 For testing with inpututils it's also convenient to create these::
0054
0055 mknod input/event0 c 13 64
0056 mknod input/event1 c 13 65
0057 mknod input/event2 c 13 66
0058 mknod input/event3 c 13 67
0059
0060 Modules needed
0061 --------------
0062
0063 For all joystick drivers to function, you'll need the userland interface
0064 module in kernel, either loaded or compiled in::
0065
0066 modprobe joydev
0067
0068 For gameport joysticks, you'll have to load the gameport driver as well::
0069
0070 modprobe ns558
0071
0072 And for serial port joysticks, you'll need the serial input line
0073 discipline module loaded and the inputattach utility started::
0074
0075 modprobe serport
0076 inputattach -xxx /dev/tts/X &
0077
0078 In addition to that, you'll need the joystick driver module itself, most
0079 usually you'll have an analog joystick::
0080
0081 modprobe analog
0082
0083 For automatic module loading, something like this might work - tailor to
0084 your needs::
0085
0086 alias tty-ldisc-2 serport
0087 alias char-major-13 input
0088 above input joydev ns558 analog
0089 options analog map=gamepad,none,2btn
0090
0091 Verifying that it works
0092 -----------------------
0093
0094 For testing the joystick driver functionality, there is the jstest
0095 program in the utilities package. You run it by typing::
0096
0097 jstest /dev/input/js0
0098
0099 And it should show a line with the joystick values, which update as you
0100 move the stick, and press its buttons. The axes should all be zero when the
0101 joystick is in the center position. They should not jitter by themselves to
0102 other close values, and they also should be steady in any other position of
0103 the stick. They should have the full range from -32767 to 32767. If all this
0104 is met, then it's all fine, and you can play the games. :)
0105
0106 If it's not, then there might be a problem. Try to calibrate the joystick,
0107 and if it still doesn't work, read the drivers section of this file, the
0108 troubleshooting section, and the FAQ.
0109
0110 Calibration
0111 -----------
0112
0113 For most joysticks you won't need any manual calibration, since the
0114 joystick should be autocalibrated by the driver automagically. However, with
0115 some analog joysticks, that either do not use linear resistors, or if you
0116 want better precision, you can use the jscal program::
0117
0118 jscal -c /dev/input/js0
0119
0120 included in the joystick package to set better correction coefficients than
0121 what the driver would choose itself.
0122
0123 After calibrating the joystick you can verify if you like the new
0124 calibration using the jstest command, and if you do, you then can save the
0125 correction coefficients into a file::
0126
0127 jscal -p /dev/input/js0 > /etc/joystick.cal
0128
0129 And add a line to your rc script executing that file::
0130
0131 source /etc/joystick.cal
0132
0133 This way, after the next reboot your joystick will remain calibrated. You
0134 can also add the ``jscal -p`` line to your shutdown script.
0135
0136 Hardware-specific driver information
0137 ====================================
0138
0139 In this section each of the separate hardware specific drivers is described.
0140
0141 Analog joysticks
0142 ----------------
0143
0144 The analog.c driver uses the standard analog inputs of the gameport, and thus
0145 supports all standard joysticks and gamepads. It uses a very advanced
0146 routine for this, allowing for data precision that can't be found on any
0147 other system.
0148
0149 It also supports extensions like additional hats and buttons compatible
0150 with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
0151 Cyborg 'digital' joysticks are also supported by this driver, because
0152 they're basically souped up CHF sticks.
0153
0154 However the only types that can be autodetected are:
0155
0156 * 2-axis, 4-button joystick
0157 * 3-axis, 4-button joystick
0158 * 4-axis, 4-button joystick
0159 * Saitek Cyborg 'digital' joysticks
0160
0161 For other joystick types (more/less axes, hats, and buttons) support
0162 you'll need to specify the types either on the kernel command line or on the
0163 module command line, when inserting analog into the kernel. The
0164 parameters are::
0165
0166 analog.map=<type1>,<type2>,<type3>,....
0167
0168 'type' is type of the joystick from the table below, defining joysticks
0169 present on gameports in the system, starting with gameport0, second 'type'
0170 entry defining joystick on gameport1 and so on.
0171
0172 ========= =====================================================
0173 Type Meaning
0174 ========= =====================================================
0175 none No analog joystick on that port
0176 auto Autodetect joystick
0177 2btn 2-button n-axis joystick
0178 y-joy Two 2-button 2-axis joysticks on an Y-cable
0179 y-pad Two 2-button 2-axis gamepads on an Y-cable
0180 fcs Thrustmaster FCS compatible joystick
0181 chf Joystick with a CH Flightstick compatible hat
0182 fullchf CH Flightstick compatible with two hats and 6 buttons
0183 gamepad 4/6-button n-axis gamepad
0184 gamepad8 8-button 2-axis gamepad
0185 ========= =====================================================
0186
0187 In case your joystick doesn't fit in any of the above categories, you can
0188 specify the type as a number by combining the bits in the table below. This
0189 is not recommended unless you really know what are you doing. It's not
0190 dangerous, but not simple either.
0191
0192 ==== =========================
0193 Bit Meaning
0194 ==== =========================
0195 0 Axis X1
0196 1 Axis Y1
0197 2 Axis X2
0198 3 Axis Y2
0199 4 Button A
0200 5 Button B
0201 6 Button C
0202 7 Button D
0203 8 CHF Buttons X and Y
0204 9 CHF Hat 1
0205 10 CHF Hat 2
0206 11 FCS Hat
0207 12 Pad Button X
0208 13 Pad Button Y
0209 14 Pad Button U
0210 15 Pad Button V
0211 16 Saitek F1-F4 Buttons
0212 17 Saitek Digital Mode
0213 19 GamePad
0214 20 Joy2 Axis X1
0215 21 Joy2 Axis Y1
0216 22 Joy2 Axis X2
0217 23 Joy2 Axis Y2
0218 24 Joy2 Button A
0219 25 Joy2 Button B
0220 26 Joy2 Button C
0221 27 Joy2 Button D
0222 31 Joy2 GamePad
0223 ==== =========================
0224
0225 Microsoft SideWinder joysticks
0226 ------------------------------
0227
0228 Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
0229 module. All currently supported joysticks:
0230
0231 * Microsoft SideWinder 3D Pro
0232 * Microsoft SideWinder Force Feedback Pro
0233 * Microsoft SideWinder Force Feedback Wheel
0234 * Microsoft SideWinder FreeStyle Pro
0235 * Microsoft SideWinder GamePad (up to four, chained)
0236 * Microsoft SideWinder Precision Pro
0237 * Microsoft SideWinder Precision Pro USB
0238
0239 are autodetected, and thus no module parameters are needed.
0240
0241 There is one caveat with the 3D Pro. There are 9 buttons reported,
0242 although the joystick has only 8. The 9th button is the mode switch on the
0243 rear side of the joystick. However, moving it, you'll reset the joystick,
0244 and make it unresponsive for about a one third of a second. Furthermore, the
0245 joystick will also re-center itself, taking the position it was in during
0246 this time as a new center position. Use it if you want, but think first.
0247
0248 The SideWinder Standard is not a digital joystick, and thus is supported
0249 by the analog driver described above.
0250
0251 Logitech ADI devices
0252 --------------------
0253
0254 Logitech ADI protocol is supported by the adi.c module. It should support
0255 any Logitech device using this protocol. This includes, but is not limited
0256 to:
0257
0258 * Logitech CyberMan 2
0259 * Logitech ThunderPad Digital
0260 * Logitech WingMan Extreme Digital
0261 * Logitech WingMan Formula
0262 * Logitech WingMan Interceptor
0263 * Logitech WingMan GamePad
0264 * Logitech WingMan GamePad USB
0265 * Logitech WingMan GamePad Extreme
0266 * Logitech WingMan Extreme Digital 3D
0267
0268 ADI devices are autodetected, and the driver supports up to two (any
0269 combination of) devices on a single gameport, using a Y-cable or chained
0270 together.
0271
0272 Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
0273 Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
0274 handled by the analog driver described above. Logitech WingMan Warrior and
0275 Logitech Magellan are supported by serial drivers described below. Logitech
0276 WingMan Force and Logitech WingMan Formula Force are supported by the
0277 I-Force driver described below. Logitech CyberMan is not supported yet.
0278
0279 Gravis GrIP
0280 -----------
0281
0282 Gravis GrIP protocol is supported by the grip.c module. It currently
0283 supports:
0284
0285 * Gravis GamePad Pro
0286 * Gravis BlackHawk Digital
0287 * Gravis Xterminator
0288 * Gravis Xterminator DualControl
0289
0290 All these devices are autodetected, and you can even use any combination
0291 of up to two of these pads either chained together or using a Y-cable on a
0292 single gameport.
0293
0294 GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
0295 supported by the stinger driver. Other Gravis joysticks are supported by the
0296 analog driver.
0297
0298 FPGaming A3D and MadCatz A3D
0299 ----------------------------
0300
0301 The Assassin 3D protocol created by FPGaming, is used both by FPGaming
0302 themselves and is licensed to MadCatz. A3D devices are supported by the
0303 a3d.c module. It currently supports:
0304
0305 * FPGaming Assassin 3D
0306 * MadCatz Panther
0307 * MadCatz Panther XL
0308
0309 All these devices are autodetected. Because the Assassin 3D and the Panther
0310 allow connecting analog joysticks to them, you'll need to load the analog
0311 driver as well to handle the attached joysticks.
0312
0313 The trackball should work with USB mousedev module as a normal mouse. See
0314 the USB documentation for how to setup a USB mouse.
0315
0316 ThrustMaster DirectConnect (BSP)
0317 --------------------------------
0318
0319 The TM DirectConnect (BSP) protocol is supported by the tmdc.c
0320 module. This includes, but is not limited to:
0321
0322 * ThrustMaster Millennium 3D Interceptor
0323 * ThrustMaster 3D Rage Pad
0324 * ThrustMaster Fusion Digital Game Pad
0325
0326 Devices not directly supported, but hopefully working are:
0327
0328 * ThrustMaster FragMaster
0329 * ThrustMaster Attack Throttle
0330
0331 If you have one of these, contact me.
0332
0333 TMDC devices are autodetected, and thus no parameters to the module
0334 are needed. Up to two TMDC devices can be connected to one gameport, using
0335 a Y-cable.
0336
0337 Creative Labs Blaster
0338 ---------------------
0339
0340 The Blaster protocol is supported by the cobra.c module. It supports only
0341 the:
0342
0343 * Creative Blaster GamePad Cobra
0344
0345 Up to two of these can be used on a single gameport, using a Y-cable.
0346
0347 Genius Digital joysticks
0348 ------------------------
0349
0350 The Genius digitally communicating joysticks are supported by the gf2k.c
0351 module. This includes:
0352
0353 * Genius Flight2000 F-23 joystick
0354 * Genius Flight2000 F-31 joystick
0355 * Genius G-09D gamepad
0356
0357 Other Genius digital joysticks are not supported yet, but support can be
0358 added fairly easily.
0359
0360 InterAct Digital joysticks
0361 --------------------------
0362
0363 The InterAct digitally communicating joysticks are supported by the
0364 interact.c module. This includes:
0365
0366 * InterAct HammerHead/FX gamepad
0367 * InterAct ProPad8 gamepad
0368
0369 Other InterAct digital joysticks are not supported yet, but support can be
0370 added fairly easily.
0371
0372 PDPI Lightning 4 gamecards
0373 --------------------------
0374
0375 PDPI Lightning 4 gamecards are supported by the lightning.c module.
0376 Once the module is loaded, the analog driver can be used to handle the
0377 joysticks. Digitally communicating joystick will work only on port 0, while
0378 using Y-cables, you can connect up to 8 analog joysticks to a single L4
0379 card, 16 in case you have two in your system.
0380
0381 Trident 4DWave / Aureal Vortex
0382 ------------------------------
0383
0384 Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipset
0385 provide an "Enhanced Game Port" mode where the soundcard handles polling the
0386 joystick. This mode is supported by the pcigame.c module. Once loaded the
0387 analog driver can use the enhanced features of these gameports..
0388
0389 Crystal SoundFusion
0390 -------------------
0391
0392 Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
0393 Port", much like the 4DWave or Vortex above. This, and also the normal mode
0394 for the port of the SoundFusion is supported by the cs461x.c module.
0395
0396 SoundBlaster Live!
0397 ------------------
0398
0399 The Live! has a special PCI gameport, which, although it doesn't provide
0400 any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
0401 its ISA counterparts. It also requires special support, hence the
0402 emu10k1-gp.c module for it instead of the normal ns558.c one.
0403
0404 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
0405 ------------------------------------------------------------------------
0406
0407 These PCI soundcards have specific gameports. They are handled by the
0408 sound drivers themselves. Make sure you select gameport support in the
0409 joystick menu and sound card support in the sound menu for your appropriate
0410 card.
0411
0412 Amiga
0413 -----
0414
0415 Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
0416 driver. Since they can't be autodetected, the driver has a command line:
0417
0418 amijoy.map=<a>,<b>
0419
0420 a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
0421 the Amiga.
0422
0423 ====== ===========================
0424 Value Joystick type
0425 ====== ===========================
0426 0 None
0427 1 1-button digital joystick
0428 ====== ===========================
0429
0430 No more joystick types are supported now, but that should change in the
0431 future if I get an Amiga in the reach of my fingers.
0432
0433 Game console and 8-bit pads and joysticks
0434 -----------------------------------------
0435
0436 These pads and joysticks are not designed for PCs and other computers
0437 Linux runs on, and usually require a special connector for attaching
0438 them through a parallel port.
0439
0440 See :ref:`joystick-parport` for more info.
0441
0442 SpaceTec/LabTec devices
0443 -----------------------
0444
0445 SpaceTec serial devices communicate using the SpaceWare protocol. It is
0446 supported by the spaceorb.c and spaceball.c drivers. The devices currently
0447 supported by spaceorb.c are:
0448
0449 * SpaceTec SpaceBall Avenger
0450 * SpaceTec SpaceOrb 360
0451
0452 Devices currently supported by spaceball.c are:
0453
0454 * SpaceTec SpaceBall 4000 FLX
0455
0456 In addition to having the spaceorb/spaceball and serport modules in the
0457 kernel, you also need to attach a serial port to it. To do that, run the
0458 inputattach program::
0459
0460 inputattach --spaceorb /dev/tts/x &
0461
0462 or::
0463
0464 inputattach --spaceball /dev/tts/x &
0465
0466 where /dev/tts/x is the serial port which the device is connected to. After
0467 doing this, the device will be reported and will start working.
0468
0469 There is one caveat with the SpaceOrb. The button #6, the one on the bottom
0470 side of the orb, although reported as an ordinary button, causes internal
0471 recentering of the spaceorb, moving the zero point to the position in which
0472 the ball is at the moment of pressing the button. So, think first before
0473 you bind it to some other function.
0474
0475 SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
0476
0477 Logitech SWIFT devices
0478 ----------------------
0479
0480 The SWIFT serial protocol is supported by the warrior.c module. It
0481 currently supports only the:
0482
0483 * Logitech WingMan Warrior
0484
0485 but in the future, Logitech CyberMan (the original one, not CM2) could be
0486 supported as well. To use the module, you need to run inputattach after you
0487 insert/compile the module into your kernel::
0488
0489 inputattach --warrior /dev/tts/x &
0490
0491 /dev/tts/x is the serial port your Warrior is attached to.
0492
0493 Magellan / Space Mouse
0494 ----------------------
0495
0496 The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
0497 Systems), for many other companies (Logitech, HP, ...) is supported by the
0498 joy-magellan module. It currently supports only the:
0499
0500 * Magellan 3D
0501 * Space Mouse
0502
0503 models; the additional buttons on the 'Plus' versions are not supported yet.
0504
0505 To use it, you need to attach the serial port to the driver using the::
0506
0507 inputattach --magellan /dev/tts/x &
0508
0509 command. After that the Magellan will be detected, initialized, will beep,
0510 and the /dev/input/jsX device should become usable.
0511
0512 I-Force devices
0513 ---------------
0514
0515 All I-Force devices are supported by the iforce module. This includes:
0516
0517 * AVB Mag Turbo Force
0518 * AVB Top Shot Pegasus
0519 * AVB Top Shot Force Feedback Racing Wheel
0520 * Boeder Force Feedback Wheel
0521 * Logitech WingMan Force
0522 * Logitech WingMan Force Wheel
0523 * Guillemot Race Leader Force Feedback
0524 * Guillemot Force Feedback Racing Wheel
0525 * Thrustmaster Motor Sport GT
0526
0527 To use it, you need to attach the serial port to the driver using the::
0528
0529 inputattach --iforce /dev/tts/x &
0530
0531 command. After that the I-Force device will be detected, and the
0532 /dev/input/jsX device should become usable.
0533
0534 In case you're using the device via the USB port, the inputattach command
0535 isn't needed.
0536
0537 The I-Force driver now supports force feedback via the event interface.
0538
0539 Please note that Logitech WingMan 3D devices are _not_ supported by this
0540 module, rather by hid. Force feedback is not supported for those devices.
0541 Logitech gamepads are also hid devices.
0542
0543 Gravis Stinger gamepad
0544 ----------------------
0545
0546 The Gravis Stinger serial port gamepad, designed for use with laptop
0547 computers, is supported by the stinger.c module. To use it, attach the
0548 serial port to the driver using::
0549
0550 inputattach --stinger /dev/tty/x &
0551
0552 where x is the number of the serial port.
0553
0554 Troubleshooting
0555 ===============
0556
0557 There is quite a high probability that you run into some problems. For
0558 testing whether the driver works, if in doubt, use the jstest utility in
0559 some of its modes. The most useful modes are "normal" - for the 1.x
0560 interface, and "old" for the "0.x" interface. You run it by typing::
0561
0562 jstest --normal /dev/input/js0
0563 jstest --old /dev/input/js0
0564
0565 Additionally you can do a test with the evtest utility::
0566
0567 evtest /dev/input/event0
0568
0569 Oh, and read the FAQ! :)
0570
0571 FAQ
0572 ===
0573
0574 :Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
0575 cause?
0576 :A: The device files don't exist. Create them (see section 2.2).
0577
0578 :Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
0579 or pad that uses a 9-pin D-type Cannon connector to the serial port of my
0580 PC?
0581 :A: Yes, it is possible, but it'll burn your serial port or the pad. It
0582 won't work, of course.
0583
0584 :Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
0585 :A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
0586 for them.
