Provided by: xboxdrv_0.8.5-1_amd64 bug

NAME

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

SYNOPSIS

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

DESCRIPTION

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

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

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

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

OPTIONS

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

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

       -v, --verbose
              Print verbose messages.

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

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

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

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

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

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

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

       --help-devices
              List supported devices.

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

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

       --help-abs
              List all allowed EV_ABS symbols.

       --help-rel
              List all allowed EV_REL symbols.

       --help-key
              List all allowed EV_KEY symbols.

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

       --help-axis
              List all allowed XboxAxis symbols.

       --help-button
              List all allowed XboxButton symbols.

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

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

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

              The examples/ directory contains some example configuration files.

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

              [ui-axismap]
              x2=REL_X:10
              y2=REL_Y:-10
              x1=KEY_A:KEY_D
              y1=KEY_W:KEY_S

              [ui-buttonmap]
              a=KEY_LEFTSHIFT
              b=BTN_C
              x=BTN_EXTRA
              y=KEY_C

              [ui-buttonmap]
              lb=BTN_RIGHT
              rb=KEY_SPACE

              [ui-buttonmap]
              lt=KEY_Z
              rt=BTN_LEFT

              [ui-buttonmap]
              dl=KEY_4
              dr=KEY_2
              du=REL_WHEEL:-1:150
              dd=REL_WHEEL:1:150

              [ui-buttonmap]
              back=KEY_TAB
              start=KEY_ESC

              # EOF #

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

              To load multiple configuration options use:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              • xbox

              • xbox-mat

              • xbox360

              • xbox360-wireless

              • xbox360-guitar

              • firestorm

              • firestorm-vsb

              • saitek-p2500

              • generic-usb

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

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

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

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

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

              if=NUM The interface from which GenericUSBController should be read

              ep=NUM The endpoint from which GenericUSBController should be read

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              LED Status Codes

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

               13   rotate with two lights
               14   blink
               15   blink once

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

              $ xboxdrv --rumble-gain 50%

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              usbserial=SERIAL
                     Match against the USB iSerial number.

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

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

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

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

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

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

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

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

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

       --timeout MSEC
              Specify the number of 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), dl(left), dr(right) │ dpad         directions        (needs │
              │                                      │ --dpad-as-button option)              │
              ├──────────────────────────────────────┼───────────────────────────────────────┤
              │green, red, yellow, blue, orange      │ guitar buttons                        │
              └──────────────────────────────────────┴───────────────────────────────────────┘
              Just like with --ui-buttonmap you can add button filter to each button.

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

              $ xboxdrv --axismap -Y1=Y1

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

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

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

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

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

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

       --autofire BUTTON=FREQUENCY,...
              Autofire  mapping  allows  you  to  let  a  button  automatically  fire  with a given frequency in
              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 options:

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

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

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

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

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

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

              $ xboxdrv --deadzone 4000

              A value of 4000 works quite well for most games.

              You can also give the deadzone in percentage:

              $ xboxdrv --deadzone 15%

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

              $ xboxdrv --deadzone-trigger 15%

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

              xboxdrv --dpad-rotation 45

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

       --four-way-restrictor
              The --four-way-restrictor option allows one to limit the movement on  both  analogsticks  to  only
              four  directions (up, down, left, right), the diagonals (up/left, up/right, down/left, down/right)
              are filtered out from the output. This option is useful for games such as Tetris, that don't  need
              diagonals  and  where  you  don't  want  to  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

       --square-axis
              The Xbox360 gamepad, as most other current day gamepads, features a circular movement range, which
              restricts  the  movement  so  that the distance to the center never gets beyond 1. This means that
              when you have the controller at the top/left the value reported is  (0.7,  0.7)  (i.e.  length  1,
              angle  45) instead of (1,1). This behaviour is different then most classic PC joysticks, which had
              a square range and would report (1,1) when hold in the top/left corner.

              Some old games (i.e. mostly DOS stuff) require a square  movement  range  and  will  not  function
              properly with the Xbox360 gamepad. Via the --square-axis option you can work around this issue and
              diagonals will be reported as (1,1).

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

       --trigger-as-button
              LT and RT send button instead of axis events

       --trigger-as-zaxis
              Combine LT and RT to form a zaxis instead

       --dpad-as-button
              The DPad sends button instead of axis events.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              Allows you to change the event code that is send to the kernel for buttons. The usage  is  similar
              to  the  normal  button  mapping,  except  that  the  right  hand  side  is  an  event  name  from
              /usr/include/linux/input.h. You can use all KEY_ or BTN_ codes for --ui-buttonmap.

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

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

              Instead of the low level KEY_ names, which represent keycodes, you can also use the  higher  level
              X11  keysyms  XK_,  the  keysyms  have the advantage that they map directly to the key you expect,
              while a KEY_ name gets mangled by the X11 keymap and will often not report what you expect in case
              you use a keymap that is different then your keyboard (i.e. dvorak on a qwerty keyboard).

              A full list of valid X11 keysyms can be optained with --help-x11keysym.

              For joystick buttons there is in addition to the BTN_JOYSTICK, BTN_X, etc. macros the special name
              JS_$NUM, which sets the given button to the $NUMS joystick button, i.e.:

              $ xboxdrv --ui-clear --ui-buttonmap A=JS_0,B=JS_1

              Note that this will only work if no other joystick button ids are in the way.

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

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

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

              REPEAT gives the number of 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 this:

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

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

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

              BTN_A@{deviceid}.{slotid}

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

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

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

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

              You can also apply filters to button events:

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

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

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

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

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

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

              REPEAT gives the number of 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 down

              THRESHOLD gives the threshold that triggers the sending of an event

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

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

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

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

INPUT EVENT HANDLER

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

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

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

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

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

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

       $ xboxdrv --ui-buttonmap A=KEY_A

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

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

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

              An example for the hold button would look like:

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

              This will send JS_0 events when the button is pressed and switch to JS_1 events  when  the  button
              was hold for 500 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

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

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

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

              Here Y will scroll up and A will scroll down.

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

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

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

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

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

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

              See cycle-key-named for a full example.

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

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

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

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

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

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

       macro  A button can be bound to a macro via:

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

              The .macro file has the form of:

              send KEY_LEFTSHIFT 1
              wait 500
              send KEY_LEFTSHIFT 0

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

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

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

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

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

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

              THRESHOLD gives the threshold that triggers the sending of an event

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

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

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

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

              REPEAT gives the number of 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.

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

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

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

INPUT FILTER

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

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

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

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

              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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              x-axis: only allow movement in the X axis

              y-axis: only allow movement in the Y axis

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

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

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

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

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

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

RUNNING XBOXDRV

   USING A SINGLE CONTROLLER
       Plug in your Xbox360 gamepad and then unload the xpad driver via:

       $ rmmod xpad

       If you want to permanently unload it add the following line to /etc/modprobe.d/blacklist.conf:

       blacklist xpad

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

       $ modprobe uinput
       $ modprobe joydev

       You also have to make sure that you have access rights to /dev/input/uinput, either add yourself  to  the
       appropriate group, adjust the permissions or run xboxdrv as root.

       Once ensured that xpad is out of the way and everything is in place start the userspace driver with:

       $ xboxdrv

       Or  in  case  you  don't have the necessary rights (being in group root should often be enough) start the
       driver as root via:

       $ sudo xboxdrv

       This will create /dev/input/js0 and allow you to access the gamepad from any game.  To  exit  the  driver
       press Ctrl-c.

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

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

       $ xboxdrv --trigger-as-button

   USING MULTIPLE CONTROLLER
       If you want to use multiple wired controllers you need to start multiple instances of the xboxdrv  driver
       and append the -i argument to select the appropriate controller like this:

       $ xboxdrv -i 1

       If  you  have multiple wireless controller you need to start multiple instances of the xboxdrv driver and
       append the --wid option like this:

       $ xboxdrv --wid 1

       You have to sync the wireless controller as usual.

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

       $ xboxdrv --list-controller

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

       $ xboxdrv --daemon

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

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

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

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

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

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

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

XBOXDRV DAEMON DBUS INTERFACE

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

       Introspection is provided via the usual means:

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

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

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

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

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

       Setting the LED on controller 0 can be done via:

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

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

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

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

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

TESTING

       Knowing  how  to  test  a xboxdrv configuration is absolutely crucial in understanding what is wrong in a
       given setup. Testing the configuration in a game is most often not helpful, since you won't see the  true
       cause  beyond  endless  layers  of abstraction between you and the actual events. Luckily there are a few
       tools you can use to test, all of these are command line based and it is recomment that you get  familiar
       with them when you want to do any more complex configuration.

   EVTEST
       evtest  lets you read raw input events from /dev/input/eventX. The event devices are the very core of all
       event handling, things like the joystick devices are derived from the event device, so if you want to fix
       some issue on the joystick device, you have to fix the event device.

       evtest  is  available in the tools/ directory or as part of your distribution in the package evtest. your
       distribution.

   JSTEST
       jstest lets you read the output out of a joystick event device (/dev/input/js0).

       jstest is available in the tools/ directory or as part of your distribution joystick.

   SDL-JSTEST
       sdl-jstest lets you see events as games using SDL see them. This is very important when you want  to  set
       and test the SDL_LINUX_JOYSTICK environment variables.

       It is currently available via:

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

       Or from the same Ubuntu PPA that also contains xboxdrv in the package sdl-jstest.

   XEV
       xev  lets  you  see the events that Xorg sees. Note however that you might not see all events, since some
       will be grapped by your Window manager before they reach xev, this is normal.

       xev is part of every Linux distribution, on Ubuntu its available via:

       $ apt-get install x11-utils

   JSCALC AND JSCALIBRATOR
       Both of these tools lets you calibrate your gamepad, however with pretty much all current  gamepads  this
       is  no  longer  needed  and actually harmful as it might overwrite a perfectly good working configuration
       with a broken one (unplugging the gamepad or a reboot will fix that). So avoid them  unless  you  clearly
       understand the issues of using them.

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

   MOUSE
       No tools for testing the output on /dev/input/mouseX are known.

   NOTE
       If the tools provide no output at all, this might not be due to a wrong configuration, but  due  to  Xorg
       grabbing your event device and locking it, see Xorg section for possible fixes.

EXAMPLES

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

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

       $ xboxdrv --trigger-as-button

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

       $ xboxdrv --deadzone 25%

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

       $ xboxdrv --buttonmap X1^deadzone:15000

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

       $ xboxdrv \
         --ui-clear \
         --ui-buttonmap a=XK_a,b=XK_b,x=XK_x,y=XK_y \
         --ui-buttonmap dl=XK_Left,dr=XK_Right,du=XK_Up,dd=XK_Down

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

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

   CH FLIGHTSTICK EMULATION IN DOSBOX:
       In dosbox.conf set:

       [joystick]
       joysticktype = ch

       Start xboxdrv with:

       $ xboxdrv -s \
         --trigger-as-zaxis --square-axis \
         --relative-axis y2=64000 --axismap -y2=x2,x2=y2

       Your right analog stick will act as trottle control, the trigger as rudder. Using --modifier to install a
       four-way  restrictor  might  also  be worth a consideration to not accidently touch the throttle when the
       rudder is moved.

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

       $ xboxdrv --next-config --mouse

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

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

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

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

   SAUERBRATEN
       First analogstick gets mapped te cursor keys, second analogstick gets mapped to mouse. Note: This is just
       an incomplete example, not a perfectly playable configuration, you have to do tweaking yourself.

       $ xboxdrv \
         --ui-axismap x2=REL_X:10,y2=REL_Y:-10,x1=KEY_LEFT:KEY_RIGHT,y1=KEY_UP:KEY_DOWN \
         --ui-buttonmap a=BTN_RIGHT,b=BTN_LEFT,x=BTN_EXTRA \
         --ui-buttonmap rb=KEY_5,lb=KEY_6,lt=BTN_LEFT,rt=BTN_RIGHT \
         --ui-buttonmap y=KEY_ENTER,dl=KEY_4,dr=KEY_2,du=KEY_1,dd=KEY_3,back=KEY_TAB,start=KEY_ESC \
         -s --deadzone 6000  --dpad-as-button --trigger-as-button

   WARSOW
       Note: This is just an incomplete example, not a perfectly playable configuration, you have to do tweaking
       yourself.

       $ xboxdrv \
         --ui-axismap x2=REL_X:10,y2=REL_Y:-10,x1=KEY_A:KEY_D,y1=KEY_W:KEY_S \
         --ui-buttonmap a=KEY_LEFTSHIFT,b=BTN_C,x=BTN_EXTRA,y=KEY_C \
         --ui-buttonmap lb=BTN_RIGHT,rb=KEY_SPACE \
         --ui-buttonmap lt=KEY_Z,rt=BTN_LEFT \
         --ui-buttonmap dl=KEY_4,dr=KEY_2,du=REL_WHEEL:-1:150,dd=REL_WHEEL:1:150 \
         --ui-buttonmap back=KEY_TAB,start=KEY_ESC \
         -s --deadzone 6000 --dpad-as-button --trigger-as-button

WRITING START-UP SCRIPTS FOR GAMES

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

       #!/bin/sh

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

       # EOF #

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

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

SDL NOTES

       To let SDL know which axis act as a hat and which act as normal axis  you  have  to  set  an  environment
       variable:

       $ SDL_LINUX_JOYSTICK="'Xbox Gamepad (userspace driver)' 6 1 0"
       $ export SDL_LINUX_JOYSTICK

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

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

       This  will  let the DPad act as Hat in SDL based application. For many games the driver will work without
       this, but especially in Dosbox this variable is very important.

       If you use options in xboxdrv that change the number of axis you have to adjust the variable accordingly,
       see:

       • ⟨ftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars⟩

       SDL_LINUX_JOYSTICK
         Special  joystick  configuration  string for linux. The format is "name numaxes numhats numballs" where
         name is the name string of the joystick (possibly in single quotes), and the rest  are  the  number  of
         axes, hats and balls respectively.

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

TROUBLESHOOTING

   "NO XBOX OR XBOX360 CONTROLLER FOUND"
       This means that either your controller isn't plugged in or is not recognized by the driver. To  fix  this
       you need to know the idVendor and the idProduct numbers, which you can find out via:

       $ lsusb -v

       Once done you can try to add them to this array in src/xpad_device.cpp:

       XPadDevice xpad_devices[] = { ... }

       If  you  have  success with that, send a patch to <grumbel@gmail.com>, if not, contact me too, I might be
       able to provide additional help.

       As an alternative you can also use the --device and --type option to enforce a USB device as  well  as  a
       controller type an bypass any auto detection.

   "UNKNOWN DATA: BYTES: 3 DATA: ..."
       This  means  that your controller is sending data that isn't understood by the driver. If your controller
       still works, you can just ignore it, the Xbox360 controller seems to send out useless data every now  and
       then.  If  your  controller  does  not work and you get plenty of those lines when you move the sticks or
       press buttons it means that your controller talks an un-understood protocol and some reverse  enginiering
       is required. Contact <grumbel@gmail.com> and include the output of:

       $ lsusb -v

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

   "ERROR: NO STUITABLE UINPUT DEVICE FOUND"
       Make  sure that uinput and joydev kernel modules are loaded. Make sure that you have a /dev/input/uinput,
       /dev/uinput or /dev/misc/uinput and permissions to access it.

       Before reporting this as a bug make sure you have tested if the driver itself works with:

       $ xboxdrv --no-uinput -v

   THE WIRELESS CONTROLLER DOESN'T WORK
       You have to sync the controller befor it can be used, restart of the driver isn't needed and  the  driver
       should let you now when it recieves a connection after you sync the controller.

   KEYBOARD EMULATION
       When  you try to let xboxdrv send a keyboard events via --ui-buttonmap or --ui-axismap Xorg must register
       the device as keyboard device to work properly. This seems to work automatically when you bind more  then
       two  keyboard  keys,  if  you  bind  less  you  need to create the file /etc/hal/fdi/preprobe/xboxdrv.fdi
       containing:

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

       This will tell HAL and later Xorg that xboxdrv acts as keyboard.

   WACOM ISSUES
       In some older kernels a Wacom graphic tablet creates a joystick device, so  xboxdrv  or  any  other  real
       joysticks  ends up as /dev/input/js1 instead of /dev/input/js0. In many games this causes the joystick to
       not function any more.

       A temporary workaround for this is to simply delete the  joystick  device  js0  and  replace  it  with  a
       symbolic link js1 via:

       $ sudo ln -sf /dev/input/js1 /dev/input/js0

       This  workaround will only last till the next reboot, since the device names are dynamically created, but
       for the time being there doesn't seem to any other way to easily work around this issue.

       In newer kernels this issue is fixed.

   UINPUT ISSUES
       On Ubuntu 9.04 the permissions of the uinput device have changed to 0640, meaning only root has access to
       the  device.   To change this back so that users in the group root have access the device and in turn can
       run xboxdrv without sudo you have to create a file  called  /etc/udev/rules.d/55-permissions-uinput.rules
       with the content:

       KERNEL=="uinput", MODE="0660", GROUP="root"

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

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

XORG ISSUES

       If  you  start  xboxdrv  and instead of having a fully working joystick, you end up controlling the mouse
       that might be due to recent changes in Xorg and its device hotplug handling. There are four  workarounds,
       the one that involves editing /etc/hal/fdi/policy/preferences.fdi is the recommont one.

   TEMPORARY WORKAROUND USING HAL-DEVICE
       Get the device id from hal:

       $ hal-find-by-property --key 'info.product' --string 'Xbox Gamepad (userspace driver)'

       Then remove the device from hal with:

       $ hal-device -r $DEVICEID

   TEMPORARY WORKAROUND USING XINPUT
       Second workaround works with xinput:

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

   PERMANENT WORKAROUND USING .FDI FILES
       The former two workarounds are just temporary and have to be redone after each start of xboxdrv, the last
       workaround is a permanent one:

       You have to edit:

       /etc/hal/fdi/policy/preferences.fdi

       And insert the following lines:

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

   PERMANENT WORKAROUND BY DISABLING DEVICE AUTO DETECTION
       A fourth workaround involved disabling the autodetection of Xorg completely, you can do  that  by  adding
       the following lines to /etc/X11/xorg.conf:

       Section "ServerFlags"
         Option "AutoAddDevices" "False"
       EndSection

       Note  that without auto detection you will have to manually configure all your mice and keyboards or your
       Xorg Server won't start up properly. So unless you are already familiar  with  editing  Xorg  you  better
       avoid  this workaround. Workaround 3) has basically the same effect, except that auto detection only gets
       disabled for the single device it is causing problems.

FORCE FEEDBACK PROGRAMMING

       For documentation on the FF interface see:

       • ⟨http://github.com/github/linux-2.6/blob/f3b8436ad9a8ad36b3c9fa1fe030c7f38e5d3d0b/Documentation/input/ff.txt⟩

       • /usr/include/linux/input.h

       Additional, non Linux related, force feedback related information can be found at:

       • ⟨http://www.immersion.com/developer/downloads/ImmFundamentals/HTML/⟩

       • ⟨http://msdn.microsoft.com/en-us/library/bb219655(VS.85).aspx⟩

       fftest is an application you can use to test the force feedback interface.

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

BUGS

   X11 KEYSYM ISSUES
       X11  keysyms  might  not  work  correctly in --ui-buttonmap a=XK_Foobar when Foobar is mapped to multiple
       keycodes in the keymap.

       Workaround: Use KEY_ instead or cleanup your keymap

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

   NON-INTERRUPTABLE PROCESSES DUE TO FORCE FEEDBACK
       Force feedback support is brittle, if you Ctrl-c the driver in the wrong moment you will end  up  with  a
       dead uninterruptable process and basically have to reboot. This looks like it might be a kernel issue and
       not a xboxdrv one.

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

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

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

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

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

COPYRIGHT

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

SEE ALSO

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