other versions
- wheezy 0.8.4-1
- wheezy-backports 0.8.5-1~bpo70+1
- jessie 0.8.5-1+b1
- testing 0.8.8-1
- unstable 0.8.8-1
xboxdrv (1) | User Commands | xboxdrv (1) |
NAME¶
xboxdrv - A Xbox/Xbox360 gamepad driver that works in userspaceSYNOPSIS¶
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.
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.
[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.
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.
xboxdrv --daemon \ # config options for the first controller --next-controller \ # config options for the second controller --next-controller # config options for the third controller
- --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
- -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.
- --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 ;
--evdev-absmap ABS_X=x1,ABS_Y=y1,ABS_RZ=x2,ABS_THROTTLE=y2,ABS_HAT0X=dpad_x,ABS_HAT0Y=dpad_y
--evdev-absmap ABS_Y+=LT,ABS_Y-=RT
- --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
STATUS OPTIONS¶
- -l, --led NUM
- Set LED status. Possible values for NUM are:
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%
- -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.
- --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
- --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 miliseconds 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
$ xboxdrv --buttonmap B=A,X=A,Y=A
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
- --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
$ xboxdrv --axismap X2=X1,Y2=Y1,X1=X2,Y1=Y2
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 miliseconds:
$ xboxdrv --autofire A=250
$ 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
t = 2 ** sensitivity; pos = (1.0f - (1.0f - pos) ** t) ** (1 / t);
- --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
xboxdrv --calibration AXIS=MIN:CENTER:MAX,...
- --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
$ 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
- --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 accidently 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.
$ 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.
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"
- --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.
- --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.
- --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 ;
$ xboxdrv --ui-clear --ui-buttonmap A=JS_0,B=JS_1
$ xboxdrv --ui-buttonmap X=REL_???:VALUE:REPEAT
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
BTN_A@{deviceid}.{slotid}
xboxdrv -s \ --ui-clear \ --ui-buttonmap A=JS_0,B=JS_1,LB+A=JS_2,LB+B=JS_3
xboxdrv -s \ --ui-buttonmap A^toggle=JS_0
- --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 ;
$ xboxdrv --ui-axismap X1=REL_???:VALUE:REPEAT
$ xboxdrv --ui-axismap X1=KEY_UP:KEY_DOWN:THRESHOLD
$ xboxdrv --ui-axismap X1=ABS_X,LB+X1=ABS_RX
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_AHere 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_AHere 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.
xboxdrv \ --ui-buttonmap A=JS_0:JS_1:500
- 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 miliseconds till the event
will be send again.
xboxdrv \ --ui-buttonmap Y=rel:REL_WHEEL:1:500,A=rel:REL_WHEEL:-1:500
- 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.
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'.
- 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.
- 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
- macro
- A button can be bound to a macro via:
xboxdrv \ --ui-buttonmap A=macro:/home/juser/.xboxdrv/somefile.macro
send KEY_LEFTSHIFT 1 wait 500 send KEY_LEFTSHIFT 0
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
$ xboxdrv --ui-axismap X1=ABS_X,LB+X1=ABS_RX
- 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)
- 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.
INPUT FILTER¶
Input filter allow 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:
- 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 miliseconds 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
- 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.
- 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.
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:
- 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.
RUNNING XBOXDRV¶
USING A SINGLE CONTROLLER¶
Plug in your Xbox360 gamepad and then unload the xpad driver via:$ rmmod xpadIf you want to permanently unload it add the following line to /etc/modprobe.d/blacklist.conf:
blacklist xpadNext 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 joydevYou 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:
$ xboxdrvOr in case you don't have the necessary rights (being in group root should often be enough) start the driver as root via:
$ sudo xboxdrvThis 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 1If you have multiple wireless controller you need to start multiple instances of the xboxdrv driver and append the --wid option like this:
$ xboxdrv --wid 1You 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 --daemonWhen 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-controllerEach 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.IntrospectStatus 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.StatusSetting 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:4Setting 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:255Setting 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-jstestOr 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 = chStart xboxdrv with:
$ xboxdrv -s \ --trigger-as-zaxis --square-axis \ --relative-axis y2=64000 --axismap -y2=x2,x2=y2Your 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 accidently 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 --mouseThe --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_JOYSTICKYou might also need in addition use this (depends on the way SDL was compiled):
$ SDL_JOYSTICK_DEVICE="/dev/input/js0" $ export SDL_JOYSTICK_DEVICEThis 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 -vOnce 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 -vAlong 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 recieves 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/js0This 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:<match key="input.product" string="Xbox Gamepad (userspace driver)"> <remove key="input.x11_driver" /> </match>
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" EndSectionNote 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
- •
-
⟨http://www.immersion.com/developer/downloads/ImmFundamentals/HTML/⟩
- •
-
⟨http://msdn.microsoft.com/en-us/library/bb219655(VS.85).aspx⟩
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)2011-07-20 | 0.8.3 |