xboxdrv/doc/xboxdrv.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
          <!ENTITY % xboxdrvstuff SYSTEM "xboxdrv.ent">
          %xboxdrvstuff;
          ]>
<refentry id="xboxdrv">
  <refentryinfo>
    <date>2010-05-05</date>
  </refentryinfo>
  
  <refmeta>
    <refentrytitle>
      <application>xboxdrv</application>
    </refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="version">&xboxdrv_version;</refmiscinfo>
    <refmiscinfo class="author">&xboxdrv_version;</refmiscinfo>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
    <refmiscinfo class="source">xboxdrv</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>
      <application>xboxdrv</application>
    </refname>
    <refpurpose>
      A Xbox/Xbox360 gamepad driver that works in userspace
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>xboxdrv</command>
      <arg rep="repeat"><option>OPTION</option></arg>
      <arg><option>--</option></arg>
      <arg><option>COMMAND</option></arg>
      <arg><option>ARGUMENTS</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>xboxdrv</command> 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 <command>xboxdrv</command> to provide regular joystick
      and event devices, which makes it compatible with all Linux
      software.
    </para>
    <para>
      Aside from the pure driver, <command>xboxdrv</command> 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.
    </para>
    <para>
      It is also possible for <command>xboxdrv</command> to read input
      data directly from an event device, this allows you to use the
      configurability of <command>xboxdrv</command> on regular PC
      joysticks and thus lets <command>xboxdrv</command> serve a
      similar purpose as <command>joy2key</command>. See the
      option <option>--evdev</option> below for more information.
    </para>
    <para>
      When a <option>COMMAND</option> 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.
    </para>
  </refsect1>

  <refsect1>
    <title>Options</title>
    <refsect2>
      <title>General Options</title>
      <variablelist>

        <varlistentry>
          <term><option>-h</option>, <option>--help</option></term>
          <listitem>
            <para>Display help text and exit.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>-V, --version</term>
          <listitem>
            <para>
              Print the version number and exit.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-v</option>, <option>--verbose</option></term>
          <listitem>
            <para>Print verbose messages.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--help-led</option></term>
          <listitem>
            <para>List possible values for the led.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--help-devices</option></term>
          <listitem>
            <para>List supported devices.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-s</option>, <option>--silent</option></term>
          <listitem>
            <para>
              Do not display events on console.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--quiet</option></term>
          <listitem>
            <para>
              Do not display startup text.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-L</option>, <option>--list-controller</option></term>
          <listitem>
            <para>
              List available controllers on the system.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--list-supported-devices</option></term>
          <listitem>
            <para>
              List supported devices (used by xboxdrv-daemon.py).
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--list-supported-devices-xpad</option></term>
          <listitem>
            <para>
              List supported devices in <filename>xpad.c</filename> style.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-R</option>, <option>--test-rumble</option></term>
          <listitem>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-uinput</option></term>
          <listitem>
            <para>
              Do not try to start uinput event dispatching, useful for debugging.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--config</option> <replaceable class="parameter">FILE</replaceable></term>
          <listitem>
            <para>
              Reads configuration information from <replaceable class="parameter">FILE</replaceable>.
              Configurations from file are handling as if they would
              be command line options at the position
              of <option>--config</option> <replaceable class="parameter">FILE</replaceable>.
            </para>
            <para>
              The syntax
              of <replaceable class="parameter">FILE</replaceable> 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.
            </para>
            <para>
              The <filename>examples/</filename> directory contains
              some example configuration files.
            </para>
            <programlisting><![CDATA[
[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 #]]></programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--mimic-xpad</option></term>
          <listitem>
            <para>
              Causes xboxdrv to use the same axis and button names as the xpad kernel driver.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-D</option>, <option>--daemon</option></term>
          <listitem>
            <para>
              Run as daemon. In most situations this is not very
              useful, as <command>xboxdrv</command> will fail when the
              pad is removed or plugged in. See xboxdrv-daemon(1) for
              a way to launch <command>xboxdrv</command>
              automatically.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
    
    <refsect2>
      <title>Device Options</title>
      <variablelist>
        <varlistentry>
          <term><option>-d</option>, <option>--detach-kernel-driver</option></term>
          <listitem>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-i</option>, <option>--id</option> <replaceable class="parameter">N</replaceable></term>
          <listitem>
            <para>
              Use controller with id N (default: 0),
              use <option>--list-controller</option> to obtain a list
              of available controller.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-w</option>, <option>--wid</option> <replaceable class="parameter">N</replaceable></term>
          <listitem>
            <para>
              Use wireless controller with wid N (default: 0).
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--device-by-path</option> <replaceable class="parameter">BUS:DEV</replaceable></term>
          <listitem>
            <para>
              Use device BUS:DEV, do not do any scanning
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--device-by-id</option> <replaceable class="parameter">VENDOR:PRODUCT</replaceable></term>
          <listitem>
            <para>
              Use device that matches VENDOR:PRODUCT (as returned by <command>lsusb</command>)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--type</option> <replaceable class="parameter">TYPE</replaceable></term>
          <listitem>
            <para>
              Ignore autodetection and enforce the controller type. Possible values for <replaceable class="parameter">TYPE</replaceable>:
            </para>
            <itemizedlist>
              <listitem><para>xbox</para></listitem>
              <listitem><para>xbox-mat</para></listitem>
              <listitem><para>xbox360</para></listitem>
              <listitem><para>xbox360-wireless</para></listitem>
              <listitem><para>xbox360-guitar</para></listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--evdev</option> <replaceable class="parameter">DEVICE</replaceable></term>
          <listitem>
            <para>
              Allows you to read input data from a regular event
              device. This allows you to
              use <command>xboxdrv</command> 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.
            </para>
            <para>
              As a regular PC joystick will most likely already create
              a <filename>/dev/input/jsX</filename> device by itself,
              you might need to get rid of that so that a game will
              properly detect the joystick device created
              by <command>xboxdrv</command>. The easiest way to
              accomplish that is to simply delete the old joystick and
              rename the device that <command>xboxdrv</command>
              created to <filename>/dev/input/js0</filename>. 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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--evdev-debug</option></term>
          <listitem>
            <para>
              The evdev event handler will print all received events
              to stdout, this makes it easy to see which events a
              given controller sends.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--evdev-no-grab</option></term>
          <listitem>
            <para>
              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 other wise
              unhandled subset of keys of an device, i.e. mapping the
              multimedia keys on a keyboard, so this option turns the
              grab off.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--evdev-absmap</option> <replaceable class="parameter">ABSMAP,...</replaceable></term>
          <listitem>
            <programlisting><![CDATA[ABSMAP = EVDEV_ABS [ "+", "-" ] "=" XBOXAXIS ;]]></programlisting>
            <para>
              Sets how evdev events are mapped to Xbox axis
              events. An example configuration would look like this:
            </para>
            <programlisting>--evdev-absmap ABS_X=x1,ABS_Y=y1,ABS_RZ=x2,ABS_THROTTLE=y2,ABS_HAT0X=dpad_x,ABS_HAT0Y=dpad_y</programlisting>
            <para>
              <command>xboxdrv</command> will output on startup a full
              list of event names that the given event device
              supports and that can be used in place of <replaceable>EVDEV_ABS</replaceable>.
            </para>
            <para>
              It is also possible to map half-axis with a command like:
            </para>
            <programlisting>--evdev-absmap ABS_Y+=LT,ABS_Y-=RT</programlisting>
            <para>
              This will map the upward movement of the Y axis to the
              left trigger and the downward movement to the right
              trigger. <!-- FIXME: directions might be wrong -->
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--evdev-keymap</option> <replaceable class="parameter">KEYMAP</replaceable></term>
          <listitem>
            <para>
              Sets how evdev events are mapped to Xbox controller
              events. An example configuration would look like this:
            </para>
            <programlisting>--evdev-keymap BTN_TRIGGER=a,BTN_THUMB=b,BTN_THUMB2=x</programlisting>
            <para>
              <command>xboxdrv</command> will output on start a full
              list of event names that the given event device
              supports.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Status Options</title>
      <variablelist>
        <varlistentry>
          <term><option>-l</option>, <option>--led</option> <replaceable class="parameter">NUM</replaceable></term>
          <listitem>
            <para>
              Set LED status. Possible values for <replaceable class="parameter">NUM</replaceable> are:
            </para>
            <table>
              <title>LED Status Codes</title>
              <tgroup cols="2">
                <colspec align="right" colwidth="1*" />
                <colspec align="left" colwidth="1*" />
                <thead>
                  <row>
                    <entry>Num</entry>
                    <entry>Behaviour</entry>
                  </row>
                </thead>
                <tbody>
                  <row><entry>0</entry> <entry> off</entry></row>
                  <row><entry>1</entry> <entry> all blinking</entry></row>
                  <row><entry>2</entry> <entry> 1/top-left blink, then on</entry></row>
                  <row><entry>3</entry> <entry> 2/top-right blink, then on</entry></row>
                  <row><entry>4</entry> <entry> 3/bottom-left blink, then on</entry></row>
                  <row><entry>5</entry> <entry> 4/bottom-right blink, then on</entry></row>
                  <row><entry>6</entry> <entry> 1/top-left on</entry></row>
                  <row><entry>7</entry> <entry> 2/top-right on</entry></row>
                  <row><entry>8</entry> <entry> 3/bottom-left on</entry></row>
                  <row><entry>9</entry> <entry> 4/bottom-right on</entry></row>
                  <row><entry>10</entry> <entry> rotate</entry></row>
                  <row><entry>11</entry> <entry> blink</entry></row>
                  <row><entry>12</entry> <entry> blink slower</entry></row>
                  <row><entry>13</entry> <entry> rotate with two lights</entry></row>
                  <row><entry>14</entry> <entry> blink</entry></row>
                  <row><entry>15</entry> <entry> blink once</entry></row>
                </tbody>
              </tgroup>
            </table>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-r</option>, <option>--rumble</option> <replaceable class="parameter"> L,R</replaceable></term>
          <listitem>
            <para>
              Set the speed for both rumble motors. Values from 0 to 255 are accepted, the default is 0,0.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>Configuration Options</title>

      <variablelist>
        <varlistentry>
          <term><option>--deadzone <replaceable class="parameter">NUM</replaceable></option></term>
          <listitem>
	    <para>
              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:
            </para>

            <programlisting>$ xboxdrv --deadzone 4000</programlisting>

            <para>A value of 4000 works quite well for most games.</para>
            
            <para>You can also give the deadzone in percentage:</para>
            
            <programlisting>$ xboxdrv --deadzone 15%</programlisting>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--deadzone-trigger <replaceable class="parameter">NUM</replaceable></option></term>
          <listitem>
            <para>
              The left and right trigger have a separate deadzone value which can be
              specified with:
            </para>
            <programlisting>$ xboxdrv --deadzone-trigger 15%  </programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--trigger-as-button</option></term>
          <listitem>
            <para>LT and RT send button instead of axis events</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--trigger-as-zaxis</option></term>
          <listitem>
            <para>Combine LT and RT to form a zaxis instead</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dpad-as-button</option></term>
          <listitem>
            <para>The DPad sends button instead of axis events.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dpad-only</option></term>
          <listitem>
            <para>
              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 <option>--trigger-as-button</option> is recommend
              in most situations.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-b, --buttonmap BUTTON=BUTTON,...</option></term>
          <listitem>
            <para>
              Button remapping is available via the <option>--buttonmap</option> option. If you want
              to swap button A and B start with:
            </para>

            <programlisting>$ xboxdrv --buttonmap A=B,B=A</programlisting>

            <para>If you want all face buttons send out A button events:</para>

            <programlisting>$ xboxdrv --buttonmap B=A,X=A,Y=A</programlisting>

            <para>Possible button names are (aliases are in parenthesis):</para>

            <table frame="all">
              <title>Button Names</title>
              <tgroup cols="2">
                <thead>
                  <row>
                    <entry>Name</entry>
                    <entry>Description</entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry>start, back</entry>
                    <entry>start, back buttons</entry>
                  </row>

                  <row>
                    <entry>guide</entry>
                    <entry>big X-button in the middle (Xbox360 only)</entry>
                  </row>

                  <row>
                    <entry>a(1), b(2), x(3), y(4)</entry>
                    <entry>face buttons</entry>
                  </row>

                  <row>
                    <entry>black, white</entry>
                    <entry>black, white buttons (Xbox1 only, mapped to lb, rb on Xbox360)</entry>
                  </row>

                  <row>
                    <entry>lb(5), rb(6)</entry>
                    <entry>shoulder buttons (Xbox360 only, mapped to black, white on Xbox1)</entry>
                  </row>

                  <row>
                    <entry>lt(7), rt(8)</entry>
                    <entry>analog trigger (needs --trigger-as-button option)</entry>
                  </row>

                  <row>
                    <entry>tl, tr</entry>
                    <entry>pressing the left or right analog stick</entry>
                  </row>

                  <row><entry>du(up), dd(down), dl(left), dr(right)</entry>
                    <entry>dpad directions (needs --dpad-as-button option)</entry>
                  </row>

                  <row>
                    <entry>green, red, yellow, blue, orange</entry>
                    <entry>guitar buttons</entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--axismap</option> <replaceable class="parameter">AXIS=MAPPING,...</replaceable></term>
          <listitem>
            <para>
              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:
            </para>

            <programlisting>$ xboxdrv --axismap -Y1=Y1</programlisting>

            <para>
              If you want to swap the left and right stick start with:
            </para>

            <programlisting>$ xboxdrv --axismap X2=X1,Y2=Y1,X1=X2,Y1=Y2</programlisting>

            <para>
              Possible axis names are: x1, y1, x2, y2, lt, rt
            </para>

            <para>
              Swaping lt or rt with x1, y1, x2, y2 will not work properly, since
              their range is different.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--ui-buttonmap</option> <replaceable class="parameter">UIBUTTONSPEC,...</replaceable></term>
          <listitem>
            <programlisting><![CDATA[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 ;]]></programlisting>
            <para>
              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
              <filename>/usr/include/linux/input.h</filename>. You can
              use all <keysym>KEY_</keysym> or <keysym>BTN_</keysym> 
              codes for <option>--ui-buttonmap</option>.
            </para>
            <para>
              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.
            </para>
            <para>
              Aside from the named keys, you can also give the input
              code directly as number via the
              syntax <keysym>KEY_#<replaceable>NUM</replaceable></keysym>.
            </para>
            <para>
              Instead of the low level <keysym>KEY_</keysym> names,
              which represent keycodes, you can also use the higher
              level X11 keysyms <keysym>XK_</keysym>, the keysyms have
              the advantage that they map directly to the key you
              expect, while a <keysym>KEY_</keysym> name gets mungled
              by the X11 keymap and will often not report what you
              expect in case you use a keymap that is different then
              your keyboard (i.e. dvorak on a qwerty keyboard).
            </para>
            <para>
              A full list of X11 keysyms is available at
              <filename>/usr/include/X11/keysymdef.h</filename>, note that you can only use those that
              are reachable by your current keymap. Keysyms that are reachable via
              multiple keycodes might break the mapping from keysym to evdev code.
            </para>
            <para>
              For joystick buttons there is in addition to the <keysym>BTN_JOYSTICK</keysym>, <keysym>BTN_X</keysym>,
              etc. macros the special name <keysym>JS_$NUM</keysym>, which sets the given button to
              the $NUMS joystick button, i.e.:
            </para>
            <programlisting>$ xboxdrv --ui-clear --ui-buttonmap A=JS_0,B=JS_1</programlisting>
            <para>
              Note that this will only work if no other joystick
              button ids are in the way.
            </para>
            <para>
              You can also map a button to a <keysym>REL_</keysym>
              event. In that case you can supply additional paramaters in the form of:
            </para>
            <programlisting>$ xboxdrv --ui-buttonmap X=REL_???:VALUE:REPEAT</programlisting>
            <para>
              <replaceable class="parameter">VALUE</replaceable> gives the value of the event (default: 10)
            </para>
            <para>
              <replaceable class="parameter">REPEAT</replaceable>
              gives the number of milisecond to pass before the event
              is fired again (default: 5)
            </para>
            <para>
              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.
            </para>
            <para>
              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. 
            </para>
            <para>
              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.
            </para>
            <para>
              An example configuration makeing use of device_id would look like this:
            </para>
            <programlisting><![CDATA[xboxdrv -s \
  --ui-clear \
  --ui-buttonmap A=0-JS_0,B=0-JS_1 --ui-axismap X2=1-ABS_X,Y2=1-ABS_Y
  --ui-buttonmap X=1-JS_0,Y=1-JS_1 --ui-axismap X2=1-ABS_X,Y2=1-ABS_Y]]></programlisting>
            <para>
              In this example the left stick creates a joystick device
              and the right stick creates a separate joystick device.
            </para>
            <para>
              Instead of giving just a single button, it is also
              possible to give two buttons
              to <option>--ui-buttonmap</option> to allow shifting:
            </para>           
            <programlisting><![CDATA[xboxdrv -s \
  --ui-clear \
  --ui-buttonmap A=JS_0,B=JS_1,LB+A=JS_2,LB+B=JS_3]]></programlisting>
            <para>
              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.
            </para>
            <para>
              See the section KEYBOARD EMULATION below on how to
              resolve issues with Xorg not detecting the virtual
              keyboard that xboxdrv creates.
            </para>
            <para>
              You can also apply filters to button events:
            </para>
            <programlisting><![CDATA[xboxdrv -s \
  --ui-buttonmap A^toggle=JS_0]]></programlisting>

            <bridgehead renderas="sect3">Hold Button</bridgehead>
            <para>
              You can send different events depending on how long a
              button was pressed by:
            </para>
            <programlisting><![CDATA[xboxdrv \
  --ui-buttonmap A=JS_0:JS_1:500]]></programlisting>
            <para>
              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.
            </para>

            <bridgehead renderas="sect3">Exec Button</bridgehead>
            <para>
              You can bind a button to an application, so that the
              application will be launched when the button was
              pressed:
            </para>
            <programlisting><![CDATA[xboxdrv \
  --ui-buttonmap A=exec:/home/juser/local/bin/screenshot.sh]]></programlisting>

            <bridgehead renderas="sect3">Macro Button</bridgehead>
            <para>
              A button can be bound to a macros via:
            </para>
            <programlisting><![CDATA[xboxdrv \
  --ui-buttonmap A=macro:/home/juser/.xboxdrv/somefile.macro]]></programlisting>
            <para>
              The <filename>.macro</filename> file has the form of:
            </para>
            <programlisting><![CDATA[
send KEY_LEFTSHIFT 1
wait 500
send KEY_LEFTSHIFT 0]]></programlisting>
            <para>
              All abs, rel and key events can be send from a macro file.
            </para>

            <bridgehead renderas="sect3">Toggle Filter</bridgehead>
            <para>
              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.
            </para>

            <bridgehead renderas="sect3">Invert Filter</bridgehead>
            <para>
              The invert filter will keep the button in pressed state
              when it is not pressed and in unpressed state when it is
              pressed.
            </para>

            <bridgehead renderas="sect3">Autofire Filter</bridgehead>
            <para>
              The autofire filter allows to repeatatly send button
              press events when the button is held down. It takes two
              optional parameters:
            </para>
            <para>
              <replaceable>RATE</replaceable> is the number of
              miliseconds between button press events.
            </para>
            <para>
              <replaceable>DELAY</replaceable> the amount of
              miliseconds till the autofire will start, before that
              delay the button will act as normal.
            </para>

            <bridgehead renderas="sect3">Log Filter</bridgehead>
            <para>
              The log filter will output everything to stdout that
              goes through it to, this is useful for debugging the
              filter. A <replaceable>STRING</replaceable> can be
              provided as parameter that will be outputed before the
              event.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ui-axismap</option> <replaceable class="parameter">UIAXISSPEC,...</replaceable></term>
          <listitem>
            <programlisting><![CDATA[UIAXISSPEC = [ XBOXBTN "+" ] XBOXAXIS { "^" FILTER }  "=" ( RELSPEC | BTNSPEC | ABSSPEC ) ;
BTNSPEC    = "KEY_" NAME ":" "KEY_" NAME ":" THRESHOLD ;
RELSPEC    = "REL_" NAME ":" VALUE ":" REPEAT ;
ABSSPEC    = "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 ;]]></programlisting>
            <para>
              Similar to <option>--ui-buttonmap</option> 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 <option>--ui-buttonmap</option>.
            </para>
            <programlisting>$ xboxdrv --ui-axismap X1=REL_???:VALUE:REPEAT</programlisting>
            <para>
              <replaceable class="parameter">VALUE</replaceable> gives the maximum value of the event (default: 10)
            </para>
            <para>
              <replaceable class="parameter">REPEAT</replaceable>
              gives the number of milisecond to pass before the event
              is fired again (default: 5)
            </para>
            
            <programlisting>$ xboxdrv --ui-axismap X1=KEY_UP:KEY_DOWN:THRESHOLD</programlisting>
            <para>
              <replaceable class="parameter">KEY_UP</replaceable> gives the keycode to be send when the axis is moved up
            </para>
            <para>
              <replaceable class="parameter">KEY_DOWN</replaceable> gives the keycode to be send when the axis is moved down
            </para>
            <para>
              <replaceable class="parameter">THRESHOLD</replaceable> gives the threshold that triggers the sending of an event
            </para>

            <para>
              Just like <option>--ui-buttonmap</option>, you can
              also use shift keys in place of the XBOXAXIS:
            </para>
            <programlisting>$ xboxdrv --ui-axismap X1=ABS_X,LB+X1=ABS_RX</programlisting>
            <para>
              This allows you to send ABS_X events normally and ABS_RX
              events when the LB button is held down.
            </para>

            <bridgehead renderas="sect3">Calibration Filter</bridgehead>
            <para>
              See <option>--calibration</option>.
            </para>

            <bridgehead renderas="sect3">Sensitifity Filter</bridgehead>
            <para>
              See <option>--axis-sensitivity</option>.
            </para>

            <bridgehead renderas="sect3">Deadzone Filter</bridgehead>
            <para>
              Deadzone filter applies a deadzone to the current axis.
              If only <replaceable>MIN</replaceable> is provided, the
              parameter will be interpreted
              as <replaceable>-MIN:MIN:1</replaceable>. 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.
            </para>

            <bridgehead renderas="sect3">Relative Axis Filter</bridgehead>
            <para>
              See <option>--relative-axis</option>.
            </para>

            <bridgehead renderas="sect3">Response Curve Filter</bridgehead>
            <para>
              The response curve filter allows you to completely
              change the way an axis reacts. The filter takes a list
              of <replaceable>VALUES</replaceable> that are then
              linearly interpolated and spread across the full range
              of the axis. An example would look like this:
            </para>
            <programlisting><![CDATA[xboxdrv \
 --ui-axismap x1^resp:-32768:-4000:0:4000:32767=]]></programlisting>
            <para>
              Here the X1 axis is manipulated so that it will have a
              lower sensitivity in the center and a higher one on the
              outside.
            </para>

            <bridgehead renderas="sect3">Log Filter</bridgehead>
            <para>
              The log filter will output everything to stdout that
              goes through it to, this is useful for debugging the
              filter. A <replaceable>STRING</replaceable> can be
              provided as parameter that will be outputed before the
              event.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--alt-config</option> <replaceable class="parameter">FILE</replaceable></term>
          <listitem>
            <para>
              A shortcut for writing <option>--ui-new</option> <option>--config</option> <replaceable class="parameter">FILE</replaceable>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ui-clear</option></term>
          <listitem>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ui-new</option></term>
          <listitem>
            <para>
              Allows the creation of an alternative uinput
              configuration to which one can toggle at runtime by
              pressing the ui-toggle button (defaults to guide).
            </para>
            <programlisting><![CDATA[$ xboxdrv \
    --mouse \
  --ui-new 
    --ui-axismap X1=ABS_X,Y1=ABS_Y \
    --ui-buttonmap A=JS_0,B=JS_1]]></programlisting>
            <para>
              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.
            </para>
            <para>
              Not that <option>--ui-new</option> is currently limited
              to only configurations done
              with <option>--ui-buttonmap</option>
              and <option>--ui-axismap</option>, autofire, throttle
              emulation, deadzones and all other things can currently
              not be switched at runtime.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ui-toggle</option> <replaceable class="parameter">XBOXBTN</replaceable></term>
          <listitem>
            <para>
              Sets the button that will be used to toggle between
              different uinput configurations.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--guitar</option></term>
          <listitem>
            <para>
              Sets a predefined button and axis mapping for use with
              guitar controllers. This mainly gets rid of a few
              unnecesary buttons and axis not used by a guitar
              controller.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-m, --mouse</option></term>
          <listitem>
            <para>
              Lets the controller act as a mouse. It is indendical to:
            </para>
            <programlisting><![CDATA[$ 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"]]></programlisting>
            <para>
              You can customize it by the usual means, just make sure
              that <option>--mouse</option> comes before you
              customization options on the command line.
            </para>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--name DEVNAME</option></term>
          <listitem>
            <para>
              Changes the descriptive name the device will have
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--square-axis</option></term>
          <listitem>
            <para>
              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.
            </para>

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

        <varlistentry>
          <term><option>--four-way-restrictor</option></term>
          <listitem>
            <para>
              The <option>--four-way-restrictor</option> option allows 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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dpad-rotation</option> <replaceable class="parameter">DEGREE</replaceable></term>
          <listitem>
            <para>
              Allows you to rotate the
              dpad. <replaceable class="parameter">DEGREE</replaceable>
              must be a multiple of 45. This can be useful in
              isometric games where the playfield itself is rotated,
              thus a:
            </para>
            <programlisting>xboxdrv --dpad-rotation 45</programlisting>
            <para>
              Will give you controls that are relative to your
              character instead of your viewpoint.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--axis-sensitivty <replaceable class="parameter">AXIS=SENSITIVITY</replaceable></option>,...</term>
          <listitem>
            <para>The sensitive of an axis can be adjusted via --axis-sensitivty:</para>

            <programlisting>$ xboxdrv --axis-sensitivty X1=-2.0,Y1=-2.0</programlisting>

            <para>A value of 0 gives you the default linear sensitivity, values larger
              then 0 will give you heigher sensitivity, while values smaller then 0
              will give you lower sensitivity.</para>

            <para>Sensitivity works by applying:</para>

            <programlisting><![CDATA[t = 2 ** sensitivity;
pos = (1.0f - (1.0f - pos) ** t) ** (1 / t);]]></programlisting>

            <para>To the value of the axis, thus both the min and max position will
              always stay the same, only the values inbetween change.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--relative-axis AXIS=NUM,...</option></term>
          <listitem>
            <para>
              The function <option>--relative-axis</option> 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.
            </para>
            <para>
              Since the axis might be upside down, you might want to use
              the <option>--axismap</option> function to reverse it.
            </para>

            <programlisting>$ xboxdrv --relative-axis y2=64000 --axismap -y2=y2</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--autofire BUTTON=FREQUENCY</option></term>
          <listitem>
            <para>Autofire mapping allows you to let a button automatically fire with a
              given frequency in miliseconds:</para>
            
            <programlisting>$ xboxdrv --autofire A=250</programlisting>

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

            <programlisting>$ xboxdrv --autofire B=250 --buttonmap B=A</programlisting>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--calibration <replaceable class="parameter">CALIBRATIONSPEC</replaceable></option></term>
          <listitem>
            <para>
              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:
            </para>

            <programlisting>$ xboxdrv --calibration X2=-32768:0:32767</programlisting>

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

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

            <programlisting>xboxdrv --calibration AXIS=MIN:CENTER:MAX,...</programlisting>

            <para>Will cause the joystick device report maximum position when your
              stick is only moved half the way.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--axis-sensitivty <replaceable class="parameter">AXIS=SENSITIVITY</replaceable></option>,...</term>
          <listitem>
            <para>The sensitive of an axis can be adjusted via --axis-sensitivty:</para>

            <programlisting>$ xboxdrv --axis-sensitivty X1=-2.0,Y1=-2.0</programlisting>

            <para>A value of 0 gives you the default linear sensitivity, values larger
              then 0 will give you heigher sensitivity, while values smaller then 0
              will give you lower sensitivity.</para>

            <para>Sensitivity works by applying:</para>

            <programlisting><![CDATA[t = 2 ** sensitivity;
pos = (1.0f - (1.0f - pos) ** t) ** (1 / t);]]></programlisting>

            <para>To the value of the axis, thus both the min and max position will
              always stay the same, only the values inbetween change.</para>

          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--force-feedback</option></term>
          <listitem>
            <para>
              Enables the standard kernel force feedback interface. It
              is disabled by default as it causes trouble with some
              applications running in Wine.
            </para>
            <para>
              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.
            </para>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rumble-gain</option> <replaceable class="parameter">AMOUNT</replaceable></term>
          <listitem>
            <para>You can change the rumble strength via:</para>

            <programlisting>$ xboxdrv --rumble-gain 50%</programlisting>

            <para>Values larger then 100% are possible as well.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1> 

  <refsect1>
    <title>Running xboxdrv</title>
    <para>
      Plug in your Xbox360 gamepad and then unload the xpad driver via:
    </para>

    <programlisting>$ rmmod xpad</programlisting>

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

    <programlisting>blacklist xpad</programlisting>

    <para>
      Next you have to load the uinput kernel module which allows userspace
      programms to create input devices and the joydev module which gives
      you the <filename>/dev/input/jsX</filename> device:
    </para>

    <programlisting><![CDATA[$ modprobe uinput
$ modprobe joydev]]></programlisting>

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

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

    <programlisting>$ xboxdrv</programlisting>

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

    <programlisting>$ sudo xboxdrv</programlisting>

    <para>
      This will create /dev/input/js0 and allow you to access the gamepad
      from any game. To exit the driver press Ctrl-c. 
      If you have multiple wired controllers you need to start multiple instances
      of the xboxdrv driver and append the -i argument like this:
    </para>

    <programlisting>$ xboxdrv -i 1</programlisting>

    <para>
      If you have multiple wireless controller you need to start multiple
      instances of the xboxdrv driver and append the --wid argument like
      this:
    </para>

    <programlisting>$ xboxdrv --wid 1</programlisting>

    <para>
      You have to sync the wireless controller as usual.
    </para>

    <para>This will then use the second detected controller, see to see which id
      your controller has:</para>

    <programlisting>$ xboxdrv --list-controller</programlisting>

    <para>When everything works as expected it is recomment that you run xboxdrv
      with the silent option:</para>

    <programlisting>$ xboxdrv --silent</programlisting>

    <para>This will suppress the logging of events to the console and will
      gurantee that no uneccesarry CPU cycles are wasted.</para>

    <para>If you want to abuse the led or rumble of the gamepad for notification
      in scripts you can do see via:</para>

    <programlisting>$ xboxdrv --led 10 --rumble 30,30 --quit</programlisting>

    <para>This will cause a mild rumble and the led to rotate, you can stop it
      again via, which also happens to be the command you can use to stop
      your Xbox360 controller from blinking:</para>

    <programlisting>$ xboxdrv ---led 0 --rumble 0,0 --quit</programlisting>

    <para>For rumble to work make sure you have connected the
      controller to a USB port that has enough power, an unpowered USB
      hub might not work.</para>
  </refsect1>

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

    <refsect2>
      <title>evtest</title>
      <para>
        evtest lets you read raw input events from <filename>/dev/input/eventX</filename>. 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.
      </para>

      <para>
        evtest is available in the tools/ directory, you might also find it in
        your distribution.
      </para>
    </refsect2>

    <refsect2>
      <title>jstest</title>
      <para>
        jstest lets you read the output out of a joystick event device (/dev/input/js0).
      </para>

      <para>
        jstest is available in the tools/ directory or as part of your
        distribution.
      </para>
    </refsect2>

    <refsect2>
      <title>sdl-jstest</title>
      <para>
        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.
      </para>

      <para>
        Currently available via:
      </para>

      <programlisting>$ svn co svn://svn.berlios.de/windstille/trunk/sdl-jstest</programlisting>
    </refsect2>

    <refsect2>
      <title>xev</title>
      <para>
        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.
      </para>
      <para>
        xev is part of every Linux distribution, on Ubuntu its available via:
      </para>

      <programlisting>$ apt-get install x11-utils</programlisting>
    </refsect2>

    <refsect2>
      <title>jscalc</title>
      <para>
        Do not use this tool, for current day joysticks it doesn't do
        anything useful, so don't touch it, it won't fix your problems.
      </para>
    </refsect2>

    <refsect2>
      <title>mouse</title>
      <para>
        No tools for testing the output on /dev/input/mouseX are known.
      </para>
    </refsect2>

    <refsect2>
      <title>Note</title>
      <para>
        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.
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>
    <refsect2>
      <title>Keyboard Emulation</title>

      <para>The following configuration works for games that are
        played with keyboard, like Flash games or games that don't
        support a joystick. You might have to adjust the keybindings
        to fit the game:</para>

      <programlisting><![CDATA[$ 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]]></programlisting>
    </refsect2>

    <refsect2>
      <title>
        Prince of Persia or Tomb Raider Anniversary in Wine
      </title>

      <para>
        Start <command>xboxdrv</command> with:
      </para>

      <programlisting><![CDATA[$ xboxdrv --trigger-as-button -s ]]></programlisting>

      <para>The triggers are not regonized in these games when they
        are analog, so we have to handle them as buttons.</para>
    </refsect2>

    <refsect2>
      <title>Fighting games with Datel Arcade Pro Joystick:</title>

      <para>The left and right trigger get turned into digital buttons. All axis
        except the dpad are ignored. RB and RT are mapped to act as if buttons
        1,2 and 3 are pressed simultaniously (useful for some special
        attacks). Instead of using the native button names, the
        1,2,3,... aliases are used, which makes things easier to edit:</para>

      <programlisting><![CDATA[$ xboxdrv --dpad-only \
  --trigger-as-button  \
  --buttonmap lb=1,x=2,y=3,lt=4,a=5,b=6,rb=1,rb=2,rb=3,rt=4,rt=5,rt=6]]></programlisting>
    </refsect2>

    <refsect2>
      <title>CH Flightstick emulation in Dosbox:</title>
      <para>In <filename>dosbox.conf</filename> set:</para>

      <programlisting><![CDATA[[joystick]
joysticktype = ch]]></programlisting>

      <para>Start xboxdrv with:</para>

      <programlisting><![CDATA[$ xboxdrv -s \
  --trigger-as-zaxis --square-axis \
  --relative-axis y2=64000 --axismap -y2=x2,x2=y2]]></programlisting>

      <para>Your right analog stick will act as trottle control, the trigger as
        rudder.</para>
    </refsect2>

    <refsect2>
      <title>Sauerbraten</title>
      <para>
        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.
      </para>

      <programlisting><![CDATA[$ 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]]></programlisting>
    </refsect2>

    <refsect2>
      <title>Warsow</title>

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

      <programlisting><![CDATA[$ 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]]></programlisting>
    </refsect2>

    <refsect2>
      <title>Using mouse emulation and joystick at the same time</title>
      <para>
        To use mouse emulation and joystick at the same time you have
        to register two uinput configuration with xboxdrv, this works
        via:
      </para>
      <programlisting><![CDATA[$ xboxdrv \
  --ui-new --mouse
]]></programlisting>
      <para>
        The <option>--ui-new</option> 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.
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>SDL Notes</title>
    <para>
      To let SDL know which axis act as a hat and which act as normal axis
      you have to set an environment variable:
    </para>

    <programlisting><![CDATA[
$ SDL_LINUX_JOYSTICK="'Xbox Gamepad (userspace driver)' 6 1 0"
$ export SDL_LINUX_JOYSTICK]]></programlisting>

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

    <programlisting><![CDATA[
$ SDL_JOYSTICK_DEVICE="/dev/input/js0"
$ export SDL_JOYSTICK_DEVICE]]></programlisting>

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

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

    <itemizedlist>
      <listitem>
        <para><ulink url="ftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars">ftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars</ulink></para>
      </listitem>
    </itemizedlist>

    <variablelist>
      <varlistentry>
        <term>SDL_LINUX_JOYSTICK</term>
        <listitem>
          <para>
	    Special joystick configuration string for linux. The format is
	    <option>"name numaxes numhats numballs"</option>
	    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.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>SDL_JOYSTICK_DEVICE</term>
        <listitem>
          <para>
	    Joystick device to use in the linux joystick driver, in addition to the usual: <filename>/dev/js*</filename>, <filename>/dev/input/event*</filename>, <filename>/dev/input/js*</filename>
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Troubleshooting</title>
    <refsect2>
      <title>"No Xbox or Xbox360 controller found"</title>
      <para>
        This means that either your controller isn't plugged in or not
        recognized by the driver. To fix this you need to know the idVendor
        and the idProduct numbers, which you can find out via:
      </para>

      <programlisting><![CDATA[$ lsusb -v]]></programlisting>

      <para>Once done you can try to add them to this array in <filename>xpad_device.cpp</filename>:</para>

      <programlisting><![CDATA[XPadDevice xpad_devices[] = { ... }]]></programlisting>

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

      <para>
        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.
      </para>
    </refsect2>

    <refsect2>
      <title>"Unknown data: bytes: 3 Data: ..."</title>
      <para>
        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 <email>grumbel@gmx.de</email> and include the output
        of:
      </para>

      <programlisting><![CDATA[$ lsusb -v]]></programlisting>

      <para>Along with all the "Unknown data" lines you get. </para>
    </refsect2>

    <refsect2>
      <title>Program starts and then just does nothing</title>
      <para>
        This is what the program is supposed to do. After you started it, it
        will give you basically two devices, a new /dev/input/eventX and a
        /dev/input/jsX. You can access and test your controller with jstest
        and evtest applications (available from your distribution or in the
        tools/ subdirectory). Or in case you want just see if your driver is
        working correctly you can pass the -v option:
      </para>

      <programlisting><![CDATA[$ xboxdrv -v]]></programlisting>

      <para>
        This will cause the driver to output all the events that it received
        from the controller.
      </para>
    </refsect2>

    <refsect2>
      <title>"Error: No stuitable uinput device found"</title>
      <para>
        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.
      </para>
      <para>
        Before reporting this as a bug make sure you have tested if the driver
        itself works with:
      </para>

      <programlisting><![CDATA[$ xboxdrv --no-uinput -v]]></programlisting>

    </refsect2>
    
    <refsect2>
      <title>The wireless controller doesn't work</title>
      <para>
        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.
      </para>
    </refsect2>
  </refsect1>

  <refsect1 id="keyboardemulation">
    <title>Keyboard Emulation</title>
    <para>
      When you try to let xboxdrv send a keyboard events
      via <option>--ui-buttonmap</option>
      or <option>--ui-axismap</option> 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 <filename>/etc/hal/fdi/preprobe/xboxdrv.fdi</filename>
      containing:
    </para>

    <programlisting><![CDATA[
<?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>]]></programlisting>

    <para>
      This will tell HAL and later Xorg that xboxdrv acts as keyboard.
    </para>
  </refsect1>

  <refsect1>
    <title>Xorg Trouble</title>
    <para>
      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 <filename>/etc/hal/fdi/policy/preferences.fdi</filename>
      is the recommont one.
    </para>

    <refsect2>
      <title>Temporary workaround using hal-device</title>
      <para>
        Get the device id from hal:
      </para>

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

      <para>Then remove the device from hal with:</para>

      <programlisting>$ hal-device -r $DEVICEID</programlisting>
    </refsect2>

    <refsect2>
      <title>Temporary workaround using xinput</title>
      <para>
        Second workaround works with xinput:
      </para>

      <programlisting><![CDATA[$ xinput list
$ xinput set-int-prop $DEVICEID 'Device Enabled' 32 0]]></programlisting>
    </refsect2>

    <refsect2>
      <title>Permanent workaround using .fdi files</title>
      <para>
        The former two workarounds are just temporary and have to be redone
        after each start of xboxdrv, the last workaround is a permanent one:
      </para>
      <para>
        You have to edit:
      </para>

      <para><filename>/etc/hal/fdi/policy/preferences.fdi</filename></para>

      <para>And insert the following lines:</para>

      <programlisting><![CDATA[
<match key="input.product" string="Xbox Gamepad (userspace driver)">
  <remove key="input.x11_driver" />
</match>]]></programlisting>
    </refsect2>

    <refsect2>
      <title>Permanent workaround by disabling device auto detection</title>
      <para>
        A fourth workaround involved disabling the autodetection of Xorg
        completly, you can do that by adding the following lines to
        <filename>/etc/X11/xorg.conf</filename>:</para>

      <programlisting><![CDATA[Section "ServerFlags"
  Option "AutoAddDevices" "False"
EndSection]]></programlisting>

      <para>
        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.
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Wacom Trouble</title>
    <para>
      In recent kernels a Wacom graphic tablet creates a joystick device, so
      xboxdrv or any other real joysticks ends up as <filename>/dev/input/js1</filename> instead
      of <filename>/dev/input/js0</filename>. In many games this causes the joystick to not
      function any more.
    </para>

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

    <programlisting>$ sudo ln -sf /dev/input/js1 /dev/input/js0</programlisting>

    <para>
      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. 
    </para>
  </refsect1>

  <refsect1>
    <title>uinput Trouble</title>
    <para>
      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:
    </para>
    <para>
      <filename>/etc/udev/rules.d/55-permissions-uinput.rules</filename>
    </para>
    <para>
      With the content:
    </para>
    <programlisting>KERNEL=="uinput", MODE="0660", GROUP="root"</programlisting>
  </refsect1>

  <refsect1>
    <title>Wine Trouble</title>
    <para>
      When using the Xbox360 gamepad in Wine it is not specially handled as
      Xbox360 gamepad, this means games will not display the proper button
      labels, but just numbers (i.e. 'Btn1' instead of 'A' for
      example). Aside from that it should work fine.
    </para>
    <para>
      XInput support (the DirectInput replacment, not the Xorg xinput)
      is as of August 2010 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.
    </para>
  </refsect1>

  <refsect1>
    <title>Force Feedback Programming</title>
    <para>
      For documentation on the FF interface see:
    </para>

    <itemizedlist>
      <listitem><para><ulink url="http://github.com/github/linux-2.6/blob/f3b8436ad9a8ad36b3c9fa1fe030c7f38e5d3d0b/Documentation/input/ff.txt">http://github.com/github/linux-2.6/blob/f3b8436ad9a8ad36b3c9fa1fe030c7f38e5d3d0b/Documentation/input/ff.txt</ulink></para></listitem>
      <listitem><para><filename>/usr/include/linux/input.h</filename></para></listitem>
    </itemizedlist>

    <para>
      Additional, non Linux related, force feedback related
      information can be found at:
    </para>

    <itemizedlist>
      <listitem><para><ulink url="http://www.immersion.com/developer/downloads/ImmFundamentals/HTML/"></ulink></para></listitem>
      <listitem><para><ulink url="http://msdn.microsoft.com/en-us/library/bb219655(VS.85).aspx"></ulink></para></listitem>
    </itemizedlist>

    <para><command>fftest</command> is an application you can use to test the force feedback
      interface.</para>

    <para>Force feedback is disabed by default since it seems to causes trouble
      in certain application, namely "Tomb Raider: Legend" when run in Wine
      it crashes at startup when rumble is enabled, while it works perfectly
      normal when rumble is disabled.</para>

    <para>"Tomb Raider: Anniversary" running in Wine seems to work together with
      xboxdrv and rumble, but hasn't been intensivly tested.</para>
  </refsect1>

  <refsect1>
    <title>Writing Start-Up Scripts for Games</title>
    <para>When you want configurability and automatic launching, it is recomment
      that you write little startup scripts for your games, such as this:</para>

    <programlisting><![CDATA[#!/bin/sh

# Start xboxdrv and remember its PID in the variable XBOXPID
xboxdrv --trigger-as-button -s &amp;
XBOXPID=$!

# Give xboxdrv a second to startup and create the device
sleep 1

# Launch your favorite game
your_favorite_game

# Kill xboxdrv and wait for it to finish
kill $XBOXPID
wait $XBOXPID

# EOF #]]></programlisting>

    <para>That way you can individually configure every game and not
      have to worry about launching xboxdrv manually.</para>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
      X11 keysyms might not work correctly in <option>--ui-buttonmap a=XK_Foobar</option>
      when Foobar is mapped to multiple keycodes in the keymap. 
    </para>

    <para>Workaround: Use <keysym>KEY_</keysym> instead or cleanup your keymap</para>

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

    <para>
      Workaround: Kill the app that uses xboxdrv before xboxdrv itself.
    </para>

    <para>
      Report bugs to Ingo Ruhnke <email>grumbel@gmx.de</email>.
    </para>
  </refsect1>

  <refsect1>
    <title>Copyright</title>
    <para>
      Copyright © 2010 Ingo Ruhnke <email>grumbel@gmx.de</email>
      License GPLv3+: GNU GPL version 3 or later
      <ulink url="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.
    </para>
  </refsect1>

  <refsect1>
    <title>See also</title>
    <para>
      <citerefentry>
        <refentrytitle>xboxdrv-daemon</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>, 
      <citerefentry>
        <refentrytitle>evtest</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>, 
      <citerefentry>
        <refentrytitle>jstest</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>, 
      <citerefentry>
        <refentrytitle>xev</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>fftest</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>lsusb</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>