joystick.txt

ARM 嵌入式 系统 设计与实例开发 实验教材 二源码

		       Linux Joystick driver v2.0.0
	       (c) 1996-2000 Vojtech Pavlik <[e-mail]>
			     Sponsored by SuSE
	   $Id: joystick.txt,v 1.6 2001/06/05 09:57:01 vojtech Exp $
----------------------------------------------------------------------------

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)
any later version.

  This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

  You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA

  Should you need to contact me, the author, you can do so either by e-mail
- mail your message to <[e-mail]>, or by paper mail: Vojtech Pavlik,
Ucitelska 1576, Prague 8, 182 00 Czech Republic

  For your convenience, the GNU General Public License version 2 is included
in the package: See the file COPYING.

1. 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.

  Should you encounter any problems while using the driver, or joysticks
this driver can't make complete use of, I'm very interested in hearing about
them. Bug reports and success stories are also welcome.

  The input project website is at:

	http://www.suse.cz/development/input/
	http://atrey.karlin.mff.cuni.cz/~vojtech/input/

  There is also a mailing list for the driver at:

	[e-mail]

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

2. Usage
~~~~~~~~
  For basic usage you just choose the right options in kernel config and
you should be set.

2.1 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
~~~~~~~~~~~~~~~~
For applications to be able to use the joysticks, in you don't use devfs,
you'll have to manually create these nodes in /dev:

cd /dev
rm js*
mkdir input
mknod input/js0 c 13 0
mknod input/js1 c 13 1
mknod input/js2 c 13 2
mknod input/js3 c 13 3
ln -s input/js0 js0
ln -s input/js1 js1
ln -s input/js2 js2
ln -s input/js3 js3

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 
~~~~~~~~~~~~~~~~~~
  For all joystick drivers to function, you'll need the userland interface
module in kernel, either loaded or compiled in:

	modprobe joydev

  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:

	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:

	modprobe analog
	
  For automatic module loading, something like this might work - tailor to
your needs:

	alias tty-ldisc-2 serport
	alias char-major-13 input
	above input joydev ns558 analog
	options analog js=gameport

2.5 Verifying that it works
~~~~~~~~~~~~~~~~~~~~~~~~~~~
  For testing the joystick driver functionality, there is the jstest
program in the utilities package. You run it by typing:

	jstest /dev/js0

  And it should show a line with the joystick values, which update as you
move the stick, and press its buttons. The axes should all be zero when the
joystick is in the center position. They should not jitter by themselves to
other close values, and they also should be steady in any other position of
the stick. They should have the full range from -32767 to 32767. If all this
is met, then it's all fine, and you can play the games. :)

  If it's not, then there might be a problem. Try to calibrate the joystick,
and if it still doesn't work, read the drivers section of this file, the
troubleshooting section, and the FAQ.

2.6. 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

	jscal -c /dev/js0

 included in the joystick package to set better correction coefficients than
what the driver would choose itself.

  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

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

  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.


3. HW specific driver information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this section each of the separate hardware specific drivers is described.

3.1 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
other system.

  It also supports extensions like additional hats and buttons compatible
with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
Cyborg 'digital' joysticks are also supported by this driver, because
they're basically souped up CHF sticks.

  However the only types that can be autodetected are:

* 2-axis, 4-button joystick
* 3-axis, 4-button joystick
* 4-axis, 4-button joystick
* Saitek Cyborg 'digital' joysticks

  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.o into the kernel. The
parameters are:

	js=type,type,type,....

  'type' is type of the joystick from the table below, defining joysticks
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

  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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
module. All currently supported joysticks:

* Microsoft SideWinder 3D Pro
* Microsoft SideWinder Force Feedback Pro
* Microsoft SideWinder Force Feedback Wheel
* Microsoft SideWinder FreeStyle Pro 
* Microsoft SideWinder GamePad (up to four, chained)
* Microsoft SideWinder Precision Pro 
* Microsoft SideWinder Precision Pro USB 

  are autodetected, and thus no module parameters are needed.

  There is one caveat with the 3D Pro. There are 9 buttons reported,
although the joystick has only 8. The 9th button is the mode switch on the
rear side of the joystick. However, moving it, you'll reset the joystick,
and make it unresponsive for about a one third of a second. Furthermore, the
joystick will also re-center itself, taking the position it was in during
this time as a new center position. Use it if you want, but think first.

  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 protocol is supported by the adi.c module. It should support
any Logitech device using this protocol. This includes, but is not limited
to:

* Logitech CyberMan 2
* Logitech ThunderPad Digital
* Logitech WingMan Extreme Digital
* Logitech WingMan Formula
* Logitech WingMan Interceptor
* Logitech WingMan GamePad
* Logitech WingMan GamePad USB
* Logitech WingMan GamePad Extreme
* Logitech WingMan Extreme Digital 3D

  ADI devices are autodetected, and the driver supports up to two (any
combination of) devices on a single gameport, using an Y-cable or chained
together.

  Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
handled by the analog driver described above. Logitech WingMan Warrior and
Logitech Magellan are supported by serial drivers described below.  Logitech
WingMan Force and Logitech WingMan Formula Force are supported by the