Input: joystick - convert documentation into ReST format

.. include:: <isonum.txt>

============================

Linux Joystick driver v2.0.0

	       (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz>

			     Sponsored by SuSE

----------------------------------------------------------------------------

============================

:Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE

Disclaimer

==========

0. Disclaimer

~~~~~~~~~~~~~

This program is free software; you can redistribute it and/or modify it

under the terms of the GNU General Public License as published by the Free

Software Foundation; either version 2 of the License, or (at your option)

For your convenience, the GNU General Public License version 2 is included

in the package: See the file COPYING.

1. Intro

~~~~~~~~

Intro

=====

The joystick driver for Linux provides support for a variety of joysticks

and similar devices. It is based on a larger project aiming to support all

input devices in Linux.

send "subscribe linux-joystick Your Name" to subscribe to it.

2. Usage

~~~~~~~~

Usage

=====

For basic usage you just choose the right options in kernel config and

you should be set.

2.1 inpututils

~~~~~~~~~~~~~~

inpututils

----------

For testing and other purposes (for example serial devices), a set of

utilities is available at the abovementioned website. I suggest you download

and install it before going on.

2.2 Device nodes

~~~~~~~~~~~~~~~~

Device nodes

------------

For applications to be able to use the joysticks,

you'll have to manually create these nodes in /dev:

you'll have to manually create these nodes in /dev::

    cd /dev

    rm js*

    ln -s input/js2 js2

    ln -s input/js3 js3

For testing with inpututils it's also convenient to create these:

For testing with inpututils it's also convenient to create these::

    mknod input/event0 c 13 64

    mknod input/event1 c 13 65

    mknod input/event2 c 13 66

    mknod input/event3 c 13 67

2.4 Modules needed 

~~~~~~~~~~~~~~~~~~

Modules needed

--------------

For all joystick drivers to function, you'll need the userland interface

module in kernel, either loaded or compiled in:

module in kernel, either loaded or compiled in::

	modprobe joydev

  For gameport joysticks, you'll have to load the gameport driver as well;

For gameport joysticks, you'll have to load the gameport driver as well::

	modprobe ns558

And for serial port joysticks, you'll need the serial input line

discipline module loaded and the inputattach utility started:

discipline module loaded and the inputattach utility started::

	modprobe serport

	inputattach -xxx /dev/tts/X &

In addition to that, you'll need the joystick driver module itself, most

usually you'll have an analog joystick:

usually you'll have an analog joystick::

	modprobe analog

For automatic module loading, something like this might work - tailor to

your needs:

your needs::

	alias tty-ldisc-2 serport

	alias char-major-13 input

	above input joydev ns558 analog

	options analog map=gamepad,none,2btn

2.5 Verifying that it works

~~~~~~~~~~~~~~~~~~~~~~~~~~~

Verifying that it works

-----------------------

For testing the joystick driver functionality, there is the jstest

program in the utilities package. You run it by typing:

program in the utilities package. You run it by typing::

	jstest /dev/input/js0

and if it still doesn't work, read the drivers section of this file, the

troubleshooting section, and the FAQ.

2.6. Calibration

~~~~~~~~~~~~~~~~

Calibration

-----------

For most joysticks you won't need any manual calibration, since the

joystick should be autocalibrated by the driver automagically. However, with

some analog joysticks, that either do not use linear resistors, or if you

want better precision, you can use the jscal program

want better precision, you can use the jscal program::

	jscal -c /dev/input/js0

After calibrating the joystick you can verify if you like the new

calibration using the jstest command, and if you do, you then can save the

correction coefficients into a file

correction coefficients into a file::

	jscal -p /dev/input/js0 > /etc/joystick.cal

  And add a line to your rc script executing that file

And add a line to your rc script executing that file::

	source /etc/joystick.cal

This way, after the next reboot your joystick will remain calibrated. You

can also add the jscal -p line to your shutdown script.

can also add the ``jscal -p`` line to your shutdown script.

3. HW specific driver information

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HW specific driver information

==============================

In this section each of the separate hardware specific drivers is described.

3.1 Analog joysticks

~~~~~~~~~~~~~~~~~~~~

Analog joysticks

----------------

The analog.c uses the standard analog inputs of the gameport, and thus

supports all standard joysticks and gamepads. It uses a very advanced

routine for this, allowing for data precision that can't be found on any

For other joystick types (more/less axes, hats, and buttons) support

you'll need to specify the types either on the kernel command line or on the

module command line, when inserting analog into the kernel. The

parameters are:

parameters are::

	analog.map=<type1>,<type2>,<type3>,....

present on gameports in the system, starting with gameport0, second 'type'

entry defining joystick on gameport1 and so on.

	Type     | Meaning

	-----------------------------------

	none     | No analog joystick on that port

	auto     | Autodetect joystick

	2btn     | 2-button n-axis joystick

	y-joy    | Two 2-button 2-axis joysticks on an Y-cable

	y-pad    | Two 2-button 2-axis gamepads on an Y-cable

	fcs      | Thrustmaster FCS compatible joystick

	chf      | Joystick with a CH Flightstick compatible hat

	fullchf  | CH Flightstick compatible with two hats and 6 buttons

	gamepad  | 4/6-button n-axis gamepad

	gamepad8 | 8-button 2-axis gamepad

	========= =====================================================

	Type      Meaning

	========= =====================================================

	none      No analog joystick on that port

	auto      Autodetect joystick

	2btn      2-button n-axis joystick

	y-joy     Two 2-button 2-axis joysticks on an Y-cable

	y-pad     Two 2-button 2-axis gamepads on an Y-cable

	fcs       Thrustmaster FCS compatible joystick

	chf       Joystick with a CH Flightstick compatible hat

	fullchf   CH Flightstick compatible with two hats and 6 buttons

	gamepad   4/6-button n-axis gamepad

	gamepad8  8-button 2-axis gamepad

	========= =====================================================

In case your joystick doesn't fit in any of the above categories, you can

specify the type as a number by combining the bits in the table below. This

is not recommended unless you really know what are you doing. It's not

dangerous, but not simple either.

	Bit | Meaning

	--------------------------

	 0  | Axis X1

	 1  | Axis Y1

	 2  | Axis X2

	 3  | Axis Y2

	 4  | Button A

	 5  | Button B

	 6  | Button C

	 7  | Button D

	 8  | CHF Buttons X and Y

	 9  | CHF Hat 1

	10  | CHF Hat 2

	11  | FCS Hat

	12  | Pad Button X

	13  | Pad Button Y

	14  | Pad Button U

	15  | Pad Button V

	16  | Saitek F1-F4 Buttons

	17  | Saitek Digital Mode

	19  | GamePad

	20  | Joy2 Axis X1

	21  | Joy2 Axis Y1

	22  | Joy2 Axis X2

	23  | Joy2 Axis Y2

	24  | Joy2 Button A

	25  | Joy2 Button B

	26  | Joy2 Button C

	27  | Joy2 Button D

	31  | Joy2 GamePad

3.2 Microsoft SideWinder joysticks

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	==== =========================

	Bit  Meaning

	==== =========================

	 0   Axis X1

	 1   Axis Y1

	 2   Axis X2

	 3   Axis Y2

	 4   Button A

	 5   Button B

	 6   Button C

	 7   Button D

	 8   CHF Buttons X and Y

	 9   CHF Hat 1

	10   CHF Hat 2

	11   FCS Hat

	12   Pad Button X

	13   Pad Button Y

	14   Pad Button U

	15   Pad Button V

	16   Saitek F1-F4 Buttons

	17   Saitek Digital Mode

	19   GamePad

	20   Joy2 Axis X1

	21   Joy2 Axis Y1

	22   Joy2 Axis X2

	23   Joy2 Axis Y2

	24   Joy2 Button A

	25   Joy2 Button B

	26   Joy2 Button C

	27   Joy2 Button D

	31   Joy2 GamePad

	==== =========================

Microsoft SideWinder joysticks

------------------------------

Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c

module. All currently supported joysticks:

The SideWinder Standard is not a digital joystick, and thus is supported

by the analog driver described above.

3.3 Logitech ADI devices

~~~~~~~~~~~~~~~~~~~~~~~~

Logitech ADI devices

--------------------

Logitech ADI protocol is supported by the adi.c module. It should support

any Logitech device using this protocol. This includes, but is not limited

to:

WingMan Force and Logitech WingMan Formula Force are supported by the

I-Force driver described below. Logitech CyberMan is not supported yet.

3.4 Gravis GrIP

~~~~~~~~~~~~~~~

Gravis GrIP

-----------

Gravis GrIP protocol is supported by the grip.c module. It currently

supports:

supported by the stinger driver. Other Gravis joysticks are supported by the

analog driver.

3.5 FPGaming A3D and MadCatz A3D

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

FPGaming A3D and MadCatz A3D

----------------------------

The Assassin 3D protocol created by FPGaming, is used both by FPGaming

themselves and is licensed to MadCatz. A3D devices are supported by the

a3d.c module. It currently supports:

The trackball should work with USB mousedev module as a normal mouse. See

the USB documentation for how to setup an USB mouse.

3.6 ThrustMaster DirectConnect (BSP)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ThrustMaster DirectConnect (BSP)

--------------------------------

The TM DirectConnect (BSP) protocol is supported by the tmdc.c

module. This includes, but is not limited to:

are needed. Up to two TMDC devices can be connected to one gameport, using

an Y-cable.

3.7 Creative Labs Blaster

~~~~~~~~~~~~~~~~~~~~~~~~~

Creative Labs Blaster

---------------------

The Blaster protocol is supported by the cobra.c module. It supports only

the:

Up to two of these can be used on a single gameport, using an Y-cable.

3.8 Genius Digital joysticks 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Genius Digital joysticks

------------------------

The Genius digitally communicating joysticks are supported by the gf2k.c

module. This includes:

Other Genius digital joysticks are not supported yet, but support can be

added fairly easily.

3.9 InterAct Digital joysticks

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

InterAct Digital joysticks

--------------------------

The InterAct digitally communicating joysticks are supported by the

interact.c module. This includes:

Other InterAct digital joysticks are not supported yet, but support can be

added fairly easily.

3.10 PDPI Lightning 4 gamecards

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PDPI Lightning 4 gamecards

--------------------------

PDPI Lightning 4 gamecards are supported by the lightning.c module.

Once the module is loaded, the analog driver can be used to handle the

joysticks. Digitally communicating joystick will work only on port 0, while

using Y-cables, you can connect up to 8 analog joysticks to a single L4

card, 16 in case you have two in your system.

3.11 Trident 4DWave / Aureal Vortex

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Trident 4DWave / Aureal Vortex

------------------------------

Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets

provide an "Enhanced Game Port" mode where the soundcard handles polling the

joystick.  This mode is supported by the pcigame.c module. Once loaded the

analog driver can use the enhanced features of these gameports..

3.13 Crystal SoundFusion

~~~~~~~~~~~~~~~~~~~~~~~~

Crystal SoundFusion

-------------------

Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game

Port", much like the 4DWave or Vortex above. This, and also the normal mode

for the port of the SoundFusion is supported by the cs461x.c module.

3.14 SoundBlaster Live!

~~~~~~~~~~~~~~~~~~~~~~~~

SoundBlaster Live!

------------------

The Live! has a special PCI gameport, which, although it doesn't provide

any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than

its ISA counterparts. It also requires special support, hence the

emu10k1-gp.c module for it instead of the normal ns558.c one.

3.15 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes

------------------------------------------------------------------------

These PCI soundcards have specific gameports. They are handled by the

sound drivers themselves. Make sure you select gameport support in the

joystick menu and sound card support in the sound menu for your appropriate

card.

3.16 Amiga

~~~~~~~~~~

Amiga

-----

Amiga joysticks, connected to an Amiga, are supported by the amijoy.c

driver. Since they can't be autodetected, the driver has a command line.

driver. Since they can't be autodetected, the driver has a command line:

	amijoy.map=<a>,<b>

a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of

the Amiga.

	Value | Joystick type

	---------------------

	  0   | None

	  1   | 1-button digital joystick

	====== ===========================

	Value  Joystick type

	====== ===========================

	  0    None

	  1    1-button digital joystick

	====== ===========================

No more joystick types are supported now, but that should change in the

future if I get an Amiga in the reach of my fingers.

3.17 Game console and 8-bit pads and joysticks

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See joystick-parport.txt for more info.

Game console and 8-bit pads and joysticks

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See :ref:`joystick-parport` for more info.

SpaceTec/LabTec devices

-----------------------

3.18 SpaceTec/LabTec devices

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SpaceTec serial devices communicate using the SpaceWare protocol. It is

supported by the spaceorb.c and spaceball.c drivers. The devices currently

supported by spaceorb.c are:

In addition to having the spaceorb/spaceball and serport modules in the

kernel, you also need to attach a serial port to it. to do that, run the

inputattach program:

inputattach program::

	inputattach --spaceorb /dev/tts/x &

or

or::

	inputattach --spaceball /dev/tts/x &

where /dev/tts/x is the serial port which the device is connected to. After

SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.

3.19 Logitech SWIFT devices

~~~~~~~~~~~~~~~~~~~~~~~~~~~

Logitech SWIFT devices

----------------------

The SWIFT serial protocol is supported by the warrior.c module. It

currently supports only the:

but in the future, Logitech CyberMan (the original one, not CM2) could be

supported as well. To use the module, you need to run inputattach after you

insert/compile the module into your kernel:

insert/compile the module into your kernel::

	inputattach --warrior /dev/tts/x &

/dev/tts/x is the serial port your Warrior is attached to.

3.20 Magellan / Space Mouse

~~~~~~~~~~~~~~~~~~~~~~~~~~~

Magellan / Space Mouse

----------------------

The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space

Systems), for many other companies (Logitech, HP, ...) is supported by the

joy-magellan module. It currently supports only the:

models, the additional buttons on the 'Plus' versions are not supported yet.

  To use it, you need to attach the serial port to the driver using the

To use it, you need to attach the serial port to the driver using the::

	inputattach --magellan /dev/tts/x &

command. After that the Magellan will be detected, initialized, will beep,

and the /dev/input/jsX device should become usable.

3.21 I-Force devices 

~~~~~~~~~~~~~~~~~~~~

I-Force devices

---------------

All I-Force devices are supported by the iforce module. This includes:

* AVB Mag Turbo Force

* Guillemot Force Feedback Racing Wheel

* Thrustmaster Motor Sport GT

  To use it, you need to attach the serial port to the driver using the

To use it, you need to attach the serial port to the driver using the::

	inputattach --iforce /dev/tts/x &

The I-Force driver now supports force feedback via the event interface.

  Please note that Logitech WingMan *3D devices are _not_ supported by this

Please note that Logitech WingMan 3D devices are _not_ supported by this

module, rather by hid. Force feedback is not supported for those devices.

Logitech gamepads are also hid devices.

3.22 Gravis Stinger gamepad 

~~~~~~~~~~~~~~~~~~~~~~~~~~~

Gravis Stinger gamepad

----------------------

The Gravis Stinger serial port gamepad, designed for use with laptop

computers, is supported by the stinger.c module. To use it, attach the

serial port to the driver using:

serial port to the driver using::

	inputattach --stinger /dev/tty/x &

where x is the number of the serial port.

4. Troubleshooting

~~~~~~~~~~~~~~~~~~

Troubleshooting

===============

There is quite a high probability that you run into some problems. For

testing whether the driver works, if in doubt, use the jstest utility in

some of its modes. The most useful modes are "normal" - for the 1.x

interface, and "old" for the "0.x" interface. You run it by typing:

interface, and "old" for the "0.x" interface. You run it by typing::

	jstest --normal /dev/input/js0

	jstest --old    /dev/input/js0

  Additionally you can do a test with the evtest utility:

Additionally you can do a test with the evtest utility::

	evtest /dev/input/event0

Oh, and read the FAQ! :)

5. FAQ

~~~~~~

Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the

FAQ

===

:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the

    cause?

A: The device files don't exist. Create them (see section 2.2).

:A: The device files don't exist. Create them (see section 2.2).

Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick

:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick

    or pad that uses a 9-pin D-type cannon connector to the serial port of my

    PC?

A: Yes, it is possible, but it'll burn your serial port or the pad. It

:A: Yes, it is possible, but it'll burn your serial port or the pad. It

    won't work, of course.

Q: My joystick doesn't work with Quake / Quake 2. What's the cause?

A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses

:Q: My joystick doesn't work with Quake / Quake 2. What's the cause?

:A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses

    for them.

6. Programming Interface

~~~~~~~~~~~~~~~~~~~~~~~~

Programming Interface

=====================

The 1.0 driver uses a new, event based approach to the joystick driver.

Instead of the user program polling for the joystick values, the joystick

driver now reports only any changes of its state. See joystick-api.txt,