xboxdrv (1) | User Commands | xboxdrv (1) |
xboxdrv - A Xbox/Xbox360 gamepad driver that works in userspace
xboxdrv
[OPTION]... [--] [COMMAND] [ARGUMENTS]
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.
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.
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 #
To load multiple configuration options use:
xboxdrv --config first.ini --alt-config second.ini --alt-config third.ini
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.
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.
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.
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 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.
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 |
$ 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.
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.
Xboxdrv does not support the headset, the options below are for developers only and will dump raw headset data, not .wav files.
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.
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.
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.
$ 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.
$ 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), dr(right) | dpad directions (needs --dpad-as-button option) |
green, red, yellow, blue, orange | guitar buttons |
Just like with --ui-buttonmap you can add button filter to each button.
$ 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.
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.
$ 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
$ 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.
$ 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.
$ xboxdrv --deadzone 4000
A value of 4000 works quite well for most games.
You can also give the deadzone in percentage:
$ xboxdrv --deadzone 15%
$ xboxdrv --deadzone-trigger 15%
xboxdrv --dpad-rotation 45
Will give you controls that are relative to your character instead of your viewpoint.
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
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).
The following options are simple shortcuts for common configurations that can be accomplished manually by using --ui-buttonmap and --ui-axismap.
$ 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.
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.
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.
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].
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 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.
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.
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.
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.
xboxdrv \
--ui-buttonmap A=cycle-key:KEY_1:KEY_2:KEY_3:KEY_4:KEY_5:KEY_6
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
See cycle-key-named for a full example.
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.
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.
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 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.
xboxdrv \
--ui-axismap X1=abs:ABS_X,Y1=abs:ABS_Y
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.
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.
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.
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 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.
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.
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.
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.
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
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.
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
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
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
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
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 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 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 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 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
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.
No tools for testing the output on /dev/input/mouseX are known.
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.
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/.
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
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
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
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
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.
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.
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.
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
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
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.
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:
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.
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.
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
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.
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.
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.
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"
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.
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.
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
Second workaround works with xinput:
$ xinput list $ xinput set-int-prop $DEVICEID 'Device Enabled' 32 0
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>
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.
For documentation on the FF interface see:
Additional, non Linux related, force feedback related information can be found at:
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.
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.
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.
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 © 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.
xboxdrvctl(1), evtest(1), jstest(1), jstest-gtk(1), xev(1), fftest(1), lsusb(1)
2011-07-20 | 0.8.3 |