Introduction

This HOWTO deals with the installation and configuration of Microsoft® Xbox 360™ controllers; both the USB and wireless. The Xbox 360™ controllers and the older Xbox™ controllers should be supported out of the box, but if you are experiencing problems you might want to check out the Testing and Troubleshooting section.

Ubuntu now includes the xpad kernel module with support for the Xbox™ controller and Xbox 360™ (wired/wireless) controller. The tools from the "joystick" package can be used to test and calibrate them from the terminal.

The rest of this HOWTO was originally written for Ubuntu 7.10, although it should apply, with a few modifications, to both older and newer versions which do not already have kernel support for these controllers. The HOWTO is an adaptation of a similar HOWTO for Gentoo Linux, with some general suggestions from various posts on the Ubuntu Forums.

It should be noted that this HOWTO only deals with the regular Xbox™ and Xbox 360™ controllers. Other controllers, peripherals and modules are not dealt with and may or may not work.

Although the steps taken in this HOWTO works for me, I make no guarantee as to the outcome and consequences from following this HOWTO. Use at your own risk.

The (old) Xbox™ Controller

When dealing with the older Xbox™ controllers, all you need to do is to make, or obtain, a USB adapter and plug it in; driver support for the older controllers should already be installed and active. If the controller doesn't respond, see the Testing and Troubleshooting section.

Before you begin

Before you begin I would like to point out that the Xbox 360™ does not use Bluetooth® for its wireless communication. If you have a wireless controller, you need to get an Xbox 360™ Wireless Gaming Receiver for Windows®. Don't worry, it works under Linux too, although there are a few quirks. All you need to do is to plug it in, as you would under Windows®, and it should behave similarly to the USB controller.

Updating the drivers

Experimental support for the Xbox 360™ controller does exist. The xpad kernel module included in kernels before 2.6.26 only supports the old Xbox™ controller though. If you want to use your Xbox 360™ controller with a kernel before 2.6.26, you will have to install an updated xpad module. Since there is no package for it, you will have to compile and install the module yourself.

Alternatively, with older kernels you can use the Userspace Xbox/Xbox360 USB Gamepad Driver.

Installing required packages

In order to compile and install the new drivers, you will need a few packages. The following command will install them for you:

sudo apt-get install linux-headers-`uname -r` build-essential automake1.9

Although it isn't required, you may want additional packages in order to calibrate the controller

sudo apt-get install jscalibrator libgii1 libjsw2

You may, of course, use any package manager you like. Just make sure you install the linux-headers version that corresponds to your current kernel.

Downloading and preparing the drivers

For kernels before 2.6.26, you will need to build an updated kernel module (xpad) or the Userspace Xbox/Xbox360 USB Gamepad Driver.

For the updated xpad module, you will need a directory for the files. The name of the directory doesn't matter, as long as it's empty and you have write permissions to it.

cd
mkdir xpad

The above will change directory to your home directory and create the subdirectory "xpad".

Now, go to the newly created directory and download the files:

cd xpad
wget "http://xbox-linux.cvs.sourceforge.net/*checkout*/xbox-linux/kernel-2.6/drivers/usb/input/xpad.c" "http://xbox-linux.cvs.sourceforge.net/*checkout*/xbox-linux/kernel-2.6/drivers/usb/input/xpad.h"

Creating the Makefile

In your working directory ("xpad"), copy and paste the following to a file called "Makefile", using your favourite editor. Make sure the tabs under "all:" and "install:" remain intact.

KERNEL_PATH?=/usr/src/linux-headers-$(shell uname -r)

EXTRA_CFLAGS=-I$(shell pwd)

obj-m:=xpad.o

all:
        $(MAKE) modules -C $(KERNEL_PATH) SUBDIRS=$(shell pwd)

install:
        cp -f xpad.ko /lib/modules/$(shell uname -r)/kernel/drivers/input/joystick

This should find your current header files, build the new xpad drivers using the recently downloaded source code as a module, and install the module to the appropriate directory.

Compiling and installing the drivers

Assuming your current directory is your working directory ("xpad"), all you need to do is to execute the following commands:

make
sudo make install
sudo modprobe -r xpad
sudo depmod -a
sudo modprobe xpad

This will compile the module, install it, remove the old one, and load the new one. If the process return errors, you probably missed a step. Otherwise, check the Testing and Troubleshooting section.

Testing and Troubleshooting

By now your new module should be installed and ready for use. Connect the controller and type "dmesg" in a terminal. If you see something like "Microsoft Xbox 360 Wireless Controller (PC)...", then the new drivers are supposedly working.

If you installed jscalibrator, you can use it to test and calibrate your controller.

Known issues with Wireless controllers

Support for wireless controllers are still experimental. And although the controllers work, the following issues exist:

• The LED indicator on the controller continues to blink even after the controller has been connected.
• There is no way to turn the controller off, save removing the batteries.
• Some programs may require that you resync the controller after starting them in order for the controller to work.

General issues and solutions

Controller doesn't respond

• Make sure that the controller is plugged in and that the drivers are installed properly. The install directory mentioned in the Makefile has changed before; if the old modules are loaded when you run "sudo modprobe xpad", then xpad.ko should probably be copied elsewhere. If so, locate the old xpad.ko, and overwrite it with the xpad.ko generated from the compiled sources.
• If the "make" process failed, you are probably missing a file, or the tabs in the Makefile got converted to spaces.

• If you just installed the driver, you could try rebooting the system, as that should load all the needed modules. If that doesn't fix it, try reconnecting the controller. You could also try to run the modprobe commands mentioned under Compiling and installing the drivers again.

• If you are using a Wireless Xbox 360™ controller, you may have to resync after starting the program that makes use of it.

Incorrectly mapped buttons

The Gentoo Linux HOWTO on the same subject mentions some fixes if you are having problems with incorrectly mapped buttons. Essentially, you need to figure out which button/axis is controlling what, and what they should be controlling. Then you need to move the corresponding variables around in the source code ("xpad.c") to match your setup, save, and repeat this HOWTO from the "Compiling and installing the drivers" section.

CategoryHardware