Input: docs - update joystick documentation a bit

The Linux Input Documentation

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

Core API

========

Contents:

.. toctree::

   :maxdepth: 2

   input

   input-programming

   event-codes

   joystick

   joystick-api

   joydev/index

   multi-touch-protocol

   gamepad

   gameport-programming

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

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

Joystick API Documentation

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

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

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 check the initial state of the

(JS_EVENT_INIT) that you can read to obtain the initial state of the

joystick.

By default, the device is opened in blocking mode::

.. note::

 As for version 1.2.8, the queue is circular and able to hold 64

 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.

.. include:: <isonum.txt>

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

Linux Joystick driver v2.0.0

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

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

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 <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,

Simunkova 1594, 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.

Intro

=====

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.

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://atrey.karlin.mff.cuni.cz/~vojtech/input/

There is also a mailing list for the driver at:

The mailing list for the project is:

	listproc@atrey.karlin.mff.cuni.cz

	linux-input@vger.kernel.org

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

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.

inpututils

----------

Utilities

---------

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.

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,

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

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*

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

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

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

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

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,

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.

.. _joystick-parport:

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

Linux Joystick parport drivers v2.0

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

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

Parallel port Joystick Drivers

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

:Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>

:Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de>

happen include burning your parallel port, and/or the sticks and joystick

and maybe even more. Like when a lightning kills you it is not our problem.

Intro

=====

Introduction

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

The joystick parport drivers are used for joysticks and gamepads not

originally designed for PCs and other computers Linux runs on. Because of

for two more interfaces.

PC parallel port pinout

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

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

::