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 and has
support for Xbox1 gamepads, Xbox360 USB gamepads and Xbox360 wireless
gamepads. The Xbox360 guitar and some Xbox1 dancemats might work too.

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



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

Required libraries and tools:

 * libusb
 * boost
 * scons
 * uinput

You can compile by typing:

 % scons

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

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 again.

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
plug in your Xbox360 gamepad and 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 -q

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.

[[ 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.

[[ 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 instantly.  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

[[ 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: start, guide, back, a, b, x, y, black,
white, lb, rb, lt, rt, tl, tr, du, dd, dl, dr

[[ 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 --buttonmap -Y1=Y1

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

 % ./xboxdrv --buttonmap 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.

[[ Running InputDrv ]]
----------------------

The programs 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.

[[ 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 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.



# EOF #