diff options
Diffstat (limited to 'Documentation/input/joydev')
| -rw-r--r-- | Documentation/input/joydev/index.rst | 18 | ||||
| -rw-r--r-- | Documentation/input/joydev/joystick-api.rst | 348 | ||||
| -rw-r--r-- | Documentation/input/joydev/joystick.rst | 585 |
3 files changed, 951 insertions, 0 deletions
diff --git a/Documentation/input/joydev/index.rst b/Documentation/input/joydev/index.rst new file mode 100644 index 000000000000..8d9666c7561c --- /dev/null +++ b/Documentation/input/joydev/index.rst @@ -0,0 +1,18 @@ +.. include:: <isonum.txt> + +====================== +Linux Joystick support +====================== + +:Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE + +.. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 3 + :numbered: + + joystick + joystick-api diff --git a/Documentation/input/joydev/joystick-api.rst b/Documentation/input/joydev/joystick-api.rst new file mode 100644 index 000000000000..95803e2e8cd0 --- /dev/null +++ b/Documentation/input/joydev/joystick-api.rst @@ -0,0 +1,348 @@ +.. _joystick-api: + +===================== +Programming Interface +===================== + +:Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 1998 + +Introduction +============ + +.. important:: + This document describes legacy ``js`` interface. Newer clients are + encouraged to switch to the generic event (``evdev``) 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, +joystick.h and jstest.c included in the joystick package for more +information. The joystick device can be used in either blocking or +nonblocking mode, and supports select() calls. + +For backward compatibility the old (v0.x) interface is still included. +Any call to the joystick driver using the old interface will return values +that are compatible to the old interface. This interface is still limited +to 2 axes, and applications using it usually decode only 2 buttons, although +the driver provides up to 32. + +Initialization +============== + +Open the joystick device following the usual semantics (that is, with open). +Since the driver now reports events instead of polling for changes, +immediately after the open it will issue a series of synthetic events +(JS_EVENT_INIT) that you can read to obtain the initial state of the +joystick. + +By default, the device is opened in blocking mode:: + + int fd = open ("/dev/input/js0", O_RDONLY); + + +Event Reading +============= + +:: + + struct js_event e; + read (fd, &e, sizeof(e)); + +where js_event is defined as:: + + struct js_event { + __u32 time; /* event timestamp in milliseconds */ + __s16 value; /* value */ + __u8 type; /* event type */ + __u8 number; /* axis/button number */ + }; + +If the read is successful, it will return sizeof(e), unless you wanted to read +more than one event per read as described in section 3.1. + + +js_event.type +------------- + +The possible values of ``type`` are:: + + #define JS_EVENT_BUTTON 0x01 /* button pressed/released */ + #define JS_EVENT_AXIS 0x02 /* joystick moved */ + #define JS_EVENT_INIT 0x80 /* initial state of device */ + +As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed +events on open. That is, if it's issuing a INIT BUTTON event, the +current type value will be:: + + int type = JS_EVENT_BUTTON | JS_EVENT_INIT; /* 0x81 */ + +If you choose not to differentiate between synthetic or real events +you can turn off the JS_EVENT_INIT bits:: + + type &= ~JS_EVENT_INIT; /* 0x01 */ + + +js_event.number +--------------- + +The values of ``number`` correspond to the axis or button that +generated the event. Note that they carry separate numeration (that +is, you have both an axis 0 and a button 0). Generally, + + =============== ======= + Axis number + =============== ======= + 1st Axis X 0 + 1st Axis Y 1 + 2nd Axis X 2 + 2nd Axis Y 3 + ...and so on + =============== ======= + +Hats vary from one joystick type to another. Some can be moved in 8 +directions, some only in 4, The driver, however, always reports a hat as two +independent axis, even if the hardware doesn't allow independent movement. + + +js_event.value +-------------- + +For an axis, ``value`` is a signed integer between -32767 and +32767 +representing the position of the joystick along that axis. If you +don't read a 0 when the joystick is ``dead``, or if it doesn't span the +full range, you should recalibrate it (with, for example, jscal). + +For a button, ``value`` for a press button event is 1 and for a release +button event is 0. + +Though this:: + + if (js_event.type == JS_EVENT_BUTTON) { + buttons_state ^= (1 << js_event.number); + } + +may work well if you handle JS_EVENT_INIT events separately, + +:: + + if ((js_event.type & ~JS_EVENT_INIT) == JS_EVENT_BUTTON) { + if (js_event.value) + buttons_state |= (1 << js_event.number); + else + buttons_state &= ~(1 << js_event.number); + } + +is much safer since it can't lose sync with the driver. As you would +have to write a separate handler for JS_EVENT_INIT events in the first +snippet, this ends up being shorter. + + +js_event.time +------------- + +The time an event was generated is stored in ``js_event.time``. It's a time +in milliseconds since ... well, since sometime in the past. This eases the +task of detecting double clicks, figuring out if movement of axis and button +presses happened at the same time, and similar. + + +Reading +======= + +If you open the device in blocking mode, a read will block (that is, +wait) forever until an event is generated and effectively read. There +are two alternatives if you can't afford to wait forever (which is, +admittedly, a long time;) + + a) use select to wait until there's data to be read on fd, or + until it timeouts. There's a good example on the select(2) + man page. + + b) open the device in non-blocking mode (O_NONBLOCK) + + +O_NONBLOCK +---------- + +If read returns -1 when reading in O_NONBLOCK mode, this isn't +necessarily a "real" error (check errno(3)); it can just mean there +are no events pending to be read on the driver queue. You should read +all events on the queue (that is, until you get a -1). + +For example, + +:: + + while (1) { + while (read (fd, &e, sizeof(e)) > 0) { + process_event (e); + } + /* EAGAIN is returned when the queue is empty */ + if (errno != EAGAIN) { + /* error */ + } + /* do something interesting with processed events */ + } + +One reason for emptying the queue is that if it gets full you'll start +missing events since the queue is finite, and older events will get +overwritten. + +The other reason is that you want to know all what happened, and not +delay the processing till later. + +Why can get the queue full? Because you don't empty the queue as +mentioned, or because too much time elapses from one read to another +and too many events to store in the queue get generated. Note that +high system load may contribute to space those reads even more. + +If time between reads is enough to fill the queue and lose an event, +the driver will switch to startup mode and next time you read it, +synthetic events (JS_EVENT_INIT) will be generated to inform you of +the actual state of the joystick. + + +.. note:: + + As of version 1.2.8, the queue is circular and able to hold 64 + events. You can increment this size bumping up JS_BUFF_SIZE in + joystick.h and recompiling the driver. + + +In the above code, you might as well want to read more than one event +at a time using the typical read(2) functionality. For that, you would +replace the read above with something like:: + + struct js_event mybuffer[0xff]; + int i = read (fd, mybuffer, sizeof(mybuffer)); + +In this case, read would return -1 if the queue was empty, or some +other value in which the number of events read would be i / +sizeof(js_event) Again, if the buffer was full, it's a good idea to +process the events and keep reading it until you empty the driver queue. + + +IOCTLs +====== + +The joystick driver defines the following ioctl(2) operations:: + + /* function 3rd arg */ + #define JSIOCGAXES /* get number of axes char */ + #define JSIOCGBUTTONS /* get number of buttons char */ + #define JSIOCGVERSION /* get driver version int */ + #define JSIOCGNAME(len) /* get identifier string char */ + #define JSIOCSCORR /* set correction values &js_corr */ + #define JSIOCGCORR /* get correction values &js_corr */ + +For example, to read the number of axes:: + + char number_of_axes; + ioctl (fd, JSIOCGAXES, &number_of_axes); + + +JSIOGCVERSION +------------- + +JSIOGCVERSION is a good way to check in run-time whether the running +driver is 1.0+ and supports the event interface. If it is not, the +IOCTL will fail. For a compile-time decision, you can test the +JS_VERSION symbol:: + + #ifdef JS_VERSION + #if JS_VERSION > 0xsomething + + +JSIOCGNAME +---------- + +JSIOCGNAME(len) allows you to get the name string of the joystick - the same +as is being printed at boot time. The 'len' argument is the length of the +buffer provided by the application asking for the name. It is used to avoid +possible overrun should the name be too long:: + + char name[128]; + if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0) + strncpy(name, "Unknown", sizeof(name)); + printf("Name: %s\n", name); + + +JSIOC[SG]CORR +------------- + +For usage on JSIOC[SG]CORR I suggest you to look into jscal.c They are +not needed in a normal program, only in joystick calibration software +such as jscal or kcmjoy. These IOCTLs and data types aren't considered +to be in the stable part of the API, and therefore may change without +warning in following releases of the driver. + +Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold +information for all axis. That is, struct js_corr corr[MAX_AXIS]; + +struct js_corr is defined as:: + + struct js_corr { + __s32 coef[8]; + __u16 prec; + __u16 type; + }; + +and ``type``:: + + #define JS_CORR_NONE 0x00 /* returns raw values */ + #define JS_CORR_BROKEN 0x01 /* broken line */ + + +Backward compatibility +====================== + +The 0.x joystick driver API is quite limited and its usage is deprecated. +The driver offers backward compatibility, though. Here's a quick summary:: + + struct JS_DATA_TYPE js; + while (1) { + if (read (fd, &js, JS_RETURN) != JS_RETURN) { + /* error */ + } + usleep (1000); + } + +As you can figure out from the example, the read returns immediately, +with the actual state of the joystick:: + + struct JS_DATA_TYPE { + int buttons; /* immediate button state */ + int x; /* immediate x axis value */ + int y; /* immediate y axis value */ + }; + +and JS_RETURN is defined as:: + + #define JS_RETURN sizeof(struct JS_DATA_TYPE) + +To test the state of the buttons, + +:: + + first_button_state = js.buttons & 1; + second_button_state = js.buttons & 2; + +The axis values do not have a defined range in the original 0.x driver, +except for that the values are non-negative. The 1.2.8+ drivers use a +fixed range for reporting the values, 1 being the minimum, 128 the +center, and 255 maximum value. + +The v0.8.0.2 driver also had an interface for 'digital joysticks', (now +called Multisystem joysticks in this driver), under /dev/djsX. This driver +doesn't try to be compatible with that interface. + + +Final Notes +=========== + +:: + + ____/| Comments, additions, and specially corrections are welcome. + \ o.O| Documentation valid for at least version 1.2.8 of the joystick + =(_)= driver and as usual, the ultimate source for documentation is + U to "Use The Source Luke" or, at your convenience, Vojtech ;) diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst new file mode 100644 index 000000000000..9746fd76cc58 --- /dev/null +++ b/Documentation/input/joydev/joystick.rst @@ -0,0 +1,585 @@ +.. include:: <isonum.txt> + +.. _joystick-doc: + +Introduction +============ + +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. + +The mailing list for the project is: + + linux-input@vger.kernel.org + +send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it. + +Usage +===== + +For basic usage you just choose the right options in kernel config and +you should be set. + +Utilities +--------- + +For testing and other purposes (for example serial devices), there is a set +of utilities, such as ``jstest``, ``jscal``, and ``evtest``, +usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on. + +``inputattach`` utility is required if your joystick is connected to a +serial port. + +Device nodes +------------ + +For applications to be able to use the joysticks, device nodes should be +created in /dev. Normally it is done automatically by the system, but +it can also be done by hand:: + + 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 + +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 map=gamepad,none,2btn + +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/input/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. + +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/input/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/input/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. + +HW specific driver information +============================== + +In this section each of the separate hardware specific drivers is described. + +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 into the kernel. The +parameters are:: + + analog.map=<type1>,<type2>,<type3>,.... + +'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 + ==== ========================= + +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. + +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 +I-Force driver described below. Logitech CyberMan is not supported yet. + +Gravis GrIP +----------- + +Gravis GrIP protocol is supported by the grip.c module. It currently +supports: + +* Gravis GamePad Pro +* Gravis BlackHawk Digital +* Gravis Xterminator +* Gravis Xterminator DualControl + +All these devices are autodetected, and you can even use any combination +of up to two of these pads either chained together or using an Y-cable on a +single gameport. + +GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is +supported by the stinger driver. Other Gravis joysticks are supported by the +analog driver. + +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: + +* FPGaming Assassin 3D +* MadCatz Panther +* MadCatz Panther XL + +All these devices are autodetected. Because the Assassin 3D and the Panther +allow connecting analog joysticks to them, you'll need to load the analog +driver as well to handle the attached joysticks. + +The trackball should work with USB mousedev module as a normal mouse. See +the USB documentation for how to setup an USB mouse. + +ThrustMaster DirectConnect (BSP) +-------------------------------- + +The TM DirectConnect (BSP) protocol is supported by the tmdc.c +module. This includes, but is not limited to: + +* ThrustMaster Millennium 3D Interceptor +* ThrustMaster 3D Rage Pad +* ThrustMaster Fusion Digital Game Pad + +Devices not directly supported, but hopefully working are: + +* ThrustMaster FragMaster +* ThrustMaster Attack Throttle + +If you have one of these, contact me. + +TMDC devices are autodetected, and thus no parameters to the module +are needed. Up to two TMDC devices can be connected to one gameport, using +an Y-cable. + +Creative Labs Blaster +--------------------- + +The Blaster protocol is supported by the cobra.c module. It supports only +the: + +* Creative Blaster GamePad Cobra + +Up to two of these can be used on a single gameport, using an Y-cable. + +Genius Digital joysticks +------------------------ + +The Genius digitally communicating joysticks are supported by the gf2k.c +module. This includes: + +* Genius Flight2000 F-23 joystick +* Genius Flight2000 F-31 joystick +* Genius G-09D gamepad + +Other Genius digital joysticks are not supported yet, but support can be +added fairly easily. + +InterAct Digital joysticks +-------------------------- + +The InterAct digitally communicating joysticks are supported by the +interact.c module. This includes: + +* InterAct HammerHead/FX gamepad +* InterAct ProPad8 gamepad + +Other InterAct digital joysticks are not supported yet, but support can be +added fairly easily. + +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. + +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.. + +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. + +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. + +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. + +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: + + 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 + ====== =========================== + +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. + +Game console and 8-bit pads and joysticks +----------------------------------------- + +These pads and joysticks are not designed for PCs and other computers +Linux runs on, and usually require a special connector for attaching +them through a parallel port. + +See :ref:`joystick-parport` for more info. + +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: + +* SpaceTec SpaceBall Avenger +* SpaceTec SpaceOrb 360 + +Devices currently supported by spaceball.c are: + +* SpaceTec SpaceBall 4000 FLX + +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 --spaceorb /dev/tts/x & + +or:: + + inputattach --spaceball /dev/tts/x & + +where /dev/tts/x is the serial port which the device is connected to. After +doing this, the device will be reported and will start working. + +There is one caveat with the SpaceOrb. The button #6, the on the bottom +side of the orb, although reported as an ordinary button, causes internal +recentering of the spaceorb, moving the zero point to the position in which +the ball is at the moment of pressing the button. So, think first before +you bind it to some other function. + +SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet. + +Logitech SWIFT devices +---------------------- + +The SWIFT serial protocol is supported by the warrior.c module. It +currently supports only the: + +* Logitech WingMan Warrior + +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:: + + inputattach --warrior /dev/tts/x & + +/dev/tts/x is the serial port your Warrior is attached to. + +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: + +* Magellan 3D +* Space Mouse + +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:: + + 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. + +I-Force devices +--------------- + +All I-Force devices are supported by the iforce module. This includes: + +* AVB Mag Turbo Force +* AVB Top Shot Pegasus +* AVB Top Shot Force Feedback Racing Wheel +* Logitech WingMan Force +* Logitech WingMan Force Wheel +* Guillemot Race Leader Force Feedback +* Guillemot Force Feedback Racing Wheel +* Thrustmaster Motor Sport GT + +To use it, you need to attach the serial port to the driver using the:: + + inputattach --iforce /dev/tts/x & + +command. After that the I-Force device will be detected, and the +/dev/input/jsX device should become usable. + +In case you're using the device via the USB port, the inputattach command +isn't needed. + +The I-Force driver now supports force feedback via the event interface. + +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. + +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:: + + inputattach --stinger /dev/tty/x & + +where x is the number of the serial port. + +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:: + + jstest --normal /dev/input/js0 + jstest --old /dev/input/js0 + +Additionally you can do a test with the evtest utility:: + + evtest /dev/input/event0 + +Oh, and read the FAQ! :) + +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). + +: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 + 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 + for them. |