Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



I noticed in quite a few posts on the Gentoo Forums that a HOWTO for joysticks was needed, so I figured I would start one with what I did to get my joystick working.

The USB-Part is for "Saitek Cyborg Evo joystick".

The Gameport-Part is for "MS Sidewinder ForceFeedback".

This also needs some info on force feedback.


USB or Gameport Setup


The old jstest and jscal programs and utilities can be found in the joystick package in portage. If you use KDE there is a joystick section of the KDE control centre. (the peripherals tab)

emerge joystick

Or you can install libjsw and use the joystick calibration program included in that. You need to emerge libjsw with gtk in your USE flags for it to compile and install jscalibrator.

USE="gtk" emerge libjsw

Since calibration may not be needed (see below) this can be done later, it is not essential to installing the joystick modules.


Now go into your kernel menu.

cd /usr/src/linux
make menuconfig

Or, if you prefer, use the genkernel scripts

genkernel --menuconfig all

Turn on the following options in your kernel:

Code: Linux Kernel 2.4 and USB
Input core support -->
 <*> Input core support
 <*> Joystick support
 <*> Event Interface Support
USB Support -->
 <*> Support for USB
  [*] Preliminary USB device filesystem
 <*> UHCI Alternate Driver (JE) support
 <*> OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support
 <*> USB Human Interface Device (full HID) support
  [*] HID input layer support
Code: Linux Kernel 2.4 and Gameport (no Input core support needed !!)
Charakter Devices -->
 Joysticks -->
 <*> Game port support
 <*>  Classic ISA/PnP gameports
 --- Joysticks
 <*>  Microsoft SideWinder digital joysticks and gamepads
Code: Linux Kernel 2.6 and USB
Device Drivers -->
 Input Device Support -->
  <*> Joystick Interface
  <*> Event Interface
   [*] Joysticks
 USB Support -->
  <*> Support for Host-side USB
   [*] USB device filesystem
  <*> EHCI HCD (USB 2.0) support
  <*> OHCI HCD support
  <*> UHCI HCD (most Intel and VIA) support
  <*> USB Human Interface Device (full HID) support
   [*] HID input layer support

Then just compile and install your kernel.

Modules for Joysticks

When joystick support is compiled as a module, there are some additional steps to take. My computer is a pretty standard setup, with an Ensoniq 1371 sound chipset on the motherboard and a Microsoft Sidewinder Force Feedback Pro plugged into its gameport. I needed the following modules:

A standard joystick needs "analog" in place of sidewinder. If ns558 fails to load it is probably not needed. (It is for ISA sound cards , ignore if you have PCI sound cards.) For more info on specific joysticks read:


Load the modules using modprobe. What is really screwed up is that you need all four to make your Sidewinder work, yet none of the modules depend on one another. Is this a design flaw? It may be necessary to use the option

modprobe snd_ens1371 joystick_port=1

again see joystick.txt for details on which drivers do a full autodetect and which require an option to enable the joystick.

With X-Skillz Cube Connection (Game Cube adaptor) you just need to

modprobe joydev

To see if the joystick is functioning try

cat /dev/input/js0

If it is working you should see garbage text characters appear in the terminal. If you do not see anything right away, wait a few seconds to give the kernel time to load the modules and configure the device files, and then try again.

A fuller test can be done using jstest from the joystick package:

jstest /dev/input/js0

If the device does not exist the drivers are probably wrong or not loading correctly. (Usually devfs or udev will create the device automatically if the driver loads and finds a joystick plugged in.)

If this module is already loaded by alsa you will need to stop alsa , unload the module and reload it with the joystick option.

/etc/init.d/alsasound stop
modprobe snd_ens1371 -r
modprobe snd_ens1371 joystick_port=1
/etc/init.d/alsasound start

Once tested you will need to add the required modules to /etc/modules.autoload.d/<kernel-version>

This example works for basic analog stick

snd_ens1371 joystick_port=1

And to ensure autoload loads it before alsa does make sure alsa is in the default rather than boot run-level (see man rc-update for more).

rc-update del alsasound
rc-update add alsasound default

If you prefer adding the option to /etc/modprobe.d/alsa (you don't need to change the runlevel as described before, although you may like to consider if you need alsa during the boot sequence. It is probably more appropriate to attach it to the default run-level anyway).

options snd-card-0 joystick_port=1

After that modification you must run update-modules for the changes to take effect, otherwise you will need to reboot.

Now you are ready to restart alsa:

/etc/init.d/alsasound restart

Joystick Test

Reboot (for kernel recompile) and do a dmesg (for USB). You do not have to reboot if you have compiled modules.

dmesg | grep -i Joystick

Look for Joystick information.

Code: dmesg | grep -i Joystick
input: USB HID v1.00 Joystick [Saitek Cyborg USB Stick] on usb2:2.0

If you see something like this, then your joystick is detected and should work. For gameport /dev/input/jsX should exist. So ls /dev/input/js* will show you if you have the device detected.

cat /dev/input/js0 will produce a string of garbage to the console for stick movement and button clicks. If you get that then you have input from the joystick.

Then run on X-Terminal: jscalibrator

That will create ~/.joystick, so now your joystick should be ready for play in gl-117, zsnes or SearchAndRescue.

Note. This calibration step is generally unnecessary unless the joystick is non-linear, so try it first.

Known Issues

Games and other software which uses joystick

Some software (eg mplayer) needs to be built with the joystick option. Add to USE variable /etc/make.conf or to /etc/portage/package.use on a per package basis.

torcs, tuxracer and flightgear do not need this.

MPlayer will only seek when stick is pressed directly left of right, although this can be changed.

To get XMAME to use the joystick, delete all contents of the .xmame/cfg folder (wipes any key setting you have made) it then defaults to joystick.

You will also need to set .xmame/xmamerc with something like the following

jt 1
as 1
jdev /dev/input/js

see xmame man page for details

Buggy drivers/ multiple sound cards

Using the sound card based ALSA drivers for multiple cards does not work correctly.

They seem unable to distinguish between gameports on two different sound cards in the same machine. Playing sound on one card may result in movement of the coordinates of a joystick connected to the other card.

The adi joystick driver (e.g. for Wingman Extreme Digital) has an upstream bug, the fix is discussed here on the gentoo forums: [1]

Picky Programs / buggy tools

If you run another program after jscalibrator you will probably only see the buttons working. Reloading the driver module should correct this and games such as gl-117 have the jockstick calibrated because of the ~/.joystick file created by jscalibrator.

This is a bug in jscalibrator which does not exit cleanly. It leaves large offsets on the axes so that the mouse pointer is permanently off-screen. It is sufficient to unload the joydev module and then reload it as before:

modprobe -r joydev && modprobe joydev


Also, for some reason, the js_demo program that comes with FlightGear does not show axis movement unless the joystick is unpluged and re-pluged. (I have hotplug installed and setup, so the kernel just detects the joystick every time its plugged back in.) This in turn, does not let you configure your joystick with fgjs correctly, since it is not detecting the axis movement. So I discovered if you unplug and re-plug the joystick back into the USB port, js_demo and fgjs detect the axis movement.

unplugging a joystick connected to the gamesport of a sound card will not generate a kernel event so this only applies to USB devices.

udev override parameters

I'm using the snd_ens1371 for the gameport. I don't need the ns558. But after a clean configuration in the /etc/modprobe.d/alsa with "joystick_port=1" the device /dev/input/js0 don't exist after reboot. After a view tests I figured out that udev is the problem because after an "/etc/init.d/alsasound restart" the device properly works. After some googling I get two solutions.

MacBook & MacBook Pro

MacBooks come with a hardware sensor that can detect sudden motion (free fall, shocks) and protect the hard drive from damage when that happens. That sensor is asigned a joystick address by the kernel (usually /dev/input/js0). That can confuse programs which look for joysticks, and can either render your joystick undetected (Vegastrike) or crash the program (gl-117). The workaround is to build the applesmc driver as a module when configuring your kernel, and unload it prior to running your game or load it after joydev, so joydev gets the /dev/input/js0 address.

Retrieved from ""

Last modified: Thu, 04 Sep 2008 22:47:00 +0000 Hits: 49,995