Howto: Use Xbox Controllers (original, 360, 360 wireless, 360 guitar) with Linux

[wootah]

Howto: Use Xbox Controllers (original, 360, 360 wireless, 360 guitar) with Linux
(June 10th, 2008 ) by ~Wootah

EDIT:
June 7th, 2011: This information has changed significantly since its original posting. Please see the edits that follow (mostly link updates)

Intro
Currently, Xbox controller support for Linux has been limited at best and the only available option we have, is the xpad kernel driver. Unfortunately, this driver doesn't work with 360 game pads (well or at all?). Thus, grumbel wrote a user space driver for xbox controllers.

The author, grumbel, provided very good instructions on how to install and use the driver, but I figured this would help out a lot and provide more exposure so we could potentially help better the driver.

As of this writing (June 10th, 2008 )the current version from his website is 0.2rc1.

Warning (as always ))
Please note, I based this guide off of my system, Ubuntu 7.10. Please let me know if there are any changes for newer versions of Ubuntu (8.04+). This howto is a guide and may not work 100% for your system, setup, geographical location, humidity, country, gender or personal height. I am not responsible for what you do to your machine, cat, parents, body, xbox (and its controllers) or any item by following this guide and neither is the author of the xbox driver, grumbel. No guarantees what so ever folks.

Do so at your own risk (also known as try it on a test machine first, please )

Supported Controllers

• Original Xbox controllers through USB (with a cable modification)
• Xbox 360 USB Controllers
• Xbox 360 Wireless Controllers through the Wireless USB Adapter
• Xbox 360 USB Guitar

Some third party controllers may work as well (MadCatz) and they are probably already available. To check support for a particular controller, review the file xboxdrv.cpp and look for the line XPadDevice xpad_devices. You may even be able to add in support for your particular controller by adding the hardware identifiers into xboxdrv.cpp and recompiling the driver (the README talks about this further in depth).

Features

• Executes in user space on top of libusb. This means that you do not have to recompile the kernel
• Provides a joystick device (/dev/input/js0)
• Allows remapping of the buttons and axises
• Support of the analog triggers (LT, RT) along with reconfiguration into a digital mode (they function just as buttons)
• Change the LED status of the ring of light on the 360 pads
• Many other features! See the author's webpage listed in the links below

Missing Features
Not all features have been implemented, as the current version is 0.2 which was released on May 3rd, 2008.

• Rumble support is limited with no force feed-back. Only scripts or simple testing may use this feature.
• No Mouse emulation (yet)
• Xbox dancemat (for games like Dance Dance Revolution) is still untested. The author would like some help
• Chatpad and Headset are not implemented yet. Once again, the author needs help.

Installation
Alright, down to business.

Requirements/Setup Overview

1. The following kernel modules must be included and loaded:
   
   1. uinput
   2. joydev
   
   
2. The xpad kernel module IS NOT LOADED.
3. The following libraries and tools for compiling:
   
   1. libusb
   2. boost
   3. scons
   4. uinput (Ubuntu 7.10 already provides this, afaik)
   
   
4. The driver itself from the author's website http://pingus.seul.org/~grumbel/xboxdrv/

For the advanced users along with those familiar with scons, this should be enough to get you going. You lucky guys can skip the next section (and check out Driver Usage), but for myself and the others, please continue

Pre-compiling Setup

Step One
We must ensure we have the kernel modules loaded listed in 1a and 1b. To check, we can issue the following commands at the terminal:

lsmod | grep uinput
lsmod | grep joydev

If these modules are not loaded, you may load them by issuing modprobe commands:

sudo modprobe uinput
sudo modprobe joydev

If you did add these modules, then you should probably ensure that they are automatically loaded every time you start up your machine. To ensure this occurs, edit /etc/modules and add the modules at the end (perhaps with a comment to let you know what they are used for and maybe a date for reference.) Example:
/etc/modules :

# /etc/modules: kernel modules to load at boot time.
#
# This file contains the names of kernel modules that should be loaded
# at boot time, one per line. Lines beginning with "#" are ignored.

lp
fuse

# The following two modules are used with the xbox controller driver.
# Added on June 10th, 2008
uinput # for creating userspace drivers. 
joydev # for joystick devices

Step Two
Check to see if the xpad module is loaded:

lsmod | grep xpad

For my machine, this module was not loaded; thus, I lucked out. If it is loaded for you, you may issue the rmmod command:

sudo rmmod xpad

The author states that "rmmod might not be enough since it might be automatically loaded again".

Could someone let me know how one would fix that?

Step Three
Now that we have the proper modules loaded, we need the software and libraries to compile everything together. If you do not have the build-essential package, you will need that first:

sudo apt-get install build-essential

Issue the following commands:
libusb:

sudo apt-get install libusb-dev

libboost:

sudo apt-get install libboost-date-time-dev libboost-date-time1.34.1 libboost-dev libboost-doc libboost-filesystem-dev libboost-filesystem1.34.1 libboost-graph-dev libboost-graph1.34.1 libboost-iostreams-dev libboost-iostreams1.34.1 libboost-program-options-dev libboost-program-options1.34.1 libboost-python-dev libboost-python1.34.1 libboost-regex-dev libboost-regex1.34.1 libboost-signals-dev libboost-signals1.34.1 libboost-test-dev libboost-test1.34.1 libboost-thread-dev libboost-thread1.34.1

scons:

sudo apt-get install scons

OR FOR YOU IMPATIENT :

sudo apt-get install libusb-dev libboost-date-time-dev libboost-date-time1.34.1 libboost-dev libboost-doc libboost-filesystem-dev libboost-filesystem1.34.1 libboost-graph-dev libboost-graph1.34.1 libboost-iostreams-dev libboost-iostreams1.34.1 libboost-program-options-dev libboost-program-options1.34.1 libboost-python-dev libboost-python1.34.1 libboost-regex-dev libboost-regex1.34.1 libboost-signals-dev libboost-signals1.34.1 libboost-test-dev libboost-test1.34.1 libboost-thread-dev libboost-thread1.34.1 scons

Compiling! (Step Four)
The best part! We can now grab the driver from the author's website. As of this writing, version 0.2rc1 is available here: removed. (EDIT: This link is old. Please go directly to the website for the latest version: http://pingus.seul.org/~grumbel/xboxdrv/). The best way to do this for now, would be to create a temp. directory in your home directory, download the driver there and extract its contents. At the terminal:

cd ~
mkdir tmp
cd tmp
wget http://pingus.seul.org/~grumbel/xboxdrv/xboxdrv-linux-0.2.tar.bz2
tar -xvvf xboxdrv-linux-0.2.tar.bz2

Now we can move into that directory and start compiling! At the terminal:

 cd xboxdrv-linux-0.2 
 scons

If everything goes alright, the driver should compile successfully and you should now have a beautiful program sitting there begging for you to use it:

tripp@eclipse-desktop:~/tmp/xboxdrv-linux-0.2$ ls -lsa xboxdrv 
1272 -rwxr-xr-x 1 tripp tripp 1297401 2008-06-10 18:47 xboxdrv

Driver Usage

So if you have made it this far with no problems, that either means I did my job right, or your system is unique/different . From this point, we can now plug in the wireless receiver or the xbox controller. If you issue a lsusb, you should see your device listed somewhere in the list.

Impatient People and Insta-Test
Let's test the driver right away.

For this example, I will be using the Xbox 360 Wireless Receiver USB Adapter and an Xbox 360 Wireless Controller. I plugged in the wireless adapter, issued the following command, turned on my controller and finally sync'd the two together.

Issuing the following command at the terminal in the installation directory gives me these reults (which I will explain in depth later on):

 tripp@eclipse-desktop:~/tmp/xboxdrv-linux-0.2$ sudo ./xboxdrv --wid 0 
 USB Device:        003:007 
 Controller:        "Microsoft Xbox 360 Wireless Controller (PC)" (idVendor: 0x045e, idProduct: 0x0719) 
 Wireless Port:     0 
 Controller Type:   Xbox360 (wireless) 
 Deadzone:          0 
 Rumble Debug:      off 
 Rumble Speed:      left: 0 right: 0 
 LED Status:        auto 
 ButtonMap:         none 
 AxisMap:           none 
 Starting with uinput 
  
 Your Xbox/Xbox360 controller should now be available as: 
   /dev/input/js0 
   /dev/input/event6 
  
 Press Ctrl-c to quit 
  
 Connection status: nothing 
 Connection status: nothing 
 Connection status: nothing 
 Connection status: controller connected 
 Serial:  d:f6:10:d2:26:4d: 0 
 Battery Status: 161 
 Unknown: len: 29 data: 0x00 0x00 0x00 0x20 0x1d 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0x00 0x00 0x00 0x05 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0x00 0x00 0x40 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0xf8 0x02 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0xf8 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0xf8 0x02 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0xf8 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00  
 Unknown: len: 29 data: 0x00 0xf8 0x02 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00

From here, if we do anything on the controller, it will show up. This is how we know things are working ok:

 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:1 B:0 X:0 Y:0  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:0 X:0 Y:0  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:1 X:0 Y:0  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:0 X:0 Y:0  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:0 X:1 Y:0  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:0 X:0 Y:0  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:0 X:0 Y:1  LB:0 RB:0  LT:  0 RT:  0 
 S1:( -2106,   4124)  S2:(  -319,   1673) [u:0|d:0|l:0|r:0]  back:0 guide:0 start:0  sl:0 sr:0  A:0 B:0 X:0 Y:0  LB:0 RB:0  LT:  0 RT:  0

From here we can see that I pressed and released A, B, X and Y. Awesome. Stuff works!
To stop, we issue CTRL-C twice.

Patient People and More Details

When I read these tutorials I like to know my that stuff is working alright which is why I included the impatient part. Anyways, here are some of the features of the driver:

 ./xboxdrv --help
 Usage: ./xboxdrv (OPTION)... 
 Xbox360 USB Gamepad Userspace Driver 
  
 General Options:  
   -h, --help               display this help and exit 
   --help-led               list possible values for the led 
   --help-devices           list supported devices 
   -s, --silent             do not display events on console 
   -i, --id N               use controller with id N (default: 0) 
   -w, --wid N              use wireless controller with wid N (default: 0) 
   -L, --list-controller    list available controllers 
   -R, --test-rumble        map rumbling to LT and RT (for testing only) 
   --no-uinput              do not try to start uinput event dispatching 
  
 Device Options:  
   -d, --device BUS:DEV     Use device BUS:DEV, do not do any scanning 
  
 Status Options:  
   -l, --led NUM            set LED status, see --list-led-values (default: 0) 
   -r, --rumble L,R         set the speed for both rumble motors [0-255] (default: 0,0) 
   -q, --quit               only set led and rumble status then quit 
  
 Configuration Options:  
   --deadzone INT           Threshold under which axis events are ignored (default: 0) 
   --trigger-as-button      LT and RT send button instead of axis events 
   --trigger-as-zaxis       Combine LT and RT to form a zaxis instead 
   --dpad-as-button         DPad sends button instead of axis events 
   --dpad-only              Both sticks are ignored, only DPad sends out axis events 
   --type TYPE              Ignore autodetection and enforce controller type 
                            (xbox, xbox-mat, xbox360, xbox360-wireless, xbox360-guitar) 
   -b, --buttonmap MAP      Remap the buttons as specified by MAP 
   -a, --axismap MAP        Remap the axis as specified by MAP 
  
 Report bugs to Ingo Ruhnke <snipped to help avoid spam!>

I believe most of the options are very straight forward, but there is one part that needs a little bit of attention, --id and --wid.

If you are using a wired controller, use the --id option; for a wireless controller, use the --wid. In the impatient example, I used --wid because I was using a wireless controller which happened to be the only controller I wanted connected. You can connect additional controllers, but you must run the command for each controller. For example, if you had two wireless controllers:

 ./xboxdrv --wid 0
 ./xboxdrv --wid 1

Two wired controllers?

 ./xboxdrv --id 0
 ./xboxdrv --id 1

Nice and clear? Great! But what if you don't know what the ID or the WID is?

 tripp@eclipse-desktop:~/tmp/xboxdrv-linux-0.2$ ./xboxdrv -L 
  id | wid | idVendor | idProduct | Name 
 ----+-----+----------+-----------+-------------------------------------- 
   0 |   0 |   0x045e |    0x0719 | Microsoft Xbox 360 Wireless Controller (PC) (Port: 0) 
   0 |   1 |   0x045e |    0x0719 | Microsoft Xbox 360 Wireless Controller (PC) (Port: 1) 
   0 |   2 |   0x045e |    0x0719 | Microsoft Xbox 360 Wireless Controller (PC) (Port: 2) 
   0 |   3 |   0x045e |    0x0719 | Microsoft Xbox 360 Wireless Controller (PC) (Port: 3)

This example shows my wireless receiver and the four ports it provides for xbox controllers. Now unfortunately I don't have any wired controllers to test, but I imagine it is very similar.

Test with a Game

If you can see that everything is working ok, we can now test with a game. I have tried TuxKart and Neverball so far and they seem to work as expected. Load up the driver with the appropriate options and leave it running in the terminal then try it with the two games I mentioned as I know these work.

Leave some messages with other games that you know work. Pretty much any game that will let you use a joystick should work.

Post Game Test

Once you know things work properly with games, you can append the --silent option to suppress the reporting of the driver for better performance.

The End Part

Hopefully everything works out ok and the driver functions as expected. Please remember, this driver is only version 0.2 and is considered as the first release candidate. There is a README file with additional information in the installation directory that may answer any other problems that you encounter—try taking a look there before posting a question.

If you have any major problems or would like to contribute to the driver effort, please visit the author's web page at: http://pingus.seul.org/~grumbel/xboxdrv/

I would also like to thank grumbel for releasing this great driver along with its code, as it works wonderfully for my system! Also, most of this information comes from him anyways.

Please seriously consider helping out the author in any way possible folks (documentation, coding, providing information for the chatpad/headset, donations [I'm saying that purely out of my own accord—grumbel didn't put me at gunpoint or offer me incentives] or any other skills that this community can provide).

If anyone can provide corrections or suggestions, please let me know by a PM and I will update this howto and mention your name.

I would love to be able to use all the features of the controller with Linux and I'm sure in the future it will work better than the Windows equivalent!

Common Driver Executions

• One Wired Controller:

  sudo ./xboxdrv --id 0

• One Wireless Controller:

  sudo ./xboxdrv --wid 0

• Suppress console logging on a wireless controller:

  sudo ./xboxdrv --wid 0 --silent

• List connected controllers:

  ./xboxdrv --list-controller

Links

• grumbel's website - http://pingus.seul.org/~grumbel/xboxdrv/
• Downloads (PPA, git, source, scroll down a bit) - http://pingus.seul.org/~grumbel/xboxdrv/
• Another thread that might be useful (mentions xpad driver just in case this how-to doesn't work) - http://ubuntuforums.org/showthread.php?t=404577

Additional Thoughts/Problems

• For whatever reason, I had to run the driver using sudo. I probably goofed somewhere, but things seem to be ok
• Check permissions on /etc/input/uinput. Somewhere they suggested changing the permissions to 664. This might help someone?

[Garudi]

Awesome guide works great with my wireless 360 controller. I've been looking for something like this for a while now. /off to test with some emulators

[wootah]

Awesome guide works great with my wireless 360 controller. I've been looking for something like this for a while now. /off to test with some emulators

Hey, let us know how the emulators work

[Boktai1000]

Im thinking about trying this, do you have to execute that command every time you want to use your controller? Also im using Xpad right now and when I boot i cant have my guitar and my controller both plugged in, do you know if this will let me? (Guitar Hero X-Plorer + Microsoft Xbox Wireless Receiver [Wireless 360 Controller])

[wootah]

Im thinking about trying this, do you have to execute that command every time you want to use your controller? Also im using Xpad right now and when I boot i cant have my guitar and my controller both plugged in, do you know if this will let me? (Guitar Hero X-Plorer + Microsoft Xbox Wireless Receiver [Wireless 360 Controller])

For now, yes, since it runs in userspace and it is not a kernel module. This driver will let you use both, but you will have to run two instances of it. Luckily, they can run as silent in the background

[wootabix]

I just tried this with a wired controller but it doesn't seem to work.

xboxdrv hangs at the following:


USB Device: 001:009
Controller: "Microsoft Xbox 360 Controller" (idVendor: 0x045e, idProduct: 0x028e)
Controller Type: Xbox360
Deadzone: 0
Rumble Debug: off
Rumble Speed: left: 0 right: 0
LED Status: auto
ButtonMap: none
AxisMap: none


There are no /dev/input/jsX devices created. I added some logging to the code and it seems it is hanging trying to find the /dev/input/jsX devices at this line in find_jsdev_number in xboxdrv.cpp:

if (access(filename1, F_OK) != 0 && access(filename2, F_OK) != 0)

Note: to get this far I have to start xboxdrv as root. If I don't, it bombs out after the AxisMap: none message with "Exception: Error couldn't claim the USB interface"

I'm running ubuntu-8.04 desktop (64bit)

Any suggestions?

[wootah]

Are the kernel modules uinput and joydev still are listed in lsmod? It sounds like the joystick device is not being created.

[wootabix]

Actually, it gets further than I said, but still hangs. joydev and uinput are there. It can't open the usb device for some reason. An strace shows:

ioctl(3, USBDEVFS_REAPURBNDELAY, 0x7fffaca55098) = -1 EAGAIN (Resource temporarily unavailable)
select(4, NULL, [3], NULL, {0, 1000}) = 0 (Timeout)

I wonder if it is 64bit issue ? (I am running 64bit Ubuntu 8.04)

[wootah]

Actually, it gets further than I said, but still hangs. joydev and uinput are there. It can't open the usb device for some reason. An strace shows:

ioctl(3, USBDEVFS_REAPURBNDELAY, 0x7fffaca55098) = -1 EAGAIN (Resource temporarily unavailable)
select(4, NULL, [3], NULL, {0, 1000}) = 0 (Timeout)

I wonder if it is 64bit issue ? (I am running 64bit Ubuntu 8.04)

You could very well be correct. I have no experience in a 64bit environment, so I have no idea what kind of problems might occur.

Did you try running the xboxdrv with sudo ?

EDIT: Where is the uinput and joydev devices located on your system ? /dev/input/uinput ?

[dudude]

I am also running Hardy 64 bit and when I this is what I get when I run xboxdrv

robert@robert-desktop:~/Desktop/Icons/xboxdrv-linux-0.2$ sudo ./xboxdrv 
USB Device:        003:007
Controller:        "Microsoft Xbox 360 Controller" (idVendor: 0x045e, idProduct: 0x028e)
Controller Type:   Xbox360
Deadzone:          0
Rumble Debug:      off
Rumble Speed:      left: 0 right: 0
LED Status:        auto
ButtonMap:         none
AxisMap:           none
Exception: Error couldn't claim the USB interface

I double checked to make sure that xpad was not loaded, joydev and uinput were, and that the controller was showing up at /dev/input/js0.

I got the program to start, but then it ran into an error.

ioctl(3, USBDEVFS_SUBMITURB, 0x7fffedef1250) = -1 ENOENT (No such file or directory)
write(1, "Exception: USBError: -2\n", 24Exception: USBError: -2
) = 24
write(1, "error submitting URB: No such fi"..., 48error submitting URB: No such file or directory
) = 48
exit_group(0)                           = ?
Process 26941 detached