xboxdrv

xboxdrv (1) User Commands xboxdrv (1)

NAME
xboxdrv - A Xbox/Xbox360 gamepad driver that works in userspace

SYNOPSIS
xboxdrv [OPTION]... [--] [COMMAND] [ARGUMENTS]

DESCRIPTION
xboxdrv is a driver for Xbox and Xbox360 gamepads. It works by reading
the raw data from the controller with the userspace library libusb and
then passes the interpreted data to the kernel via uinput. This allows
xboxdrv to provide regular joystick and event devices, which makes it
compatible with all Linux software.

Aside from the pure driver, xboxdrv also includes a rich set of
configuration options that allow you to tweak the abilities of the
virtual input devices that xboxdrv will create. This includes basic
button and axis remapping, as well as more complicated things like mouse
and keyboard emulation, auto-fire and throttle control emulation.

It is also possible for xboxdrv to read input data directly from an event
device, this allows the use of the configurability of xboxdrv on regular
PC joysticks, keyboards and mice and thus lets xboxdrv serve a similar
purpose as joy2key. See the option --evdev below for more information.

When a COMMAND is provided xboxdrv will launch that application and be
running till that application exits. This is a convenience function to
make it easier to use xboxdrv in wrapper scripts. See the section
[Writing Start-Up Scripts for Games] for more information.

OPTIONS
GENERAL OPTIONS
-h, --help
Display help text and exit.

-V, --version
Print the version number and exit.

-v, --verbose
Print verbose messages.

--debug
Print even more verbose messages then --verbose.

-s, --silent
Do not display controller events on the terminal. For regular use
this option should always be used as output data to the terminal
can eat up quite a bit of CPU.

--quiet
Do not display startup text and suppress most other output.

--priority PRIORITY
Possible values for PRIORITY are "normal" and "realtime". Realtime
scheduling gives the xboxdrv process higher priority and thus
allows it to function properly even when the machine is under
load.

Note that realtime priority requires running xboxdrv as root, when
running xboxdrv as user there is no way to increase the priority.

This option is deprecated, use chrt(1) instead to achive the same
effect.

LIST OPTIONS
--help-led
List possible values for the led.

--help-devices
List supported devices.

--list-supported-devices
List supported devices (used by xboxdrv-daemon.py).

--list-supported-devices-xpad
List supported devices in xpad.c style.

--help-abs
List all allowed EV_ABS symbols.

--help-rel
List all allowed EV_REL symbols.

--help-key
List all allowed EV_KEY symbols.

--help-x11keysym
List all allowed X11 Keysym symbols.

--help-axis
List all allowed XboxAxis symbols.

--help-button
List all allowed XboxButton symbols.

--help-all
List all symbols that can be used in --ui-buttonmap, --ui-axismap,
--buttonmap and --axismap. This option is the same as --help-abs,
--help-rel, --help-key, --help-x11keysym, --help-axis and
--help-button.

CONFIG FILE OPTIONS
-c, --config FILE
Reads configuration information from FILE. Configurations from
file are handling as if they would be command line options at the
position of --config FILE.

The syntax of FILE is the familiar INI syntax used for many
configuration files. Regular key/value pairs must go into the
[xboxdrv] section. '#' and ';' can be used for comments. Key
names have for most part the same name as command line options.
Command line options that take a list of input mappings
(--ui-buttonmap, --ui-axismap, --evdev-absmap, ...) can be split
of into their own section for better readability.

The examples/ directory contains some example configuration files.

[xboxdrv]
silent=true
deadzone=6000
dpad-as-button=true
trigger-as-button=true

[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

# EOF #

--alt-config FILE
A shortcut for writing --next-config --config FILE.

To load multiple configuration options use:

xboxdrv --config first.ini --alt-config second.ini --alt-config third.ini

-o, --option NAME=VALUE
Set an option as if it would come from a config file from the
command line.

--write-config FILE
Write an example configuration file to FILE.

DAEMON OPTIONS
-D, --daemon
Run xboxdrv as daemon. If this option is given xboxdrv will listen
to udev for USB connection events and launch driver threads for
newly connected controllers.

Configuration options can still be supplied as usual. Note
however that xboxdrv when run as daemon will not create new uinput
devices on demand, instead it will only create devices once at
startup for the given configurations and then assign new
controllers to these configurations. While this means xboxdrv
can't support an unlimited number of controllers, it also means
that xboxdrv can allow hot plugging even for applications that
don't support it themselves, as applications will only see the
permanent device files, not the controller that xboxdrv will
change around under the hood.

An example configuration that supports three controller would look
like this:

xboxdrv --daemon \
# config options for the first controller
--next-controller \
# config options for the second controller
--next-controller
# config options for the third controller

The --match option can be used to limit the controller slots to
only those controllers that match the given RULE and thus be used
to assign configurations only to specific controllers.

--detach
Detaches xboxdrv from the current shell, only valid if --daemon is
given.

--pid-file FILE
Write the xboxdrv daemon process id to FILE.

--dbus BUS
Set which bus type xboxdrv should connect to. Allowed values for
BUS are session, system, disabled and auto. The default is auto,
which will detect the appropriate bus type depending on if xboxdrv
is run as root (system or as user (session). Running with disabled
will disable D-Bus support completely.

--on-connect EXE
Launches EXE when a controller gets connected. As arguments
"BUSDEV:DEVNUM", "idVendor:idProduct", "NAME are provided.

--on-disconnect EXE
Launches EXE when a controller gets disconnected. As arguments
"BUSDEV:DEVNUM", "idVendor:idProduct", "NAME are provided.

DEVICE OPTIONS
-L, --list-controller
List available controllers on the system.

-i, --id N
Use controller with id N (default: 0), use --list-controller to
obtain a list of available controller.

-w, --wid N
Use wireless controller with wid N (default: 0).

--device-by-path BUS:DEV
Use the controller at BUS:DEV, do not do any automatic scanning.
Useful for cases when a controller isn't known by xboxdrv, but
supports one of the given protocols.

--device-by-id VENDOR:PRODUCT
Use device that matches VENDOR:PRODUCT (as returned by lsusb).
Useful for cases when a controller isn't known by xboxdrv, but
supports one of the given protocols.

--type TYPE
Ignore autodetection and enforce the controller type. Possible
values for TYPE:

• xbox

• xbox-mat

• xbox360

• xbox360-wireless

• xbox360-guitar

• firestorm

• firestorm-vsb

• saitek-p2500

• generic-usb

The generic-usb type is a special type that will work with any USB
controller, it will however not interpret the input it gets, but just
dump it to the console for development purposes. See --generic-usb-spec
for further information.

-d, --detach-kernel-driver
Detaches the kernel driver that is currently associated with the
given device. This is useful when you have the xpad module loaded
and want to use xboxdrv without unloading it.

--generic-usb-spec NAME=VALUE,...
Allows one to specify from which endpoint generic-usb will read.
The spec as the form of NAME=VALUE,.... Allowed values are:

vid=HEX
The vendor id of the controller to which this spec applies

pid=HEX
The product id of the controller to which this spec applies

if=NUM The interface from which GenericUSBController should be
read

ep=NUM The endpoint from which GenericUSBController should be read

EVDEV OPTION
--evdev DEVICE
Allows you to read input data from a regular event device. This
allows you to use xboxdrv on regular PC joysticks. The data that
is read from the event device is converted internally into a
XboxMsg object and then passed through the same configuration
pipeline as it would be for a regular Xbox360 controller. This
allows you to make use of all the regular configurability, but
limits you to the number of axis and buttons that an Xbox360
controller provides.

As a regular PC joystick will most likely already create a
/dev/input/jsX device by itself, you might need to get rid of that
so that a game will properly detect the joystick device created by
xboxdrv. The easiest way to accomplish that is to simply delete
the old joystick and rename the device that xboxdrv created to
/dev/input/js0. When you use udev, this operation should be
harmless and automatically reverse itself when you remove the
controller and plug it back in or when you reboot the computer.

--evdev-debug
The evdev event handler will print all received events to stdout,
this makes it easy to see which events a given controller sends.

--evdev-no-grab
By default the evdev driver will grab the device, thus making it
impossible for other applications to receive events from that
device. This is done to avoid confusing applications, as otherwise
an app would receive every event twice, once from the original
device and once from the virtual xboxdrv one. In some cases this
behaviour is undesired, such when mapping only an otherwise
unhandled subset of keys of an device, i.e. mapping the multimedia
keys on a keyboard, so this option turns the grab off.

--evdev-absmap ABSMAP,...
ABSMAP = EVDEV_ABS [ "+", "-" ] "=" XBOXAXIS ;

Sets how evdev events are mapped to Xbox axis events. An example
configuration would look like this:

--evdev-absmap ABS_X=x1,ABS_Y=y1,ABS_RZ=x2,ABS_THROTTLE=y2,ABS_HAT0X=dpad_x,ABS_HAT0Y=dpad_y

xboxdrv will output on startup a full list of event names that the
given event device supports and that can be used in place of
EVDEV_ABS.

It is also possible to map half-axis with a command like:

--evdev-absmap ABS_Y+=LT,ABS_Y-=RT

This will map the upward movement of the Y axis to the left
trigger and the downward movement to the right trigger.

--evdev-keymap KEYMAP
Sets how evdev events are mapped to Xbox controller events. An
example configuration would look like this:

--evdev-keymap BTN_TRIGGER=a,BTN_THUMB=b,BTN_THUMB2=x

xboxdrv will output on start a full list of event names that the
given event device supports.

STATUS OPTIONS
-l, --led NUM
Set LED status. Possible values for NUM are:

LED Status Codes
Num Behavior
0 off
1 all blinking
2 1/top-left blink, then on
3 2/top-right blink, then on
4 3/bottom-left blink, then
on
5 4/bottom-right blink, then
on
6 1/top-left on
7 2/top-right on
8 3/bottom-left on
9 4/bottom-right on
10 rotate
11 blink
12 blink slower
13 rotate with two lights
14 blink
15 blink once

--rumble-gain AMOUNT
You can change the rumble strength via:

$ xboxdrv --rumble-gain 50%

Values larger then 100% are possible as well and will amplify
small rumble commands, rumble commands already at the maximum will
stay unchanged.

-q, --quit
Exit xboxdrv after setting LED or rumble values.

CHATPAD OPTIONS (EXPERIMENTAL)
Chatpad support is still experimental. Basic keyboard usage will work,
there is however currently no support for customization or the green and
orange key modifiers.

Starting xboxdrv multiple times in a row with the --chatpad option can
crash the controller. Unplugging it and plugging it back in should reset
it.

--chatpad
Enables the support for the Xbox360 Chatpad. WARNING: This is
preliminary code, it will crash your gamepad when xboxdrv is
started multiple times and won't provide proper keymapping for any
of the umlauts and special characters.

--chatpad-no-init
This will start chatpad support with out sending the init
sequence, thus potentially avoiding crashing the controller if
xboxdrv is started multiple times.

--chatpad-debug
Output raw chatpad data to the stdout for debugging purpose.

HEADSET OPTIONS (EXPERIMENTAL, XBOX360 USB ONLY)
Xboxdrv does not support the headset, the options below are for
developers only and will dump raw headset data, not .wav files.

--headset
Enable headset support and dump incoming data to stdout.

--headset-dump FILE
Enable headset support and dump incoming data to FILE.

--headset-play FILE
Enable headset support and send FILE to the headset for playback.

FORCE FEEDBACK
--force-feedback
Enables the standard kernel force feedback interface. It is
disabled by default as it causes trouble with some applications
running in Wine.

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.

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.

When using xboxdrv in daemon mode with multiple controller slots
you have to enable force feedback for each slot separately.

--ff-device DEVICEID
Select to which virtual device the force-feedback callbacks will
be connected to, it defaults to joystick. Other allowed values are
mouse, keyboard and any integer number. See --ui-buttonmap for
further information on how device-ids work.

-R, --test-rumble
Pressing LT will move the left rumble motor and pressing RT will
move the right one. Rumble motor strength depends on how hard you
press. This is useful for testing the rumble motors.

-r, --rumble L,R
Set the speed for both rumble motors. Values from 0 to 255 are
accepted, the default is 0,0.

CONTROLLER SLOT OPTIONS
Controller slots are used when running xboxdrv in daemon mode. Each slot
represents a complete controller configuration. If you want to use
multiple controller in daemon mode you have to supply multiple controller
slots.

--controller-slot N
Switches to the controller slot with the number N, numbering
starts at zero.

--next-controller
Switches to the next controller slot.

--match RULE,...
Limits a controller slot to devices that match any one of the
given rules. Possible match rules are:

usbid=VENDOR:PRODUCT
Match controllers that have the given USB vendor and
product ids.

vendor=VENDOR
Match controllers that have the given USB idVendor.

product=PRODUCT
Match controllers that have the given USB idProduct.

property=PROPERTY:VALUE
Match against an arbitrary udev property, with name
PROPERTY and value VALUE.

usbpath=BUS:DEV
Match against the USB path given by BUS and DEV.

usbserial=SERIAL
Match against the USB iSerial number.

--match-group RULE,...
Limits a controller slot to devices that match all of the given
rules. Possible match rules are the same as for --match.

CONFIG SLOT OPTIONS
You can use multiple configurations, called config slots, with your
controller. You switch between those multiple configurations by pressing
the Guide button by default, but you can also set another button via the
option --toggle.

--config-slot NUM
Select the config slot NUM.

--next-config
Allows the creation of an alternative uinput configuration to
which one can toggle at runtime by pressing the ui-toggle button
(defaults to guide).

$ xboxdrv \
--mouse \
--next-config
--ui-axismap X1=ABS_X,Y1=ABS_Y \
--ui-buttonmap A=JS_0,B=JS_1

The above configuration would install mouse emulation as first
configuration and a simple joystick emulation as second
configuration. Allowing toggling between mouse emulation and
joystick handling by pressing the guide button.

Not that --next-config is currently limited to only configurations
done with --ui-buttonmap and --ui-axismap, autofire, throttle
emulation, deadzones and all other things can currently not be
switched at runtime.

--toggle XBOXBTN
Sets the button that will be used to toggle between different
different configurations. A value of 'void' will disable the
toggle button. If no toggle button is specified, the guide button
will be used to toggle between configurations.

CONFIGURATION OPTIONS
--modifier MOD
Add a modifier to the modifier stack, see [Modifier] for a full
list of possible modifier.

--timeout MSEC
Specify the number of milliseconds that xboxdrv will wait for
events from the controller before moving on and processing things
like auto-fire or relative-axis. Default value is 10, smaller
values will give you a higher resolution auto fire and relative
event movement, but will waste some more CPU.

-b, --buttonmap BUTTON=BUTTON,...
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 (aliases are in parenthesis):

Button Names
┌─────────────────────────────┬─────────────────────────────┐
│ Name │ Description │
├─────────────────────────────┼─────────────────────────────┤
│ start, back │ start, back buttons │
├─────────────────────────────┼─────────────────────────────┤
│ guide │ big X-button in the middle │
│ │ (Xbox360 only) │
├─────────────────────────────┼─────────────────────────────┤
│ a(1), b(2), x(3), y(4) │ face buttons │
├─────────────────────────────┼─────────────────────────────┤
│ black, white │ black, white buttons (Xbox1 │
│ │ only, mapped to lb, rb on │
│ │ Xbox360) │
├─────────────────────────────┼─────────────────────────────┤
│ lb(5), rb(6) │ shoulder buttons (Xbox360 │
│ │ only, mapped to black, │
│ │ white on Xbox1) │
├─────────────────────────────┼─────────────────────────────┤
│ lt(7), rt(8) │ analog trigger (needs │
│ │ --trigger-as-button option) │
├─────────────────────────────┼─────────────────────────────┤
│ tl, tr │ pressing the left or right │
│ │ analog stick │
├─────────────────────────────┼─────────────────────────────┤
│ du(up), dd(down), dl(left), │ dpad directions (needs │
│ dr(right) │ --dpad-as-button option) │
├─────────────────────────────┼─────────────────────────────┤
│ green, red, yellow, blue, │ guitar buttons │
│ orange │ │
└─────────────────────────────┴─────────────────────────────┘

Just like with --ui-buttonmap you can add button filter to each
button.

--axismap AXIS=MAPPING,...
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.

Just like with --ui-axismap you can add axis filter to each axis.

MODIFIER PRESET CONFIGURATION OPTIONS
The options in this sections are sortcuts for --modifier options. Unlike
--modifier they are not order depended, but have a predefined order that
is used no matter the order in which the options are given.

--autofire BUTTON=FREQUENCY,...
Autofire mapping allows you to let a button automatically fire
with a given frequency in milliseconds:

$ 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

--axis-sensitivty AXIS=SENSITIVITY,...
The sensitive of an axis can be adjusted via --axis-sensitivty:

$ xboxdrv --axis-sensitivty X1=-1.0,Y1=-1.0

A value of 0 gives you the default linear sensitivity, values
larger then 0 will give you higher sensitivity, while values
smaller then 0 will give you lower sensitivity. Sensitivity values
in the range of [-1, 1] will generally give good results,
everything beyond that won't be of much practical use.

Sensitivity works by applying:

t = 2 ** sensitivity;
pos = (1.0f - (1.0f - pos) ** t) ** (1 / t);

To the value of the axis, this means that both the minimum value
and the maximum value of the axis will always stay the same, just
the response inbetween changes.

For a complete freeform way to change the axis response see the
Response Curve Filter.

--calibration CALIBRATIONSPEC
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 AXIS=MIN:CENTER:MAX,...

Will cause the joystick device report maximum position when your
stick is only moved half the way.

--deadzone NUM
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%

--deadzone-trigger NUM
The left and right trigger have a separate deadzone value which
can be specified with:

$ xboxdrv --deadzone-trigger 15%

--dpad-rotation DEGREE
Allows you to rotate the dpad. DEGREE must be a multiple of 45.
This can be useful in isometric games where the playfield itself
is rotated, thus a:

xboxdrv --dpad-rotation 45

Will give you controls that are relative to your character instead
of your viewpoint.

--four-way-restrictor
The --four-way-restrictor option allows one to limit the movement
on both analogsticks to only four directions (up, down, left,
right), the diagonals (up/left, up/right, down/left, down/right)
are filtered out from the output. This option is useful for games
such as Tetris, that don't need diagonals and where you don't want
to accidentally trigger the down-move while trying to do a
left/right move.

--relative-axis AXIS=NUM,...
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 allows you to simulate
throttle control for flightsim games.

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

--square-axis
The Xbox360 gamepad, as most other current day gamepads, features
a circular movement 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 PC joysticks, which had a
square range and would report (1,1) when hold in the top/left
corner.

Some old games (i.e. mostly DOS stuff) require a square movement
range and will 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).

UINPUT PRESET CONFIGURATION OPTIONS
The following options are simple shortcuts for common configurations that
can be accomplished manually by using --ui-buttonmap and --ui-axismap.

--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
The DPad sends button instead of axis events.

--dpad-only
Both sticks are ignored, only the DPad sends out axis events.
Useful for games that might get confused by additional analog
axis. Combining this option with --trigger-as-button is recommend
in most situations.

--guitar
Sets a predefined button and axis mapping for use with guitar
controllers. This mainly gets rid of a few unnecessary buttons and
axis not used by a guitar controller.

-m, --mouse
Lets the controller act as a mouse. It is indendical to:

$ xboxdrv \
--dpad-as-button
--deadzone 4000
--trigger-as-zaxis
--axismap "-y2=y2,-trigger=trigger"
--ui-axismap "x1=REL_X:15:20,y1=REL_Y:15:20,y2=REL_WHEEL:5:100,x2=REL_HWHEEL:5:100,trigger=REL_WHEEL:5:100"
--ui-buttonmap "a=BTN_LEFT,b=BTN_RIGHT,x=BTN_MIDDLE,y=KEY_ENTER,rb=KEY_PAGEDOWN,lb=KEY_PAGEUP,"
--ui-buttonmap "dl=KEY_LEFT,dr=KEY_RIGHT,du=KEY_UP,dd=KEY_DOWN,"
--ui-buttonmap "start=KEY_FORWARD,back=KEY_BACK,guide=KEY_ESC,tl=void,tr=void"

You can customize it by the usual means, just make sure that
--mouse comes before your customization options on the command
line.

Note that if you have your mouse buttons switched you must adjust
the above to match your mouse configuration or the button events
will come out wrong.

--mimic-xpad
Causes xboxdrv to use the same axis and button names as the xpad
kernel driver for wired Xbox360 controller

--mimic-xpad-wireless
Causes xboxdrv to use the same axis and button names as the xpad
kernel driver for wired Xbox360 controller

UINPUT CONFIGURATION OPTIONS
--no-uinput
Do not to start UInput, instead simply read events from the
controller, useful for debugging.

--no-extra-devices
By default xboxdrv will allocate multiple uinput devices and sort
events to each of them. Thus mouse related events like BTN_LEFT or
REL_X will go to a virtual mouse device, while ABS_X events would
go to a virtual joystick device and KEY_ESC would go to a virtual
keyboard device.

This option disables that automatism and all events will go to the
same virtual device.

Manual assignment to a specific device (i.e. KEY_ESC@keyboard,
BTN_A@joystick, ...) is still possible.

--no-extra-events
By default xboxdrv will allocate multiple uinput devices and sort
events to each of them. Thus mouse related events like BTN_LEFT or
REL_X will go to a virtual mouse device, while ABS_X events would
go to a virtual joystick device and KEY_ESC would go to a virtual
keyboard device.

To make sure sure that a mouse, keyboard or joystick device is
properly detected by Xorg, the kernel or libraries such SDL
xboxdrv will insert extra dummy events. For example a mouse device
needs REL_X and REL_Y events to be detected as such, but a
configuration that only wants to emulate the mouse buttons won't
provide those, thus xboxdrv will add them automatically. The
--no-extra-events option will switch this behaviour off.

--device-name NAME
Changes the descriptive name the device will have. This options
acts the same as --device-names CURRENTSLOT.auto=NAME

--device-names TYPE.SLOT=NAME,...
Changes the descriptive name the device will have. TYPE is one of
mouse, keyboard, joystick, auto or a number. SLOT is a slot number
or auto. The auto name acts as wild card and matches everything.

--device-usbid VENDOR:PRODUCT:VERSION:BUS
Changes the vendor, product, version and bus id that the device
will have. The last two arguments are optional. This options acts
the same as --device-usbids
CURRENTSLOT.auto=VENDOR:PRODUCT:VERSION:BUS

--device-usbids TYPE.SLOT=VENDOR:PRODUCT:VERSION:BUS,...
Changes the vendor, product, version and bus id the device will
have. TYPE is one of mouse, keyboard, joystick, auto or a number.
SLOT is a slot number or auto. The auto name acts as wild card
and matches everything.

--ui-clear
Removes all uinput mappings and will leave the driver in a blank
state and only map those things you added yourself. If you only
want to get rid of individual buttons you can use the 'void'
event.

--ui-buttonmap UIBUTTONSPEC,...
UIBUTTONSPEC = XBOXBUTTON [ "+" XBOXBUTTON ] [ "ˆ" FILTER ] ... "=" ( RELSPEC | BTNSPEC | EXECSPEC ) ;
RELSPEC = [ DEVICEID "-" ] "REL_" [ ":" [ VALUE ] [ ":" REPEAT ] ] ;
BTNSPEC = [ DEVICEID "-" ] ( ( "BTN_" NAME ) | ( "KEY_" NAME ) ) { "+" BTNSPEC } ;
EXECSPEC = PROGRAM { ":" ARGUMENT } ;
XBOXBUTTON = "a" | "b" | "x" | "y" | "lb" | "rb" | "lt" | "rt" |
"tl" | "tr" | "start" | "select" | "back" | "guide" | "black" | "white" ;
FILTER = "toggle" | "invert" | "autofire" [ ":" RATE ] [ ":" DELAY ] | log [ ":" STRING ] ;
NAME = STRING ;
VALUE = NUMBER ;
REPEAT = NUMBER ;
DEVICEID = NUMBER ;

Allows you to change the event code that is send to the kernel for
buttons. The usage is similar to the normal button mapping, 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.

If the right hand side is left empty all the supplied filters will
be added to the already existing button binding instead of a new
one.

Aside from the named keys, you can also give the input code
directly as number via the syntax KEY_#NUM.

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 mangled 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 valid X11 keysyms can be optained with
--help-x11keysym.

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.

You can also map a button to a REL_ event. In that case you can
supply additional paramaters in the form of:

$ xboxdrv --ui-buttonmap X=REL_???:VALUE:REPEAT

VALUE gives the value of the event (default: 10)

REPEAT gives the number of millisecond to pass before the event is
fired again (default: 5)

The special 'void' event allows you to clear any existing bindings
for a given button, which can be useful in cases when a game only
supports a limited number of buttons.

You can also prepend a device_id to the UIBUTTONSPEC which allows
you to create multiple uinput devices. By default 'auto' is
assumed as device_id which automatically try to do the right
thing, sending keyboard events to a keyboard device and mouse
events to a mouse device. Other possible values are 'mouse' and
'keyboard'. A device_id of '0' refers to the first joystick
device, values larger then 0 to the second, third, etc.

Note that the 'mouse' and 'keyboard' device_id names do not give
you a mouse or keyboard device, these are just symbolic names for
the devices into which xboxdrv will sort events that look like a
mouse or keyboard event. The final determination of which device
gets handled as what will be done by the Kernel or Xorg depending
on what events a device provides.

An example configuration making use of device_id would look like
this:

xboxdrv -s \
--ui-clear \
--ui-buttonmap A=JS_0@0,B=JS_1@0 --ui-axismap X2=ABS_X@0,Y2=ABS_Y@0
--ui-buttonmap X=JS_0@0,Y=1-JS_1@0 --ui-axismap X2=ABS_X@1,Y2=ABS_Y@1

In this example the left stick creates a joystick device and the
right stick creates a separate joystick device.

When using multiple controller slots you can additionally append
the slot id and thus assign events across controller slot
boundaries. The syntax for that is:

BTN_A@{deviceid}.{slotid}

Instead of giving just a single button, it is also possible to
give two buttons to --ui-buttonmap to allow shifting:

xboxdrv -s \
--ui-clear \
--ui-buttonmap A=JS_0,B=JS_1,LB+A=JS_2,LB+B=JS_3

In this example LB acts as shift button, if A is pressed without
LB it will send out a JS_0 event, but if LB is pressed it will
send a JS_2 event instead. This allows you to multiply the number
of available buttons on the controller.

See the section KEYBOARD EMULATION below on how to resolve issues
with Xorg not detecting the virtual keyboard that xboxdrv creates.

You can also apply filters to button events:

xboxdrv -s \
--ui-buttonmap Aˆtoggle=JS_0

For documentation on the filters you can apply to events see
[Button Filter].

--ui-axismap UIAXISSPEC,...
UIAXISSPEC = [ XBOXBTN "+" ] XBOXAXIS { "ˆ" FILTER } "=" ( RELSPEC | RELREP | KEYSPEC | ABSSPEC ) ;
KEYSPEC = [ "key:" ] "KEY_" NAME ":" "KEY_" NAME ":" THRESHOLD ;
RELSPEC = [ "rel:" ] "REL_" NAME ":" VALUE ":" REPEAT ;
RELREP = "rel-repeat:" "REL_" NAME ":" VALUE ":" REPEAT ;
ABSSPEC = [ "abs:" ] "ABS_" NAME ;
FILTER = ( "calibration" | "cal" ) ":" MIN ":" CENTER ":" MAX |
( "sensitifity" | "sen" ) ":" SENSITIFITY |
( "deadzone" | "dead" ) ":" MIN ":" MAX ":" SMOOTH |
( "relative" | "rel" ) ":" SPEED |
( "responsecurve" | "response" | "resp" ) { ":" VALUE }
XBOXBTN = "a" | "b" | "x" | "y" | "start" | "back" | "guide" | "lb" | "rb" | ...
XBOXAXIS = "x1" | "y1" | "x2" | "y2" | "z" | "lt" | "rt" | "dpad_x" | "dpad_y" ;
VALUE = NUMBER ;
REPEAT = NUMBER ;
THRESHOLD = NUMBER ;
NAME = STRING ;

Similar to --ui-buttonmap this option allows you to change the
event code that is send to the kernel for axes. The events that
are available are the same as for --ui-buttonmap.

$ xboxdrv --ui-axismap X1=REL_???:VALUE:REPEAT

VALUE gives the maximum value of the event, the actual value that
gets send is VALUE * axis_state. (default: 10)

REPEAT gives the number of millisecond to pass before the event is
fired again (default: 5).

The value of -1 has a special meaning, it will result in the REL
event being fired as soon as possible (i.e. every timeout
milliseconds). This is the recomment way for handling mouse
emulation, as it will keep REL events syncronized and thus avoid
jaggies in the movement, that will result from manually specifying
a timeout.

$ xboxdrv --ui-axismap X1=KEY_UP:KEY_DOWN:THRESHOLD

KEY_UP gives the keycode to be send when the axis is moved up

KEY_DOWN gives the keycode to be send when the axis is moved down

THRESHOLD gives the threshold that triggers the sending of an
event

Just like --ui-buttonmap, you can also use shift keys in place of
the XBOXAXIS:

$ xboxdrv --ui-axismap X1=ABS_X,LB+X1=ABS_RX

This allows you to send ABS_X events normally and ABS_RX events
when the LB button is held down.

For information on how to use axis filters, see [Axis Filter].

INPUT EVENT HANDLER
Input event handler decide what comes out of the virtual input devices
that xboxdrv creates. They for example decide that when button A is
pressed on a gamepad, that a virtual keyboard will emit a press of the
space key.

Furthermore input event handler can also perform some basic
transformation of the input signals, thus a joystick can be used to send
WASD keys.

BUTTON EVENT HANDLER
A button event handler decides what happens when a button is pressed, it
needs to be specified with the --ui-buttonmap option. The example below
shows the simplest use case:

$ xboxdrv --ui-buttonmap A=key:KEY_A

Here key is the name of the button event handler, while KEY_A is an
argument for the event handler. What kind of arguments an event handler
allows depends on the event handler.

There is also a shorthand form of specifying event handlers by just
writing:

$ xboxdrv --ui-buttonmap A=KEY_A

Here no handler is specified explicitly, if that is the case, the
appropriate handler will be guessed based on the event type. EV_KEY
events will be handled by the key handler, EV_REL by the rel handler and
EV_ABS by the abs handler.

key:KEY_EVENT, key:KEY_EVENT:KEY_EVENT:HOLD_THRESHOLD_MSEC
The key handler is the most basic one, it maps a button directly
to a virtual key or another button.

If additional arguments are supplied the button will be able to
send out two different events. The first event specified will be
send when the button is clicked normally, while the second event
will be send in case the button is hold down for the time
specified in HOLD_THRESHOLD_MSEC.

An example for the hold button would look like:

xboxdrv \
--ui-buttonmap A=JS_0:JS_1:500

This will send JS_0 events when the button is pressed and switch
to JS_1 events when the button was hold for 500 milliseconds.

The hold button feature is useful to effectively double the number
of available buttons, thus the dpad can for example be used to
send out eight different button events instead of just four, which
is enough to handle weapons in most FPS games.

abs not yet implemented

rel:REL_EVENT:VALUE:REPEAT
The rel handler will send out a REL event whenever the button is
pressed. VALUE gives the value of the event that will be send,
while REPEAT gives the number of milliseconds till the event will
be send again.

A typical use for REL events is emulation of the scroll wheel of a
mouse, an example configuration would be:

xboxdrv \
--ui-buttonmap Y=rel:REL_WHEEL:1:500,A=rel:REL_WHEEL:-1:500

Here Y will scroll up and A will scroll down.

cycle-key:KEY_EVENT:...
The cycle-key handler will switch the KEY_EVENT that gets send
with each button press. This is useful in situations where a range
of buttons should be mapped to a single key. For example a FPS
might have weapons mapped from 1 to 6, but only a single key on
the gamepad is free, thus one could write:

xboxdrv \
--ui-buttonmap A=cycle-key:KEY_1:KEY_2:KEY_3:KEY_4:KEY_5:KEY_6

cycle-key-named:NAME:KEY_EVENT:...
The cycle-key-named handler works exactly like the cycle-key
handler, except that a name has to be supplied for the cycle
sequence. The name of the sequence is used by cycle-key-ref to
access the sequence and reuse it for another button.

In this simple example A is used to toggle through all weapon keys
forward, while B is used to toggle the keys backwards:

xboxdrv \
--ui-buttonmap A=cycle-key-named:weapons:KEY_1:KEY_2:KEY_3:KEY_4,B=cycle-key-ref:weapons

cycle-key-ref:NAME:DIRECTION, sequence-key-ref:NAME:DIRECTION
The cycle-key-ref handler will access and reuse the named cycle
keysequence given by NAME. If DIRECTION can either be 'forward'
or 'backward', if no direction is supplied it will default to
'backward'.

See cycle-key-named for a full example.

sequence-key-named:NAME:KEY_EVENT:...
The sequence-key-named works exactly the same as the
cycle-key-named, with the only difference being that the
sequence-key-named will not wrap around when reaching the
beginning or end of the sequence.

This behaviour is useful in flight simulations or other games
where thrusters might be controllered by numeric keys and it
wouldn't make much sense to jump from zero to full thrust in one
go.

To move backwards through the sequence another key must be bound
to sequence-key-ref.

exec The exec button handler allows one to launch an application when
the button was pressed. An example would look like this:

xboxdrv \
--ui-buttonmap A=exec:/home/juser/local/bin/screenshot.sh

Possible uses for the button are the ability to do screenshots or
perform other tasks that are outside the main application you are
using xboxdrv with.

macro A button can be bound to a macro via:

xboxdrv \
--ui-buttonmap A=macro:/home/juser/.xboxdrv/somefile.macro

The .macro file has the form of:

send KEY_LEFTSHIFT 1
wait 500
send KEY_LEFTSHIFT 0

All abs, rel and key events can be send from a macro file.

AXIS EVENT HANDLER
Axis event handler decide what happens when an axis is moved. Like
button event handler they come in different forms and like button event
handler they provide a shortcut form. EV_KEY events will be handled by
the key handler, EV_REL by the rel handler and EV_ABS by the abs handler.

abs:ABS_EVENT
The abs handler is the simplest of them all, it will simply send
out the value it gets as input as the given ABS_EVENT event to the
kernel. Thus a basic configuration to make the left stick behave
as joystick would look like this:

xboxdrv \
--ui-axismap X1=abs:ABS_X,Y1=abs:ABS_Y

key:KEY_UP:KEY_DOWN:THRESHOLD
KEY_UP gives the keycode to be send when the axis is moved up

KEY_DOWN gives the keycode to be send when the axis is moved down

THRESHOLD gives the threshold that triggers the sending of an
event

Just like --ui-buttonmap, you can also use shift keys in place of
the XBOXAXIS:

$ xboxdrv --ui-axismap X1=ABS_X,LB+X1=ABS_RX

This allows you to send ABS_X events normally and ABS_RX events
when the LB button is held down.

rel:REL_EVENT:VALUE:REPEAT
VALUE gives the maximum value of the event, the actual value that
gets send is VALUE * axis_state. (default: 10)

REPEAT gives the number of millisecond to pass before the event is
fired again (default: 5).

The rel handler is mainly useful for mouse pointer emulation, if
you want to emulate a mouse scroll wheel use the rel-repeat
handler instead.

rel-repeat:REL_EVENT:VALUE:REPEAT
The rel-repeat handler is similar to the rel handler, but
optimized for emulating the scroll wheel of a mouse.

VALUE isn't scaled to how far the axis has moved, instead it is
constant, instead the time given in REPEAT is scaled according to
the axis movement. Thus the further the stick is moved, the more
events will be send.

The need for both rel-repeat and rel arises from the fact that
Xorg converts scroll wheel movement to button presses before they
are handed to an application, thus an application never properly
sees the changes in VALUE, by scaling REPEAT instead that problem
is worked around.

INPUT FILTER
Input filters allow one to manipulate the events that come from the
controller. They can be used on --buttonmap, --axismap, --ui-buttonmap
and --ui-axismap. The difference between the two is that the --ui-...
versions applies to the uinput events, while the other version applies to
Xbox360 controller events.

BUTTON FILTER
tog, toggle
The toggle filter will turn the button into a toggle button,
clicking the button will set it to pressed state and pressing it
again will unpress it. Useful for games where you might want to
permanently run or duck without holding the button pressed.

inv, invert
The invert filter will keep the button in pressed state when it is
not pressed and in unpressed state when it is pressed.

auto, autofire:RATE:DELAY
The autofire filter allows one to repeatedly send button press
events when the button is held down. It takes two optional
parameters:

RATE is the number of milliseconds between button press events.

DELAY the amount of milliseconds till the autofire will start,
before that delay the button will act as normal.

click-press
The click-press filter will transmit a single button click when
the button is pressed.

click-release
The click-release filter will transmit a single button click when
the button is released.

click-both
The click-both filter will transmit a single button click when the
button is pressed and another one when it is released.

const:VALUE
The const filter will ignore the input signal and send a constant
value to the output. This can be used for example in combination
with multiple configurations to signal a game or another
application which configuration is currently active.

delay:TIME
A button has to be held down for TIME milliseconds before it will
emit an event, press events shorter then that will be ignored.

log:STRING
The log filter will output everything to stdout that goes through
it to, this is useful for debugging the filter. A STRING can be
provided as parameter that will be outputed before the event.

AXIS FILTER
cal, calibration:MIN:CENTER:MAX
See --calibration.

sen, sensitivity:SENSITIVITY
See --axis-sensitivity.

dead, deadzone:VALUE, deadzone:MIN:CENTER:MAX
Deadzone filter applies a deadzone to the current axis. If only
MIN is provided, the parameter will be interpreted as -MIN:MIN:1.
If the argument is 1, smooth filtering will be applied so that the
end of the deadzone is 0. Setting the argument to 0 will apply a
simple cut-off filter, where all events smaller then the threshold
are ignored.

rel, relative:SPEED
See --relative-axis.

resp, response:VALUES:...
The response curve filter allows you to completely change the way
an axis reacts. The filter takes a list of VALUES that are then
linearly interpolated and spread across the full range of the
axis. An example would look like this:

xboxdrv \
--ui-axismap x1ˆresp:-32768:-4000:0:4000:32767

Here the X1 axis is manipulated so that it will have a lower
sensitivity in the center and a higher one on the outside.

MODIFIER
While button and axis filter only apply to a single axis or button at a
time, modifiers apply to the complete controller at once and can thus be
used to perform modifications that require input from multiple axis or
buttons. Most of the modifiers explained below replicate functionality
provided by regular options, but allow more fine tuning, such as limiting
the effects to a single analog stick instead of just applyig it to all.
Note that modifiers are applied one after the other, so order is
important.

dpad-rotate=DEGREE
See --dpad-rotation.

dpad-restrictor=RESTRICTON
Restricts the dpad movement, values for RESTRICTON can be:

x-axis: only allow movement in the X axis

y-axis: only allow movement in the Y axis

fourway: allow movement in X and Y axis, but filter out diagonals

4wayrest, four-way-restrictor=XAXIS:YAXIS
See --four-way-restrictor.

square, square-axis=XAXIS:YAXIS
See --square-axis.

rotate=XAXIS:YAXIS:DEGREE:MIRROR
Rotates the stick given by XAXIS and YAXIS by DEGREE and
optionally MIRRORS it.

stat, statistic
The statistic modifier doesn't actually modify anything, instead
it collects statistics on the controller, such as how many times a
button has been pressed. The results of the collections will be
displayed on shutdown of xboxdrv.

Note that the stat modifier is part of the modifier stack, thus to
get correct results you must make sure that it comes first in the
stack when it should work on real events and not be confused by
auto-fire or similar modifications.

RUNNING XBOXDRV
USING A SINGLE CONTROLLER
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.conf:

blacklist xpad

Next you have to load the uinput kernel module which allows userspace
programs to create virtual input devices and the joydev module handles
the /dev/input/jsX devices:

$ 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 necessary 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.

By default xboxdrv will echo all controller events to the console, this
makes it easy to see if things are properly working, but will eat a lot
of CPU, thus it is strongly recomment to disabled that output with the
--silent option.

The trigger buttons are handled by xboxdrv normally as axis, giving you
analog feedback, while this reproduces the Xbox360 controller the most
accurately, it will confuse many and only be useful in a few, racing
games mainly. So in the majority of cases it is recomment to change the
triggers to regular buttons via:

$ xboxdrv --trigger-as-button

USING MULTIPLE CONTROLLER
If you want to use multiple wired controllers you need to start multiple
instances of the xboxdrv driver and append the -i argument to select the
appropriate controller 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 option like this:

$ xboxdrv --wid 1

You have to sync the wireless controller as usual.

To see a list of all the controllers that xboxdrv detects being connected
to your system use:

$ xboxdrv --list-controller

HOTPLUGGING AND XBOXDRV DAEMON
To allow hotplugging of gamepads xboxdrv has to be run in daemon mode.
This is accomplished with the --daemon option:

$ xboxdrv --daemon

When launched in daemon mode xboxdrv will listen to udev events and thus
be notified whenever a new USB device gets plugged into the computer. It
will then match that device against its list of supported devices and
launch a separate thread to handle that gamepad.

Note that xboxdrv will not allow an arbitrary large number of controllers
to be used in that mode, it can only handle as many controllers as you
have allocated controller slots at startup. New slots can be allocated
with --next-controller and by default one slot is always allocated, thus
to support three controller you would run it with:

$ xboxdrv --daemon --next-controller --next-controller

Each controller slot can be configured individually and you can limit
which gamepad gets assigned to which slot with the --match option.

Note that xboxdrv will create the virtual uinput devices on startup, not
when a gamepad gets plugged in, this allows one to plug in gamepads even
after a game or an application like XBMC has already been launched and
still have it all function properly.

In daemon mode xboxdrv can be detached from the current shell via
--detach, to get a handle on it to kill it you can write its pid via the
--pid-file:

$ sudo xboxdrv --daemon --detach --pid-file /var/run/xboxdrv.pid

XBOXDRV DAEMON DBUS INTERFACE
When Xboxdrv is run as daemon it will export some API functions via D-
Bus, thus allowing to make configuration changes at runtime. The D-Bus
interface can be accessed either by the numerous language bindings
provided or via the generic command line tool dbus-send or by the more
userfriendly xboxdrvctl tool. Examples below are given for the raw dbus-
send.

Introspection is provided via the usual means:

dbus-send --session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv org.freedesktop.DBus.Introspectable.Introspect

dbus-send --session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv/ControllerSlots/0 org.freedesktop.DBus.Introspectable.Introspect

dbus-send --session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv/Daemon org.freedesktop.DBus.Introspectable.Introspect

Status information on available slots, configuration and active
controllers can be obtained via:

dbus-send \
--session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv/Daemon org.seul.Xboxdrv.Daemon.Status

Setting the LED on controller 0 can be done via:

dbus-send --session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv/ControllerSlots/0 org.seul.Xboxdrv.Controller.SetLed int32:4

Setting the rumble motors on controller 0 can be done via:

dbus-send --session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv/ControllerSlots/0 org.seul.Xboxdrv.Controller.SetRumble int32:255 int32:255

Setting a specific controller slot configuration, just as --toggle BTN
allows, can be done with:

dbus-send --session --type=method_call --print-reply \
--dest=org.seul.Xboxdrv /org/seul/Xboxdrv/ControllerSlots/0 org.seul.Xboxdrv.Controller.SetConfig int32:2

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 familiar 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 or as part of your
distribution in the package evtest. 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 joystick.

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.

It is currently available via:

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

Or from the same Ubuntu PPA that also contains xboxdrv in the package
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 AND JSCALIBRATOR
Both of these tools lets you calibrate your gamepad, however with pretty
much all current gamepads this is no longer needed and actually harmful
as it might overwrite a perfectly good working configuration with a
broken one (unplugging the gamepad or a reboot will fix that). So avoid
them unless you clearly understand the issues of using them.

If your gamepad produces incorrect data and you do want to calibrate it
you might want to check out the option --calibration, which lets you
tweak the way xboxdrv interprets your gamepad data.

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.

EXAMPLES
The configurations below are just a few random examples, further examples
can be found in the examples/ directory of the xboxdrv source tree or in
/usr/share/doc/xboxdrv/examples/.

TURNING TRIGGERS INTO BUTTONS
By default xboxdrv will handle the trigger as analog axis, not buttons,
while this is beneficial for racing games, it will confuse many other
games, thus xboxdrv provides an easy way to change the handling into
buttons via the --trigger-as-button option:

$ xboxdrv --trigger-as-button

CONFIGURE A DEADZONE
Many gamepads don't center exactly at zero, but at random values around
it. This 'noise' can confuse some games and is thus be best filtered out,
this can be accomplished with:

$ xboxdrv --deadzone 25%

The percentance is the amount of noise that will get filtered out, you
can also give raw device values if you leave out the % sign. If you want
to have a deadzone only on a specific axis you have to use axis filter:

$ xboxdrv --buttonmap X1ˆdeadzone:15000

KEYBOARD EMULATION
The following configuration will cause xboxdrv to emulate a keyboard,
which can be useful for games that are played with keyboard, like Flash
games or games that don't support a joystick. Since different games use
different keyboard keys you might have to adjust the keybindings to fit
the game:

$ xboxdrv \
--ui-clear \
--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

FIGHTING GAMES:
In this configuration the left and right trigger get turned into digital
buttons. All axis except the dpad are ignored. RB and RT are mapped to
act as if buttons 1,2 and 3 are pressed simultaniously which is useful
for some special attacks. Instead of using the native button names, the
1,2,3,... aliases are used, which makes things a little easier to read:

$ xboxdrv \
--dpad-only \
--trigger-as-button \
--buttonmap lb=1,x=2,y=3,lt=4,a=5,b=6 \
--buttonmap rb=1,rb=2,rb=3 \
--buttonmap rt=4,rt=5,rt=6

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. Using --modifier to install a four-way restrictor might also be
worth a consideration to not accidentally touch the throttle when the
rudder is moved.

USING MOUSE EMULATION AND JOYSTICK AT THE SAME TIME
To use mouse emulation and joystick at the same time you have to register
two configuration with xboxdrv, this works via:

$ xboxdrv --next-config --mouse

The --next-config option will open up a second configuration and all
configuration options on the right side of it will go there, while
everything on the left side of it will go into the first configuration.
Toggling between the configurations works with the guide button, you can
have as many configuratios as you want.

MAPPING EVERY BUTTON MULTIPLE
Some games might require more buttons then your gamepad has, in those
situation it can be useful to map a button twice by using shifted
buttons:

$ xboxdrv \
--ui-clear \
--ui-axismap X1=ABS_X,Y1=ABS_Y \
--ui-buttonmap a=JS_0,b=JS_1,x=JS_2,y=JS_3 \
--ui-buttonmap lb+a=JS_4,lb+b=JS_5,lb+x=JS_6,lb+y=JS_7 \
--ui-buttonmap rb+a=JS_8,rb+b=JS_9,rb+x=JS_10,rb+y=JS_11
.fi

Here all face buttons are get mapped three times, once when
pressed normally, once when pressed while LB is held down and
once when RB is held down, thus given you for the six buttons
12 virtual ones.

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

WRITING START-UP SCRIPTS FOR GAMES
When you want full game specific configurability and automatic launching
of xboxdrv, it is easiest to write little startup scripts for your games
that will launch xboxdrv, launch your game and then when the game is
finished tear down xboxdrv:

#!/bin/sh

exec xboxdrv \
--trigger-as-button -s \
-- \
your_favorite_game

# EOF #

Here your_favorite_game is the executable of your game and is passed to
xboxdrv as last argument. This will cause xboxdrv to start the game and
keep running as long as the game is running, when the game is done,
xboxdrv will quit automatically.

If you want to pass parameters to the game you have to add a --
separator, as otherwise your options to the game would be eaten up by
xboxdrv.

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

You might also need in addition use this (depends on the way SDL was
compiled):

$ SDL_JOYSTICK_DEVICE="/dev/input/js0"
$ export SDL_JOYSTICK_DEVICE

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.

SDL_JOYSTICK_DEVICE
Joystick device to use in the linux joystick driver, in addition to the
usual: /dev/js*, /dev/input/event*, /dev/input/js*

TROUBLESHOOTING
"NO XBOX OR XBOX360 CONTROLLER FOUND"
This means that either your controller isn't plugged in or is 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 this array in src/xpad_device.cpp:

XPadDevice xpad_devices[] = { ... }

If you have success with that, send a patch to <grumbel@gmail.com>, 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.

"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@gmail.com> and include the output of:

$ lsusb -v

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

"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

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 receives a
connection after you sync the controller.

KEYBOARD EMULATION
When you try to let xboxdrv send a keyboard events via --ui-buttonmap or
--ui-axismap Xorg must register the device 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.

WACOM ISSUES
In some older 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.

In newer kernels this issue is fixed.

UINPUT ISSUES
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 ISSUES
When using the Xbox360 gamepad in Wine it is not specially handled as
Xbox360 gamepad, but as generic DirectInput gamepad. This means games
will not display the proper button labels, but just numbers (i.e. 'Btn1'
instead of 'A' for example). Aside from that it should work fine.

XInput support (the Microsoft DirectInput replacment, not the Xorg
xinput) is as of January 2011 not implemented in Wine, so games that
require XInput and don't have an DirectInput fallback will not work with
a Xbox360 controller, unofficial patches however do exist.

XORG ISSUES
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.

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

TEMPORARY WORKAROUND USING XINPUT
Second workaround works with xinput:

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

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:

PERMANENT WORKAROUND BY DISABLING DEVICE AUTO DETECTION
A fourth workaround involved disabling the autodetection of Xorg
completely, 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 keyboards 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.

FORCE FEEDBACK PROGRAMMING
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.

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

BUGS
X11 KEYSYM ISSUES
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

Newer versions of Xorg will also do perform some auto configuration that
might lead to your keymap being switched whenever a new keyboard is
detected, in cases of custom Xmodmaps this might confuse xboxdrv and make
the XK_ style names unusable. No workaround for that is known right now.

NON-INTERRUPTABLE PROCESSES DUE TO FORCE FEEDBACK
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 like it might be a kernel issue and not a
xboxdrv one.

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

QUESTIONS, BUG REPORTS AND FEATURE REQUESTS
Bug reports and feature request can be report to the xboxdrv issue
tracker at:

⟨https://github.com/Grumbel/xboxdrv/issues/new⟩

General questions and requests for configuration help should be directed
to the xboxdrv mailing list at:

⟨http://groups.google.com/group/xboxdrv⟩

COPYRIGHT
Copyright © 2010-2011 Ingo Ruhnke <grumbel@gmail.com> License GPLv3+: GNU
GPL version 3 or later ⟨http://gnu.org/licenses/gpl.html⟩ . This is free
software: you are free to change and redistribute it. There is NO
WARRANTY, to the extent permitted by law.

SEE ALSO
xboxdrvctl(1), evtest(1), jstest(1), jstest-gtk(1), xev(1), fftest(1),
lsusb(1)

0.8.3 2011-07-20 xboxdrv (1)