Driver name: LinuxJoydev_drv
Config element type:
linux_joydev
Interface type: game port or USB
Driver availability: Linux
Other information: requires Linux
joydev kernel module
The Linux joystick device driver makes use of the Linux
joydev kernel module to
communicate with joysticks and game pads connected via a PC game port
or USB. Because the
specifics of joysticks and game pads vary from vendor to vendor and
model to model, the Linux joydev device is highly
dynamic and generic. The Linux joystick device driver in
Gadgeteer takes advantage of this to avoid restricting what
types of joysticks or game pads may be used. This is reflected in the
configurable properties of the Linux joystick device driver config
element (type linux_joydev), shown below:
The name of the joystick port through which the
Gadgeteer driver can communicate with the device. The port
name will be one of /dev/js0,
/dev/js1,
/dev/input/js0, etc. The default value
for this property is /dev/js0.
With the Linux 2.4 kernel, it is unclear whether
multiple USB joysticks or game pads plugged in to a
single computer will always have the same port numbers
assigned to them each time the computer is rebooted. By
default, there appears to be no guarantee that a given
joystick or game pad will always be associated with the
same /dev/jsN device node. There may
be a way to tell the Linux kernel how to assign port
numbers to USB joysticks or game pads, but the process is
not known to us as of this writing. Further, it is not
known if the Linux 2.6 kernel exhibits the same
behavior.
A variable-valued property that identifies which axes (using zero-based integer identifiers) should be treated as digital buttons. The additional buttons will be appended to the basic set of digital inputs available from the device. This feature is useful with a directional pad (also known as a “hat”) to get additional button inputs.
The analog input from the axis (or axes) will still be available. An “axis button” provides a second interpretation of the received input data.
The minimum value returned by the hardware to the
driver for the analog axes of the joystick(s) on the game
controller. The value of this property is ignored by the
device driver. The joydev kernel module
always returns joystick axis data in the range -32,767 to
32,767 inclusive (in mathematical terms, [-32,767, 32,767]).
Using the default value for this property is always
safe.
The maximum value returned by the hardware to the driver for the analog axes of the joystick(s) on the game controller. The value of this property is ignored by the device driver. The joydev kernel module always returns joystick axis data in the range -32,767 to 32,767 inclusive (in mathematical terms, [-32,767, 32,767]). Using the default value for this property is always safe.
In a cluster configuration, a pointer to the cluster node config element where the device is physically attached. In a non-cluster configuration, this property should have an empty value. Refer to Chapter 4, Configuring a Cluster for more details on cluster configuration and shared input device data.
In spite of the simplicity of the Linux joystick device config element, there are several caveats and points of caution associated with using joysticks and/or game pads on Linux. The following subsections address various issues that must be kept in mind when setting up a VR Juggler configuration that will make use of the Linux joystick device driver.
Before the Linux joystick device driver in Gadgeteer can be
used at all, the Linux joydev kernel module
must be loaded. Some Linux distributions may not include a
pre-compiled version of the kernel module[10], which means that the module must be built from the
Linux kernel source. This is not a trivial process, and it can
have disastrous results if something goes wrong.
For the benefit of users who find themselves lacking a copy
of the Linux joydev kernel module for their
kernel, we include instructions here for building the module on an
unpatched, uni-processor Red Hat Enterprise Linux 3 installation.
The steps may vary with differing Linux distributions and with
differing Linux kernel versions.
Read the following very carefully! These steps will
configure and build a new kernel, but only
a single module (joydev.o) ultimately gets
installed. Nothing else in the kernel installation will be
changed. The only difference to the kernel installation after
performing these steps is that the file
joydev.o will be added to the existing
installation.
First, edit line 4 of the file
/usr/src/linux-2.4.21-4.EL/Makefile so that
it appears as follows:
EXTRAVERSION = -4.EL
Then, the joydev module can be compiled,
installed, and loaded using the following steps. Note that the
percent character (%) represents the command
prompt and should not actually be typed.
% cd /usr/src/linux-2.4.21-4.EL % make mrproper % cp configs/kernel-2.4.21-i686.config .config % make dep % make % make modules % cp drivers/input/joydev.o /lib/modules/2.4.21-4.EL/kernel/drivers/input/joydev.o % insmod joydev
In order for USB joysticks and game pads to be handled by
the joydev kernel module, it is necessary for
the USB configuration to identify the devices correctly. Doing so
requires that the USB device mapping include the identifiers for
the joystick or game pad being used. Modern Linux distributions
come with device mappings for a wide variety of devices, but there
will always be new products and new models of existing products
being released.
First, to determine if a USB joystick or game pad is being
handled by the joydev kernel module, look at
the contents of /var/log/messages when the
device is plugged in. There should be output similar to the
following (from a Linux 2.4 kernel):
kernel: input0: USB HID v1.00 Gamepad [...] on usb2:6.0 /etc/hotplug/usb.agent: Setup hid for USB product 6a4/1580/100
If the device is being handled by the
joydev kernel module, there will be a second
line of output from
/etc/hotplug/usb.agent:
/etc/hotplug/usb.agent: Setup joydev for USB product 6a4/1580/100
If that output is not printed, then the USB joystick or game
pad is not correctly configured to use the
joydev kernel module. In that case, the file
/etc/hotplug/usb.handmap must be extended to
include the missing information.
Fortunately, the first line of output from /etc/hotplug/usb.agent provides the details we need to do this. In the output, the sequence “6a4/1580/100” provides us with the hexadecimal vendor ID (0x06a4) and the product ID (0x1580). This can also be determined using the graphical application usbview, included with the “usbview” package. If usbview is not available, however, the above will work with all Linux distributions.
With the vendor ID and product ID in hand, we can extend
/etc/hotplug/usb.handmap with the following
line:
joydev 0x0003 0x06a4 0x1580 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
Here, the vendor ID appears as the second number and the
product ID as the third. After making this change, it is not
necessary to reboot, but the USB device should be unplugged and
plugged back in to ensure that the device is correctly handled by
the joydev kernel module.
The Linux joystick device returns analog and digital data. The number of analog and/or digital proxies to use and the input source indices to use depends on the physical device. The most convenient way we have found to determine the ordering of the buttons and axes on a given joystick is to use the software utilities jstest (included with the “joystick” package). Pressing buttons and moving joysticks will result in output being printed to the console or terminal window.
[10] Red Hat Enterprise Linux 3 Workstation is one such
distribution that is known to ship without a pre-compiled
copy of the joydev module.