Provided by: xboxdrv_0.8.2-1_i386 bug


       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

       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.


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

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

       -v, --verbose
              Print verbose messages.

              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.

              Do not display startup text and suppress most other output.

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

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

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

              List possible values for the led.

              List supported devices.

              List supported devices (used by

              List supported devices in xpad.c style.

              List all allowed EV_ABS symbols.

              List all allowed EV_REL symbols.

              List all allowed EV_KEY symbols.

              List all allowed X11 Keysym symbols.

              List all allowed XboxAxis symbols.

              List all allowed XboxButton symbols.

              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.

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

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

              The  examples/  directory  contains  some  example configuration








              # EOF #

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

              To load multiple configuration options use:

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

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

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

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

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

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

              xboxdrv --daemon \
                  # config options for the first controller
                --next-controller \
                  # config options for the second controller
                  # 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.

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

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

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

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

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

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

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

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

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

              · xbox

              · xbox-mat

              · xbox360

              · xbox360-wireless

              · xbox360-guitar

              · firestorm

              · firestorm-vsb

              · saitek-p2500

              · generic-usb

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

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

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

                     The vendor id  of  the  controller  to  which  this  spec

                     The  product  id  of  the  controller  to which this spec

              if=NUM The interface from which GenericUSBController  should  be

              ep=NUM The  endpoint  from  which GenericUSBController should be

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

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

              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

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

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

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

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

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

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

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

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

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

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

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

              LED Status Codes

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

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

              $ xboxdrv --rumble-gain 50%

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

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

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

              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.

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

              Output raw chatpad data to the stdout for debugging purpose.

       Xboxdrv does not  support  the  headset,  the  options  below  are  for
       developers only and will dump raw headset data, not .wav files.

              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

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

              Since the Xbox360 controller supports just rumble not full force
              feedback, xboxdrv tries to emulate other effects. This emulation
              hasn't been tested much and might not always work  as  expected.
              Bug reports and test cases are welcome.

              Note  that  you  must  close the application that is using force
              feedback always before you close the xboxdrv  driver,  else  you
              might  end  up  with a hanging non-interruptable xboxdrv process
              that will require a reboot to get rid of.

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

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

              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:

                     Match  controllers  that  have  the  given USB vendor and
                     product ids.

                     Match controllers that have the given USB idVendor.

                     Match controllers that have the given USB idProduct.

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

                     Match against the USB path given by BUS and DEV.

                     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.

       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.

              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 \
                  --ui-axismap X1=ABS_X,Y1=ABS_Y \
                  --ui-buttonmap A=JS_0,B=JS_1

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

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

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

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

              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), │ dpad   directions   (needs │
              │dl(left), dr(right)        │ --dpad-as-button option)   │
              │green, red, yellow,  blue, │ guitar buttons             │
              │orange                     │                            │
              Just  like with --ui-buttonmap you can add button filter to each

       --axismap AXIS=MAPPING,...
              Axis remapping is available via --axismap and works the same  as
              button  mapping.  In  addition you can supply a sign to indicate
              that an axis should be inverted. So if you want to invert the y1
              axis start with:

              $ xboxdrv --axismap -Y1=Y1

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

              $ xboxdrv --axismap X2=X1,Y2=Y1,X1=X2,Y1=Y2

              Possible axis names are: x1, y1, x2, y2, lt, rt

              Swaping  lt  or  rt  with x1, y1, x2, y2 will not work properly,
              since their range is different.

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

       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

              Combining --autofire with button map  allows  you  to  have  one
              button  act  as  autofire  while  another one, emitting the same
              signal, acts normally.

              $ xboxdrv --autofire B=250 --buttonmap B=A

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

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

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

              Sensitivity works by applying:

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

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

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

       --calibration CALIBRATIONSPEC
              If your gamepad for some reason can't reach the maximum value or
              isn't centered properly you can fix  that  via  the  calibration

              $ xboxdrv --calibration X2=-32768:0:32767

              X2  is  the  axis name and the three values that follow are min,
              center and max. Simply insert the  values  that  jstest  reports
              when your axis is in the respective positions.

              You can also use the calibration option if you want to make your
              joystick more sensitive. A setting of:

              xboxdrv --calibration AXIS=MIN:CENTER:MAX,...

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

       --deadzone NUM
              The  deadzone  is the area at which the sticks do not report any
              events. The default is zero, which gives  the  best  sensitifity
              but might also cause trouble in some games in that the character
              or camera might move without moving the stick. To fix  this  one
              has to set the value to something higher:

              $ xboxdrv --deadzone 4000

              A value of 4000 works quite well for most games.

              You can also give the deadzone in percentage:

              $ xboxdrv --deadzone 15%

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

              $ xboxdrv --deadzone-trigger 15%

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

              xboxdrv --dpad-rotation 45

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

              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.

              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

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

       The  following  options  are simple shortcuts for common configurations
       that  can  be  accomplished  manually  by  using   --ui-buttonmap   and

              LT and RT send button instead of axis events

              Combine LT and RT to form a zaxis instead

              The DPad sends button instead of axis events.

              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.

              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 \
                --deadzone 4000
                --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

              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.

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

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

              Do not to start UInput, instead  simply  read  events  from  the
              controller, useful for debugging.

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

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

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

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

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

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

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

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

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

              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'

       --ui-buttonmap UIBUTTONSPEC,...
              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

              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 making use of device_id would look like

              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:


              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

              You can also apply filters to button events:

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

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

       --ui-axismap UIAXISSPEC,...
              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 milisecond 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
              miliseconds).  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

              THRESHOLD gives the threshold that triggers the  sending  of  an

              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

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

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

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

              An example for the hold button would look like:

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

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

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

       abs    not yet implemented

              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.

              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.

              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

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

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

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

              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

              See cycle-key-named for a full example.

       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/

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

       macro  A button can be bound to a macro via:

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

              The .macro file has the form of:

              send KEY_LEFTSHIFT 1
              wait 500
              send KEY_LEFTSHIFT 0

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

       Axis  event  handler  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

              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_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

              THRESHOLD  gives  the  threshold that triggers the sending of an

              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.

              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 milisecond 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
              miliseconds).  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.

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

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

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


       Input  filter  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.

       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

              RATE is the number of miliseconds between button press events.

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

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

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

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

              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.

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

              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

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

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

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

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

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

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

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

              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.

              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

       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.

              See --dpad-rotation.

              Restricts the dpad movement, values for RESTRICTON can be:

              x-axis: only allow movement in the X axis

              y-axis: only allow movement in the Y axis

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

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

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

              Rotates  the  stick  given  by  XAXIS  and  YAXIS  by DEGREE and
              optionally MIRRORS it.

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

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


       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

       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

       $ 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/


       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

       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

       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

       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://

       Or from the same Ubuntu PPA that also contains xboxdrv in  the  package

       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

       $ 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:

       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 accidently 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

       $ 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

       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:


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

       # 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


       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

       $ 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:

       · ⟨⟩

         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.

         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  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 <>,  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

       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 <> 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 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:

       <?xml version="1.0" encoding="UTF-8"?>
       <deviceinfo version="0.2">
           <match key="input.product" string="Xbox Gamepad (userspace driver) - Keyboard Emulation">
             <addset key="info.capabilities" type="strlist">input.keys</addset>

       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

       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:


       And insert the following lines:

       <match key="input.product" string="Xbox Gamepad (userspace driver)">
         <remove key="input.x11_driver" />

       A fourth  workaround  involved  disabling  the  autodetection  of  Xorg
       completely,   you  can  do  that  by  adding  the  following  lines  to

       Section "ServerFlags"
         Option "AutoAddDevices" "False"

       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:

       · ⟨⟩

       · /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

       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:


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



       Copyright  ©  2010-2011 Ingo Ruhnke <> 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.


       xboxdrvctl(1), evtest(1), jstest(1), jstest-gtk(1), xev(1),  fftest(1),