xboxdrv/README

[[ XBox/XBox360 USB Gamepad Driver for Userspace ]]
===================================================

This is a XBox/XBox360 gamepad driver for Linux that works in userspace. It
is a alternative to the xpad kernel driver.


[[ Compilation ]]
-----------------

Required libraries and tools:

 * libusb
 * boost
 * scons
 * uinput

You can compile by typing:

 % scons


[[ Running ]]
--------------

First make sure that the xpad kernel module does not get loaded,
either by deleting or renaming it. rmmod might not be enough since it
might be automatically loaded.

Next you have to load the uinput kernel module which allows userspace
programms to create input devices and the joydev module which gives
you the /dev/input/jsX device:

 % modprobe uinput
 % modprobe joydev

You also have to make sure that you have access rights to
/dev/input/uinput, either add yourself to the appropriate group,
adjust the permissions or run xboxdrv as root.

Once ensured that xpad is out of the way and everything is in palce
plug in your XBox360 gamepad and start the userspace driver with:

 % ./xboxdrv

This will create a /dev/input/js0 and allow you to access the gamepad
from any game. To exit the driver press Ctrl-c.

If you have multiple controllers you need to start multiple instances
of the xboxdrv driver and append the -i argument like this:

 % ./xboxdrv -i 1

This will then use the second detected controller, see to see which id
your controller has:

 % ./xboxdrv --list-controller

If you want to abuse the led or rumble of the gamepad for notification
in scripts you can do see via:

 % ./xboxdrv --led 10 --rumble 30,30 --quit

This will cause a mild rumble and the led to rotate, you can stop it
again via, which also happens to be the command you can use to stop
your XBox360 controller from blinking:

 % ./xboxdrv -q


[[ SDL Notes ]]
---------------

To let SDL know which axis act as a hat and which act as normal axis
you have to set an environment variable:

 % SDL_LINUX_JOYSTICK="'XBox360 Gamepad (userspace driver)' 6 1 0"
 % export SDL_LINUX_JOYSTICK

This will let the DPad act as Hat in case you need that for any
game. For most games the driver should work as-is.

See ftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars for more information.


[[ Troubleshooting ]]
---------------------

1) "Error opening XBox360 controller"
-------------------------------------
This means that either your controller isn't plugged in or not
recognized by the driver. To fix this you need to know the idVendor
and the idProduct numbers, which you can find out via:

 % lsusb -v

Once done you can try to add them to the array:

XPadDevice xpad_devices[] = { ... } in xboxdrv.c. 

If you have success with that, send a patch to grumbel@gmx.de

2) "Unknown data: bytes: 3 Data: ..."
-------------------------------------
This means that your controller is sending data that isn't understood
by the driver. If your controller still works, you can just ignore it,
the XBox360 controller seems to send out useless data every now and
then. If your controller does not work and you get plenty of those
lines when you move the sticks or press buttons it means that your
controller talks an un-understood protocol and some reverse
enginiering is required. Contact grumbel@gmx.de and include the output
of:

 % lsusb -v

Along with all the "Unknown data" lines you get.

3) Program starts and then just does nothing
--------------------------------------------

This is what the program is supposed to do. After you started it will
give you basically two devices, a new /dev/input/eventX and a
/dev/input/jsX. You can access and test your controller with jstest
and evtest applications (available from your distribution or in the
tools/ subdirectory). Or in case you want just see if your driver is
working correctly you can pass the -v option:

 % ./xboxdrv -v 

This will cause the driver to output all the events that it received
from the controller.

4) "Error: No stuitable uinput device found"
--------------------------------------------

Make sure that uinput and joydev kernel modules are loaded. Make sure
that you have a /dev/input/uinput, /dev/uinput or /dev/misc/uinput and
permissions to access it.

Before reporting this as a bug make sure you have tested if the driver
itself works with:

 % ./xboxdrv --no-uinput -v

# EOF #