xboxdrv/README

[[ Xbox/Xbox360 USB Gamepad Driver for Userspace ]]
===================================================

This is a Xbox/Xbox360 gamepad driver for Linux that works in
userspace. It is an alternative to the xpad kernel driver and has
support for Xbox1 gamepads, Xbox360 USB gamepads and Xbox360 wireless
gamepads. The Xbox360 guitar and some Xbox1 dancemats might work too.
The Xbox 360 racing wheel is not supported, but shouldn't be to hard
to add if somebody is interested.

The Xbox360 chatpad does currently not work and the headset does
neither. There has been some work on reverse enginiering, but no
usable results.

This driver is only of interest if the xpad kernel driver doesn't work
for you or if you want more configurabity. If the xpad kernel driver
works for you there is no need to try this driver.

Newest version of the driver can be found at:

 * http://pingus.seul.org/~grumbel/xboxdrv/

The development version can be optained via:

 * git clone http://pingus.seul.org/~grumbel/xboxdrv.git

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

Required libraries and tools:

 * g++ - GNU C++ Compiler
 * libusb
 * boost
 * scons
 * uinput (userspace input kernel module)
 * git (only to download the development version)
 * X11
 * python-dbus (for xboxdrv-daemon.py)

Once everything installed, you can compile by typing:

 % scons

On Ubuntu 9.10 you can install all the required libraries via:

 % apt-get install \
     g++ \
     libboost1.40-dev \
     libboost-thread1.40-dev \
     scons \
     libusb-dev \
     git-core \
     libx11-dev \
     x11proto-core-dev \
     python-dbus

To load the uinput kernel module automatically on boot add it
/etc/modules, to load it manually type:

 % sudo modprobe uinput

On other distributions exact install instructions might be
slightly different.

[[ Running InputDrv ]]
----------------------

The programs src/inputdrv and gui/inputcfg.py are part of an experiment to
create a very flexible input configuration framework. They are still
in development and not of any use unless you want to hack the
source. Their compilation is disabled by default.

[[ Xorg Trouble ]]
------------------

If you start xboxdrv and instead of having a fully working joystick,
you end up controlling the mouse that might be due to recent changes
in Xorg and its device hotplug handling. There are four workarounds,
the one that involves editing /etc/hal/fdi/policy/preferences.fdi is
the recommont one.

1) Temporary workaround using hal-device
----------------------------------------

Get the device id from hal:

 % hal-find-by-property --key 'info.product' --string 'Xbox Gamepad (userspace driver)'

Then remove the device from hal with:

 % hal-device -r $DEVICEID

2) Temporary workaround using xinput
------------------------------------

Second workaround works with xinput:

 % xinput list
 % xinput set-int-prop $DEVICEID 'Device Enabled' 32 0

3) Permanent workaround using .fdi files
---------------------------------------

The former two workarounds are just temporary and have to be redone
after each start of xboxdrv, the last workaround is a permanent one:

You have to edit:

 /etc/hal/fdi/policy/preferences.fdi

And insert the following lines:

    <match key="input.product" string="Xbox Gamepad (userspace driver)">
      <remove key="input.x11_driver" />
    </match>

4) Permanent workaround by disabling device auto detection
----------------------------------------------------------

A fourth workaround involved disabling the autodetection of Xorg
completly, you can do that by adding the following lines to
/etc/X11/xorg.conf:

Section "ServerFlags"
  Option "AutoAddDevices" "False"
EndSection

Note that without auto detection you will have to manually configure
all your mice and keyborads or your Xorg Server won't start up
properly. So unless you are already familiar with editing Xorg you
better avoid this workaround. Workaround 3) has basically the same
effect, except that auto detection only gets disabled for the single
device it is causing problems.

[[ Wacom Trouble ]]
-------------------

In recent kernels a Wacom graphic tablet creates a joystick device, so
xboxdrv or any other real joysticks ends up as /dev/input/js1 instead
of /dev/input/js0. In many games this causes the joystick to not
function any more.

A temporary workaround for this is to simply delete the joystick
device js0 and replace it with a symbolic link js1 via:

 % sudo ln -sf /dev/input/js1 /dev/input/js0

This workaround will only last till the next reboot, since the device
names are dynamically created, but for the time being there doesn't
seem to any other way to easily work around this issue. 


[[ uinput Trouble ]]
--------------------

On Ubuntu 9.04 the permissions of the uinput device have changed to
0640, meaning only root has access to the device. To change this back
so that users in the group root have access the device and in turn can
run xboxdrv without sudo you have to create a file called:

/etc/udev/rules.d/55-permissions-uinput.rules

With the content:

KERNEL=="uinput", MODE="0660", GROUP="root"


[[ Wine Trouble ]]
------------------

When using the Xbox360 gamepad in Wine it is not specially handled as
Xbox360 gamepad, this means games will not display the proper button
labels, but just numbers (i.e. 'Btn1' instead of 'A' for
example). Asside from that it should work fine.

Xinput support (the DirectInput replacment, not the Xorg xinput) might
not work properly or not at all.

It is currently unknown if this can be fixed by xboxdrv or if it
requires patches to Wine.

# EOF #