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:

 * libusb
 * boost
 * scons
 * uinput (userspace input kernel module)
 * git (only to download the development version)
 * X11

Once everything installed, you can compile by typing:

 % scons

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

 % apt-get install \
     libboost1.35-dev \
     scons \
     libusb-dev \
     git-core \
     libx11-dev \
     x11proto-core-dev

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 XboxDrv manually ]]
------------------------------

Plug in your Xbox360 gamepad and then unload the xpad driver via:

 % rmmod xpad

If you want to permanently unload it add the following line to
/etc/modprobe.d/blacklist:

blacklist xpad

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 place
start the userspace driver with:

 % ./xboxdrv

Or in case you don't have the neccesary rights (being in group root
should often be enough) start the driver as root via:

 % sudo ./xboxdrv

This will create /dev/input/js0 and allow you to access the gamepad
from any game. To exit the driver press Ctrl-c. 
If you have multiple wired controllers you need to start multiple instances
of the xboxdrv driver and append the -i argument like this:

 % ./xboxdrv -i 1

If you have multiple wireless controller you need to start multiple
instances of the xboxdrv driver and append the --wid argument like
this:

 % ./xboxdrv --wid 1

You have to sync the wireless controller as usual.

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

 % ./xboxdrv --list-controller

When everything works as expected it is recomment that you run xboxdrv
with the silent option:

 % ./xboxdrv --silent

This will suppress the logging of events to the console and will
gurantee that no uneccesarry CPU cycles are wasted.

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 ---led 0 --rumble 0,0 --quit

For rumble to work make sure you have connected the controller to a
USB port that has enough power, i.e. an unpowered USB hub might not
work.

[[ Running XboxDrv via daemon ]]
--------------------------------

You can also run xboxdrv automatically whenever you plug in a gamepad via:

 % tools/xboxdrv-daemon.py

The script assumes that xboxdrv is available from PATH and that hal
and dbus are available.

Note that you lose most of the configurabilty when you launch it
automatically, so this isn't recomment. 

When you want configurability and automatic launching, it is recomment
that you write little startup scripts for your games, such as this:

#!/bin/sh

xboxdrv --trigger-as-button -s &
XBOXPID=$!

# Launch your favorite game
your_favorite_game

kill $XBOXPID
wait $XBOXPID

# EOF #

That way you can individually configure every game and still not have
to worry about launching xboxdrv manually.

[[ Deadzone ]]
--------------

The deadzone is the area at which the sticks do not report any
events. The default is zero, which gives the best sensitifity but
might also cause trouble in some games in that the character or camera
might move without moving the stick. To fix this one has to set the
value to something higher:

 % ./xboxdrv --deadzone 4000

A value of 4000 works quite well for most games. 

You can also give the deadzone in percentage:

 % ./xboxdrv --deadzone 15%


[[ Calibration ]]
-----------------

If your gamepad for some reason can't reach the maximum value or isn't
centered properly you can fix that via the calibration options:

 % ./xboxdrv --calibration X2=-32768:0:32767

X2 is the axis name and the three values that follow are min, center
and max. Simply insert the values that jstest reports when your axis
is in the respective positions.

You can also use the calibration option if you want to make your
joystick more sensitive. A setting of:

 ./xboxdrv --calibration X2=-16384:0:16384

Will cause the joystick device report maximum position when your
stick is only moved half the way.

[[ Square Axis ]]
-----------------

The Xbox360 gamepad, as most other current day gamepads, features a
circular movment range, which restricts the movement so that the
distance to the center never gets beyond 1. This means that when you
have the controller at the top/left the value reported is (0.7, 0.7)
(i.e. length 1, angle 45) instead of (1,1). This behaviour is
different then most classic joysticks, which had a square range and
allowed x and y to be handled completly indepened.

Some old games (i.e. DOS stuff) require a square movement range and
will thus not function properly with the Xbox360 gamepad. Via the
--square-axis option you can work around this issue and diagonals will
be reported as (1,1).

[[ AutoFire Mapping ]]

Autofire mapping allows you to let a button automatically fire with a
given frequency in miliseconds:

 % ./xboxdrv --autofire A=250

Combining --autofire with button map allows you to have one button act
as autofire while another one, emitting the same signal, acts normally.

 % ./xboxdrv --autofire B=250 --buttonmap B=A

[[ Relative Axis Mapping ]]

The function --relative-axis allows you to change the behaviour of an
axis so that your movement of it moves its value up or down instead of
applying it directly.  This is mostly useful for flightsim games that
make use of a throttle control, which you can emulate by using the
relative axis mapping. Since the axis might be upside down, you might
want to use the --axismap function to reverse it.

 % ./xboxdrv --relative-axis y2=64000 --axismap -y2=y2

[[ Button Remapping ]]
----------------------

Button remapping is available via the --buttonmap option. If you want
to swap button A and B start with:

 % ./xboxdrv --buttonmap A=B,B=A

If you want all face buttons send out A button events:

 % ./xboxdrv --buttonmap B=A,X=A,Y=A

Possible button names are: 

Name           | Description
---------------+------------------------------------------------------------------
start, back    | start, back buttons
guide          | big X-button in the middle (Xbox360 only)
a, b, x, y     | face buttons
black, white   | black, white buttons (Xbox1 only, mapped to lb, rb on Xbox360)
lb, rb         | shoulder buttons (Xbox360 only, mapped to black, white on Xbox1)
lt, rt         | analog trigger (needs --trigger-as-button option)
tl, tr         | pressing the left or right analog stick
du, dd, dl, dr | dpad directions (needs --dpad-as-button option)
green, red,    | guitar buttons
yellow, blue,  |
orange         |

[[ Axis Remapping ]]
--------------------

Axis remapping is available via --axismap and works the same as button
mapping. In addition you can supply a sign to indicate that an axis
should be inverted. So if you want to invert the y1 axis start with:

 % ./xboxdrv --axismap -Y1=Y1

If you want to swap the left and right stick start with:

 % ./xboxdrv --axismap X2=X1,Y2=Y1,X1=X2,Y1=Y2

Possible axis names are: x1, y1, x2, y2, lt, rt

Swaping lt or rt with x1, y1, x2, y2 will not work properly, since
their range is different.

[[ UInput Mapping ]]
--------------------

Another more low level form to remap buttons and axis comes in the
form of --ui-buttonmap and --ui-axismap, these allow you to change the
event code that is send to the kernel for a given button or
axis. Usage is similar to the normal button mapping:

 % ./xboxdrv -s --ui-buttonmap X=KEY_A

Except that the right hand side is an event name from
/usr/include/linux/input.h. You can use all KEY_ or BTN_ codes for
--ui-buttonmap and all ABS_ and REL_ ones for --ui-axismap.

Instead of the low level KEY_ names, which represent keycodes, you can
also use the higher level X11 keysyms XK_, the keysyms have the
advantage that they map directly to the key you expect, while a KEY_
name gets mungled by the X11 keymap and will often not report what you
expect in case you use a keymap that is different then your keyboard
(i.e. dvorak on a qwerty keyboard).

A full list of X11 keysyms is available at
/usr/include/X11/keysymdef.h, note that you can only use those that
are reachable by your current keymap. Keysyms that are reachable via
multiple keycodes might break the mapping from keysym to evdev code.

When you try to let a gamepad key send a keyboard events Xorg must
register it as keyboard device to work properly. This seems to work
automatically when you bind more then two keyboard keys, if you bind
less you need to create the file /etc/hal/fdi/preprobe/xboxdrv.fdi
containing:

<?xml version="1.0" encoding="UTF-8"?>
<deviceinfo version="0.2">
  <device>
   <match key="input.product" string="Xbox Gamepad (userspace driver) - Keyboard Emulation">
     <addset key="info.capabilities" type="strlist">input.keys</addset>
   </match>
  </device>
</deviceinfo>

This will tell HAL and later Xorg that xboxdrv acts as keyboard.

For joystick buttons there is in addition to the BTN_JOYSTICK, BTN_X,
etc. macros the special name JS_$NUM, which sets the given button to
the $NUMS joystick button, i.e.:

 % xboxdrv --ui-clear --ui-buttonmap A=JS_0,B=JS_1

Note that this will only work if no other joystick button ids are in
the way

In addition to just the event you can also pass additional
configuration parameter seperated by colons, the exact parameter
differ on the type of event, everything but the first parameter is
optional:

  --ui-axismap X1=REL_???:VALUE:REPEAT
    VALUE:  the maximum value of the event (default: 10)
    REPEAT: number of milisecond to pass before the event is fired again (default: 5)

  --ui-axismap X1=KEY_UP:KEY_DOWN:THRESHOLD
    KEY_UP:    keycode to be send when the axis is moved up
    KEY_DOWN:  keycode to be send when the axis is moved down
    THRESHOLD: threshold that triggers the sending of an event
 
  --ui-buttonmap X1=REL_???:VALUE:REPEAT
    VALUE:  the of the event (default: 10)
    REPEAT: number of milisecond to pass before the event is fired again (default: 5)

If you want to get rid of all uinput mappings you can use --ui-clear
which will leave the driver in a blank state and only map those things
you add later. You can get rid of individual buttons by using the
'void' event:

  % ./xboxdrv \
    --ui-buttonmap tr=void,tl=void,lb=void,rb=void \
    --ui-axismap x2=void,y2=void,rt=void,lt=void,dpad_x=void,dpad_y=void


[[ 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.

[[ 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="'Xbox Gamepad (userspace driver)' 6 1 0"
 % export SDL_LINUX_JOYSTICK

This will let the DPad act as Hat in SDL based application. For many
games the driver will work without this, but especially in Dosbox this
variable is very important.

If you use options in xboxdrv that change the number of axis you have
to adjust the variable accordingly, see:

 * ftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars

SDL_LINUX_JOYSTICK
	Special joystick configuration string for linux. The format is
	"name numaxes numhats numballs"
	where name is the name string of the joystick (possibly in single
	quotes), and the rest are the number of axes, hats and balls
	respectively.


[[ 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 woraround 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.


[[ Mouse Emulation ]]
---------------------

Mouse emulation can be done with something like this:

./xboxdrv \
  --axismap -y2=y2 \
  --ui-axismap x1=REL_X,y1=REL_Y,y2=REL_WHEEL:3:50 \
  --ui-buttonmap a=BTN_LEFT,b=BTN_RIGHT,x=BTN_MIDDLE,y=KEY_ENTER \
  --ui-buttonmap rb=KEY_FORWARD,lb=KEY_BACK \
  --ui-buttonmap dl=KEY_LEFT,dr=KEY_RIGHT,du=KEY_UP,dd=KEY_DOWN \
  -s --deadzone 5000  --dpad-as-button

This will map the dpad to cursor keys, left analogstick to mouse
cursor and right analogstick to mouse wheel.

Note that if you have your mouse buttons switched you must adjust the
above to match your mouse or the button events will come out wrong.

[[ 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. 

[[ 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.

[[ Example Configurations ]]
----------------------------

Prince of Persia: Sands of Time (in Wine)
Prince of Persia: Warrior Within (in Wine)
Prince of Persia: The Two Thrones (in Wine)
Tomb Raider Anniversary (in Wine)
Tomb Raider Legend (in Wine)
----------------------------

 % xboxdrv --trigger-as-button -s 

The triggers are not regonized in these games when they are analog, so
we have to handle them as buttons.


CH Flightstick emulation in Dosbox:
-----------------------------------

In dosbox.conf set:

[joystick]
joysticktype = ch

Start xboxdrv with:

 % xboxdrv -s --trigger-as-zaxis --square-axis --relative-axis y2=64000 --axismap -y2=x2,x2=y2

Your right analog stick will act as trottle control, the trigger as
rudder.


Keyboard controlled games:
--------------------------

The following configuration works for games that are played with
keyboard, like Flash games or games that don't support a joystick, you
have to adjust the keybindings to fit the game:

 % ./xboxdrv \
     --ui-clear \
     --dpad-as-button \
     --ui-buttonmap a=XK_a,b=XK_b,x=XK_x,y=XK_y \
     --ui-buttonmap dl=XK_Left,dr=XK_Right,du=XK_Up,dd=XK_Down \


Sauerbraten
-----------

First analogstick gets mapped te cursor keys, second analogstick gets mapped to mouse.
Note: This is just an incomplete example, not a perfectly playable
configuration, you have to do tweaking yourself.

 % ./xboxdrv \
    --ui-axismap x2=REL_X:10,y2=REL_Y:-10,x1=KEY_LEFT:KEY_RIGHT,y1=KEY_UP:KEY_DOWN \
    --ui-buttonmap a=BTN_RIGHT,b=BTN_LEFT,x=BTN_EXTRA \
    --ui-buttonmap rb=KEY_5,lb=KEY_6,lt=BTN_LEFT,rt=BTN_RIGHT \
    --ui-buttonmap y=KEY_ENTER,dl=KEY_4,dr=KEY_2,du=KEY_1,dd=KEY_3,back=KEY_TAB,start=KEY_ESC \
    -s --deadzone 6000  --dpad-as-button --trigger-as-button


Warsow
------

Note: This is just an incomplete example, not a perfectly playable
configuration, you have to do tweaking yourself.

 % ./xboxdrv \
   --ui-axismap x2=REL_X:10,y2=REL_Y:-10,x1=KEY_A:KEY_D,y1=KEY_W:KEY_S \
   --ui-buttonmap a=KEY_LEFTSHIFT,b=BTN_C,x=BTN_EXTRA,y=KEY_C \
   --ui-buttonmap lb=BTN_RIGHT,rb=KEY_SPACE \
   --ui-buttonmap lt=KEY_Z,rt=BTN_LEFT \
   --ui-buttonmap dl=KEY_4,dr=KEY_2,du=REL_WHEEL:-1:150,dd=REL_WHEEL:1:150 \
   --ui-buttonmap back=KEY_TAB,start=KEY_ESC \
   -s --deadzone 6000 --dpad-as-button --trigger-as-button


[[ Testing ]]
-------------

Knowing how to test a xboxdrv configuration is absolutely crucial in
understanding what is wrong in a given setup. Testing the
configuration in a game is most often not helpful, since you won't see
the true cause beyond endless layers of abstraction between you and
the actual events. Luckily there are a few tools you can use to test,
all of these are command line based and it is recomment that you get
familar with them when you want to do any more complex configuration.

evtest:
-------
evtest lets you read raw input events from (/dev/input/eventX). The
event devices are the very core of all event handling, things like the
joystick devices are derived from the event device, so if you want to
fix some issue on the joystick device, you have to fix the event
device.

evtest is available in the tools/ directory, you might also find it in
your distribution.

jstest:
-------
jstest lets you read the output out of a joystick event device (/dev/input/js0). 

jstest is available in the tools/ directory or as part of your
distribution.

sdl-jstest:
-----------
sdl-jstest lets you see events as games using SDL see them. This is
very important when you want to set and test the SDL_LINUX_JOYSTICK
environment variables.

Currently available via:

 svn co svn://svn.berlios.de/windstille/trunk/sdl-jstest

xev:
----
xev lets you see the events that Xorg sees. Note however that you
might not see all events, since some will be grapped by your Window
manager before they reach xev, this is normal.

xev is part of every Linux distribution, on Ubuntu its available via:

  apt-get install x11-utils

jscalc:
-------
Do not use this tool, for current day joysticks it doesn't do
anything useful, so don't touch it, it won't fix your problems.

mouse:
--------
No tools for testing the output on /dev/input/mouseX are known.

Note:
-----
If the tools provide no output at all, this might not be due to a
wrong configuration, but due to Xorg grabbing your event device and
locking it, see Xorg section for possible fixes.

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

1) "No Xbox or Xbox360 controller found"
----------------------------------------

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, if not,
contact me too, I might be able to provide additional help.

As an alternative you can also use the --device and --type option to
enforce a USB device as well as a controller type an bypass any auto
detection.


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, 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


5) The wireless controller doesn't work
----------------------------------------

You have to sync the controller befor it can be used, restart of the
driver isn't needed and the driver should let you now when it recieves
a connection after you sync the controller.

[[ Force Feedback / Rumble ]]
-----------------------------

Force feedback is disabled by default and has to be enabled with:

 % ./xboxdrv --force-feedback

Xboxdrv works via the standard kernel force feedback interface. For
documentation on the FF interface see:

 * http://github.com/github/linux-2.6/blob/f3b8436ad9a8ad36b3c9fa1fe030c7f38e5d3d0b/Documentation/input/ff.txt
 * /usr/include/linux/input.h

Additional, non Linux related, force feedback related information can
be found at:

 * http://www.immersion.com/developer/downloads/ImmFundamentals/HTML/
 * http://msdn.microsoft.com/en-us/library/bb219655(VS.85).aspx

fftest is an application you can use to test the force feedback
interface.

Since the Xbox360 controller supports just rumble not full force
feedback, xboxdrv tries to emulate other effects. This emulation
hasn't been tested much and might not always work as expected. Bug
reports and test cases are welcome.

Force feedback is disabed by default since it seems to causes trouble
in certain application, namely "Tomb Raider: Legend" when run in Wine
crashes at startup when rumble is enabled, while it works perfectly
when rumble is disabled.

"Tomb Raider: Anniversary" running in Wine seems to work together with
xboxdrv and rumble, but hasn't been intensivly tested.

You can change the rumble strength via:

 ./xboxdrv --rumble-gain 50%

Values larger then 100% are possible as well.

Note that you must close the application that is using force feedback
always before you close the xboxdrv driver, else you might end up with
a hanging non-interruptable xboxdrv process that will require a reboot
to get rid of.


[[ Known bugs ]]
----------------

X11 keysyms might not work correctly in '--ui-buttonmap a=XK_Foobar'
when Foobar is mapped to multiple keycodes in the keymap. 

Workaround: Use KEY_ instead or cleanup your keymap


Force feedback support is brittle, if you Ctrl-c the driver in the
wrong moment you will end up with a dead uninterruptable process and
basically have to reboot. This looks might a kernel issue and not a
xboxdrv one. 

Workaround: Kill the app that uses xboxdrv before xboxdrv itself.



# EOF #