%xboxdrvstuff; ]> 2010-05-05 xboxdrv 1 &xboxdrv_version; &xboxdrv_version; User Commands xboxdrv xboxdrv A Xbox/Xbox360 gamepad driver that works in userspace xboxdrv OPTION 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 you to use the configurability of xboxdrv on regular PC joysticks and thus lets xboxdrv serve a similar purpose as joy2key. See the option --evdev below for more information. -h, --help Display help text and exit. -V, --version Print the version number and exit. -v, --verbose Print verbose messages. --help-led List possible values for the led. --help-devices List supported devices. -s, --silent Do not display events on console. --quiet Do not display startup text. -L, --list-controller List available controllers on the system. --list-supported-devices List supported devices (used by xboxdrv-daemon.py). --list-supported-devices-xpad List supported devices in xpad.c style. -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. --no-uinput Do not try to start uinput event dispatching, useful for debugging. --mimic-xpad Causes xboxdrv to use the same axis and button names as the xpad kernel driver. --no-extra-devices Normally xboxdrv will create an extra device for keyboard emulation and mouse emulation when it detects a button mapping that requires that. If this option is set, it will not do that and instead dump all the buttons into the joystick device. -D, --daemon Run as daemon. In most situations this is not very useful, as xboxdrv will fail when the pad is removed or plugged in. See xboxdrv-daemon(1) for a way to launch xboxdrv automatically. -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. -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 device BUS:DEV, do not do any scanning --device-by-id VENDOR:PRODUCT Use device that matches VENDOR:PRODUCT (as returned by lsusb) --type TYPE Ignore autodetection and enforce the controller type. Possible values for TYPE: xbox xbox-mat xbox360 xbox360-wireless xbox360-guitar --evdev DEVICE Allows you to read input data from a regular event device. This allows you to use xboxdrv on regular PC joysticks. The data that is read from the event device is converted internally into a XboxMsg object and then passed through the same configuration pipeline as it would be for a regular Xbox360 controller. This allows you to make use of all the regular configurability, but limits you to the number of axis and buttons that an Xbox360 controller provides. As a regular PC joystick will most likely already create a /dev/input/jsX device by itself, you might need to get rid of that so that a game will properly detect the joystick device created by xboxdrv. The easiest way to accomplish that is to simply delete the old joystick and rename the device that xboxdrv created to /dev/input/js0. When you use udev, this operation should be harmless and automatically reverse itself when you remove the controller and plug it back in or when you reboot the computer. --evdev-absmap ABSMAP Sets how evdev events are mapped to Xbox controller 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 start a full list of event names that the given event device supports. --evdev-keymap KEYMAP Sets how evdev events are mapped to Xbox controller events. An example configuration would look like this: --evdev-keymap BTN_TRIGGER=a,BTN_THUMB=b,BTN_THUMB2=x xboxdrv will output on start a full list of event names that the given event device supports. -l, --led NUM Set LED status. Possible values for NUM are: Num Behaviour 0 off1 all blinking2 1/top-left blink, then on3 2/top-right blink, then on4 3/bottom-left blink, then on5 4/bottom-right blink, then on6 1/top-left on7 2/top-right on8 3/bottom-left on9 4/bottom-right on10 rotate11 blink12 blink slower13 rotate with two lights14 blink15 blink once -r, --rumble L,R Set the speed for both rumble motors. Values from 0 to 255 are accepted, the default is 0,0. --deadzone NUM The deadzone is the area at which the sticks do not report any events. The default is zero, which gives the best sensitifity but might also cause trouble in some games in that the character or camera might move without moving the stick. To fix this one has to set the value to something higher: $ xboxdrv --deadzone 4000 A value of 4000 works quite well for most games. You can also give the deadzone in percentage: $ xboxdrv --deadzone 15% --deadzone-trigger NUM The left and right trigger have a separate deadzone value which can be specified with: $ xboxdrv --deadzone-trigger 15% --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. -b, --buttonmap BUTTON=BUTTON,... Button remapping is available via the --buttonmap option. If you want to swap button A and B start with: $ xboxdrv --buttonmap A=B,B=A If you want all face buttons send out A button events: $ xboxdrv --buttonmap B=A,X=A,Y=A Possible button names are (aliases are in parenthesis): 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 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. --ui-buttonmap UIBUTTONSPEC,... 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. 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 mungled by the X11 keymap and will often not report what you expect in case you use a keymap that is different then your keyboard (i.e. dvorak on a qwerty keyboard). A full list of X11 keysyms is available at /usr/include/X11/keysymdef.h, note that you can only use those that are reachable by your current keymap. Keysyms that are reachable via multiple keycodes might break the mapping from keysym to evdev code. 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 milisecond 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 makeing use of device_id would look like this: In this example the left stick creates a joystick device and the right stick creates a separate joystick device. Instead of giving just a single button, it is also possible to give two buttons to --ui-buttonmap to allow shifting: 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. --ui-axismap UIAXISSPEC,... 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 (default: 10) REPEAT gives the number of milisecond to pass before the event is fired again (default: 5) $ 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 --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: -m, --mouse Lets the controller act as a mouse. It is indendical to: You can customize is by the usal means, just make sure that --mouse comes before you 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. --name DEVNAME Changes the descriptive name the device will have --square-axis The Xbox360 gamepad, as most other current day gamepads, features a circular movement range, which restricts the movement so that the distance to the center never gets beyond 1. This means that when you have the controller at the top/left the value reported is (0.7, 0.7) (i.e. length 1, angle 45) instead of (1,1). This behaviour is different then most classic PC joysticks, which had a square range and would report (1,1) when hold in the top/left corner. Some old games (i.e. mostly DOS stuff) require a square movement range and will not function properly with the Xbox360 gamepad. Via the --square-axis option you can work around this issue and diagonals will be reported as (1,1). --four-way-restrictor The --four-way-restrictor option allows to 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. --dpad-rotation DEGREE Allows you to rotate the dpad. DEGREE must be a multiple of 45. This can be useful in isometric games where the playfield itself is rotated, thus a: xboxdrv --dpad-rotation 45 Will give you controls that are relative to your character instead of your viewpoint. --axis-sensitivty AXIS=SENSITIVITY,... The sensitive of an axis can be adjusted via --axis-sensitivty: $ xboxdrv --axis-sensitivty X1=-2.0,Y1=-2.0 A value of 0 gives you the default linear sensitivity, values larger then 0 will give you heigher sensitivity, while values smaller then 0 will give you lower sensitivity. Sensitivity works by applying: To the value of the axis, thus both the min and max position will always stay the same, only the values inbetween change. --relative-axis AXIS=NUM,... The function --relative-axis allows you to change the behaviour of an axis so that your movement of it moves its value up or down instead of applying it directly. This allows you to simulate throttle control for flightsim games. Since the axis might be upside down, you might want to use the --axismap function to reverse it. $ xboxdrv --relative-axis y2=64000 --axismap -y2=y2 --autofire BUTTON=FREQUENCY Autofire mapping allows you to let a button automatically fire with a given frequency in miliseconds: $ xboxdrv --autofire A=250 Combining --autofire with button map allows you to have one button act as autofire while another one, emitting the same signal, acts normally. $ xboxdrv --autofire B=250 --buttonmap B=A --calibration CALIBRATIONSPEC If your gamepad for some reason can't reach the maximum value or isn't centered properly you can fix that via the calibration options: $ xboxdrv --calibration X2=-32768:0:32767 X2 is the axis name and the three values that follow are min, center and max. Simply insert the values that jstest reports when your axis is in the respective positions. You can also use the calibration option if you want to make your joystick more sensitive. A setting of: xboxdrv --calibration AXIS=MIN:CENTER:MAX,... Will cause the joystick device report maximum position when your stick is only moved half the way. --axis-sensitivty AXIS=SENSITIVITY,... The sensitive of an axis can be adjusted via --axis-sensitivty: $ xboxdrv --axis-sensitivty X1=-2.0,Y1=-2.0 A value of 0 gives you the default linear sensitivity, values larger then 0 will give you heigher sensitivity, while values smaller then 0 will give you lower sensitivity. Sensitivity works by applying: To the value of the axis, thus both the min and max position will always stay the same, only the values inbetween change. --force-feedback Enables the standard kernel force feedback interface. It is disabled by default as it causes trouble with some applications running in Wine. Since the Xbox360 controller supports just rumble not full force feedback, xboxdrv tries to emulate other effects. This emulation hasn't been tested much and might not always work as expected. Bug reports and test cases are welcome. Note that you must close the application that is using force feedback always before you close the xboxdrv driver, else you might end up with a hanging non-interruptable xboxdrv process that will require a reboot to get rid of. --rumble-gain AMOUNT You can change the rumble strength via: $ xboxdrv --rumble-gain 50% Values larger then 100% are possible as well. 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 programms to create input devices and the joydev module which gives you the /dev/input/jsX device: You also have to make sure that you have access rights to /dev/input/uinput, either add yourself to the appropriate group, adjust the permissions or run xboxdrv as root. Once ensured that xpad is out of the way and everything is in place start the userspace driver with: $ xboxdrv Or in case you don't have the neccesary rights (being in group root should often be enough) start the driver as root via: $ sudo xboxdrv This will create /dev/input/js0 and allow you to access the gamepad from any game. To exit the driver press Ctrl-c. If you have multiple wired controllers you need to start multiple instances of the xboxdrv driver and append the -i argument like this: $ xboxdrv -i 1 If you have multiple wireless controller you need to start multiple instances of the xboxdrv driver and append the --wid argument like this: $ xboxdrv --wid 1 You have to sync the wireless controller as usual. This will then use the second detected controller, see to see which id your controller has: $ xboxdrv --list-controller When everything works as expected it is recomment that you run xboxdrv with the silent option: $ xboxdrv --silent This will suppress the logging of events to the console and will gurantee that no uneccesarry CPU cycles are wasted. If you want to abuse the led or rumble of the gamepad for notification in scripts you can do see via: $ xboxdrv --led 10 --rumble 30,30 --quit This will cause a mild rumble and the led to rotate, you can stop it again via, which also happens to be the command you can use to stop your Xbox360 controller from blinking: $ xboxdrv ---led 0 --rumble 0,0 --quit For rumble to work make sure you have connected the controller to a USB port that has enough power, an unpowered USB hub might not work. Knowing how to test a xboxdrv configuration is absolutely crucial in understanding what is wrong in a given setup. Testing the configuration in a game is most often not helpful, since you won't see the true cause beyond endless layers of abstraction between you and the actual events. Luckily there are a few tools you can use to test, all of these are command line based and it is recomment that you get familar with them when you want to do any more complex configuration. evtest lets you read raw input events from /dev/input/eventX. The event devices are the very core of all event handling, things like the joystick devices are derived from the event device, so if you want to fix some issue on the joystick device, you have to fix the event device. evtest is available in the tools/ directory, you might also find it in your distribution. jstest lets you read the output out of a joystick event device (/dev/input/js0). jstest is available in the tools/ directory or as part of your distribution. sdl-jstest lets you see events as games using SDL see them. This is very important when you want to set and test the SDL_LINUX_JOYSTICK environment variables. Currently available via: $ svn co svn://svn.berlios.de/windstille/trunk/sdl-jstest xev 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 Do not use this tool, for current day joysticks it doesn't do anything useful, so don't touch it, it won't fix your problems. 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 following configuration works for games that are played with keyboard, like Flash games or games that don't support a joystick, you have to adjust the keybindings to fit the game: Start xboxdrv with: The triggers are not regonized in these games when they are analog, so we have to handle them as buttons. 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 (useful for some special attacks). Instead of using the native button names, the 1,2,3,... aliases are used, which makes things easier to edit: In dosbox.conf set: Start xboxdrv with: Your right analog stick will act as trottle control, the trigger as rudder. 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. Note: This is just an incomplete example, not a perfectly playable configuration, you have to do tweaking yourself. To let SDL know which axis act as a hat and which act as normal axis you have to set an environment variable: You might also need in addition use this (depends on the way SDL was compiled): This will let the DPad act as Hat in SDL based application. For many games the driver will work without this, but especially in Dosbox this variable is very important. If you use options in xboxdrv that change the number of axis you have to adjust the variable accordingly, see: ftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars SDL_LINUX_JOYSTICK Special joystick configuration string for linux. The format is "name numaxes numhats numballs" where name is the name string of the joystick (possibly in single quotes), and the rest are the number of axes, hats and balls respectively. SDL_JOYSTICK_DEVICE Joystick device to use in the linux joystick driver, in addition to the usual: /dev/js*, /dev/input/event*, /dev/input/js* This means that either your controller isn't plugged in or not recognized by the driver. To fix this you need to know the idVendor and the idProduct numbers, which you can find out via: Once done you can try to add them to this array in xpad_device.cpp: If you have success with that, send a patch to grumbel@gmx.de, if not, contact me too, I might be able to provide additional help. As an alternative you can also use the --device and --type option to enforce a USB device as well as a controller type an bypass any auto detection. This means that your controller is sending data that isn't understood by the driver. If your controller still works, you can just ignore it, the Xbox360 controller seems to send out useless data every now and then. If your controller does not work and you get plenty of those lines when you move the sticks or press buttons it means that your controller talks an un-understood protocol and some reverse enginiering is required. Contact grumbel@gmx.de and include the output of: Along with all the "Unknown data" lines you get. This is what the program is supposed to do. After you started it, it will give you basically two devices, a new /dev/input/eventX and a /dev/input/jsX. You can access and test your controller with jstest and evtest applications (available from your distribution or in the tools/ subdirectory). Or in case you want just see if your driver is working correctly you can pass the -v option: This will cause the driver to output all the events that it received from the controller. 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: 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. 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: input.keys ]]> This will tell HAL and later Xorg that xboxdrv acts as keyboard. 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: 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: ]]> A fourth workaround involved disabling the autodetection of Xorg completly, you can do that by adding the following lines to /etc/X11/xorg.conf: 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. In recent kernels a Wacom graphic tablet creates a joystick device, so xboxdrv or any other real joysticks ends up as /dev/input/js1 instead of /dev/input/js0. In many games this causes the joystick to not function any more. A temporary workaround for this is to simply delete the joystick device js0 and replace it with a symbolic link js1 via: $ sudo ln -sf /dev/input/js1 /dev/input/js0 This workaround will only last till the next reboot, since the device names are dynamically created, but for the time being there doesn't seem to any other way to easily work around this issue. 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, this means games will not display the proper button labels, but just numbers (i.e. 'Btn1' instead of 'A' for example). Asside from that it should work fine. Xinput support (the DirectInput replacment, not the Xorg xinput) might not work properly or not at all. It is currently unknown if this can be fixed by xboxdrv or if it requires patches to Wine. For documentation on the FF interface see: http://github.com/github/linux-2.6/blob/f3b8436ad9a8ad36b3c9fa1fe030c7f38e5d3d0b/Documentation/input/ff.txt /usr/include/linux/input.h Additional, non Linux related, force feedback related information can be found at: fftest is an application you can use to test the force feedback interface. Force feedback is disabed by default since it seems to causes trouble in certain application, namely "Tomb Raider: Legend" when run in Wine it crashes at startup when rumble is enabled, while it works perfectly normal when rumble is disabled. "Tomb Raider: Anniversary" running in Wine seems to work together with xboxdrv and rumble, but hasn't been intensivly tested. X11 keysyms might not work correctly in --ui-buttonmap a=XK_Foobar when Foobar is mapped to multiple keycodes in the keymap. Workaround: Use KEY_ instead or cleanup your keymap Force feedback support is brittle, if you Ctrl-c the driver in the wrong moment you will end up with a dead uninterruptable process and basically have to reboot. This looks like it might be a kernel issue and not a xboxdrv one. Workaround: Kill the app that uses xboxdrv before xboxdrv itself. Report bugs to Ingo Ruhnke grumbel@gmx.de. Copyright © 2010 Ingo Ruhnke grumbel@gmx.de License GPLv3+: GNU GPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. xboxdrv-daemon 1 , evtest 1 , jstest 1 , xev 1 , fftest 1 , lsusb 1