About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / input / joystick.txt


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog