Provided by: xboxdrv_0.8.8-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  milliseconds  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), │ dpad      directions      (needs │
              │dr(right)                        │ --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 milliseconds:

              $ 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 accidentally 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  millisecond to pass before the event is fired again
              (default: 5)

              The special 'void' event allows you to clear any  existing  bindings  for  a  given
              button,  which can be useful in cases when a game only supports a limited number of
              buttons.

              You can also prepend a device_id to the UIBUTTONSPEC which  allows  you  to  create
              multiple   uinput  devices.  By  default  'auto'  is  assumed  as  device_id  which
              automatically try to do the right thing, sending  keyboard  events  to  a  keyboard
              device  and  mouse  events to a mouse device. Other possible values are 'mouse' and
              'keyboard'. A device_id of '0' refers to the first joystick device,  values  larger
              then 0 to the second, third, etc.

              Note  that  the  'mouse'  and 'keyboard' device_id names do not give you a mouse or
              keyboard device, these are just symbolic names for the devices into  which  xboxdrv
              will  sort events that look like a mouse or keyboard event. The final determination
              of which device gets handled as what will be done by the Kernel or  Xorg  depending
              on what events a device provides.

              An example configuration making use of device_id would look like this:

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

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

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

              BTN_A@{deviceid}.{slotid}

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

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

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

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

              You can also apply filters to button events:

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

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

       --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 millisecond to pass before  the  event  is  fired  again
              (default: 5).

              The  value of -1 has a special meaning, it will result in the REL event being fired
              as soon as possible (i.e.  every timeout milliseconds).  This is the recomment  way
              for handling mouse emulation, as it will keep REL events syncronized and thus avoid
              jaggies in the movement, that will result from manually specifying a timeout.

              $ xboxdrv --ui-axismap X1=KEY_UP:KEY_DOWN:THRESHOLD

              KEY_UP gives the keycode to be send when the axis is moved up

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

              THRESHOLD gives the threshold that triggers the sending of an event

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

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

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

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

INPUT EVENT HANDLER

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

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

       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
              milliseconds 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 millisecond to pass before  the  event  is  fired  again
              (default: 5).

              The  value of -1 has a special meaning, it will result in the REL event being fired
              as soon as possible (i.e.  every timeout milliseconds).  This is the recomment  way
              for handling mouse emulation, as it will keep REL events syncronized and thus avoid
              jaggies in the movement, that will result from manually specifying a timeout.

              The rel handler is mainly useful for  mouse  pointer  emulation,  if  you  want  to
              emulate a mouse scroll wheel use the rel-repeat handler instead.

       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  filters  allow one to manipulate the events that come from the controller. They can
       be used on --buttonmap, --axismap, --ui-buttonmap and --ui-axismap. The difference between
       the  two  is  that  the  --ui-...  versions  applies to the uinput events, while the other
       version applies to Xbox360 controller events.

   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 milliseconds between button press events.

              DELAY  the  amount  of milliseconds 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 milliseconds 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
       accidentally 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 receives 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)