Joystick control - for the lazy in us

Joystick control is a simple tool that lets you control popular media applications using your joystick. All you need to tell it is which joystick device you want to use, and that’s all! Optionally, you can specify priorities for your applications, so when one is not running, Joystick control automatically directs joystick commands to the next running application on the list.

Curious? Take a look!

How it works

Joystick control connects to your joystick and starts detecting button presses and yoke movements. When one of these events happen, Joystick control executes the appropriate action for the highest-priority media application you have running. It really is that simple.

What it requires

Joystick control requires:

• a joystick or gamepad, properly configured for use
• Linux
• Python
• GNOME
• the Python GTK+ 2, GNOME and Glade bindings
• any application that can be controlled by Joystick control
  • Rhythmbox
  • XMMS
  • Beep media player
  • amaroK
  • tvtime

All major distributions include these packages, either as default or in their package manager repositories. You can get these things in a matter of minutes, so there's no excuse not to try Joystick control.

How to get and install it

There are three ways you can get Joystick control:

Official, ready-to-install release for your distribution

Find it on the releases page. Install it using your distribution's package manager.

Official, buildable source package

Get the compressed tape archive on on the releases page. Install it using Python's distutils.

Latest code, directly from our Git repository

Clone our Git repository to get the latest snapshot of the source code. You can inspect the repository online too.

The one-page manual

Open Joystick control, by accessing your desktop environment's main menu, multimedia (sound/video) group, Joystick control. Joystick control will open.

Joystick control should have autodetected your gaming device (typically <code>/dev/js0</code> or <code>/dev/input/js0</code>). <code>js0</code> represents the first joystick device. If you have another joystick or gamepad, just select it from the drop-down (<code>js1</code> or type the path to the device.

If no device appears, or you see an error message, see the troubleshooting guide below.

Once it's running, you can safely close the preferences window, and it will remain running on the notification area (see below for more information). If you log out, Joystick control will open again once you log back in.

Controlling your applications

Joystick control automatically keeps tabs on the currently open media applications. Whenever one of them is open:

• Gamepad/joystick left will rewind to the last song. If you are watching TV, it will change channel down.
• Gamepad/joystick right will skip to the next song. If you are watching TV, it will change channel up.
• Button 1 will toggle play/pause. If you are watching TV, it will jump to the last channel you were watching.
• Button 2 will stop playback

Some actions are not supported on all applications.

Application priorities

You can define which application takes precedence, when controlling them via your joystick. This is useful when you have several media applications open, and you want to control one of them, but not the other.

The preferences window contains a list of all controllable applications. Use the Up/Down buttons to put your preferred applications first on the list. For example, if you have Rhythmbox and tvtime open, and tvtime is higher on the list, the joystick commands will be directed to tvtime; once you close tvtime, Rhythmbox will be controlled.

You can see which application is running by checking the Running? column in the preferences window.

Showing and hiding Joystick control

As nice as it may look, it gets kind of tiresome to have the window open all the time. Fortunately, Joystick control can be hidden out of view. When it's running, a small joystick icon will appear on your notification area. Either click it once, or click the Close button on the Joystick preferences window to hide it.

To show the preferences window again, click the joystick icon on the notification area again. Do not reopen Joystick control, as this would open another instance and command your applications twice, without prejudice.

Exiting Joystick control

If you need to use your joystick for other purposes, such as gaming, and Joystick control interferes, bring the preferences window up and click the Quit button.

Troubleshooting

If Joystick control cannot detect any devices, it means one of the following conditions is happening:

• there are no joysticks plugged in (we can simply rule that out by virtue of you being smart)
• the joystick is not properly configured on Linux
• you do not have permission to open the joystick device file

To solve this, you will need root (administrator) privileges. Follow each one of these three steps to fix this issue.

You need to load the appropriate driver for your joystick interface, and then load the appropriate driver for your joystick or gamepad. On recent kernels, this should automatically create the device files needed. One way to accomplish that on startup is adding the following lines to the /etc/modules file.

install joydev /sbin/modprobe --ignore-install joydev && /sbin/modprobe ns558 && /sbin/modprobe analog
remove joydev /sbin/modprobe -r analog && /sbin/modprobe -r ns558 && /sbin/modprobe -r --ignore-remove joydev

(these are two separate lines) and then issuing the /sbin/modprobe joydev command on the command line. Replace analog with the appropriate joystick driver, and ns558 with the appropriate joystick interface driver (by the way, 99% of the time, ns558 is right).

Now test it! With root privileges, try to run the following command: cat /dev/input/js0

(older Linux versions might use /dev/js0 instead). You should see a bit of garbage, or perhaps nothing, until you press a button or pad, or move the rudder or a hat on your joystick, where more garbage should follow. Interrupt this with Ctrl+C. If you are returned to the command prompt immediately, preceded by a No such device error, this means the wrong driver is installed. Check your distribution documentation or refer to other sources. If you see No such file or directory instead, you might need to manually make the device node yourself. You can accomplish this by using the command mknod /dev/input/js0 c 13 0 on the command line.

Software development information

This is the first known application that uses the joystick in Python. Well, that's not true, I might have been blowing a bit of smoke up your chimney. What's true is this:

• the joystick code is easily excisable
• the code reads joystick events
• the code collapses multiple identical events into one (for broken gamepads like mine)
• the code considers a threshold
• the code for joystick processing is completely multithreaded, and will deliver events to any function or method of your choosing. Keep in mind the method of your choosing will be executed in thread context, so if you're using GTK+, you better use gobject.idle_add to execute more stuff in your app context! See the on_joystick_event and on_joystick_event_synchronized callbacks in the JoystickControl class for an example.