1569 lines
58 KiB
XML
1569 lines
58 KiB
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>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</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>--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>--no-extra-devices</option></term>
|
|
<listitem>
|
|
<para>
|
|
Normally xboxdrv will create an extra device for
|
|
keyboard emulation and mouse emulation when it detects a
|
|
button mapping that requires that. If this option is
|
|
set, it will not do that and instead dump all the
|
|
buttons into the joystick device.
|
|
</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>-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>
|
|
</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.
|
|
</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 ] "=" ( RELSPEC | BTNSPEC ) ;
|
|
RELSPEC = [ DEVICEID "-" ] "REL_" [ ":" [ VALUE ] [ ":" REPEAT ] ] ;
|
|
BTNSPEC = [ DEVICEID "-" ] ( ( "BTN_" NAME ) | ( "KEY_" NAME ) ) { "+" BTNSPEC } ;
|
|
XBOXBUTTON = "a" | "b" | "x" | "y" | "lb" | "rb" | "lt" | "rt" |
|
|
"tl" | "tr" | "start" | "select" | "back" | "guide" | "black" | "white" ;
|
|
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>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--ui-axismap</option> <replaceable class="parameter">UIAXISSPEC,...</replaceable></term>
|
|
<listitem>
|
|
<programlisting><![CDATA[UIAXISSPEC = XBOXAXIS "=" ( RELSPEC | BTNSPEC | ABSSPEC ) ;
|
|
BTNSPEC = "KEY_" NAME ":" "KEY_" NAME ":" THRESHOLD ;
|
|
RELSPEC = "REL_" NAME ":" VALUE ":" REPEAT ;
|
|
ABSSPEC = "ABS_" NAME ;
|
|
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>
|
|
</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>-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 is by the usal 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 movment 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 joysticks, which had a square range and
|
|
allowed x and y to be handled completly indepened.
|
|
</para>
|
|
|
|
<para>Some old games (i.e. DOS stuff) require a square movement range and
|
|
will thus 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
|
|
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
|
|
have to adjust the keybindings to fit the game:</para>
|
|
|
|
<programlisting><![CDATA[$ xboxdrv \
|
|
--ui-clear \
|
|
--dpad-as-button \
|
|
--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>
|
|
</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). Asside from that it should work fine.
|
|
</para>
|
|
<para>
|
|
Xinput support (the DirectInput replacment, not the Xorg xinput) might
|
|
not work properly or not at all.
|
|
</para>
|
|
<para>
|
|
It is currently unknown if this can be fixed by xboxdrv or if it
|
|
requires patches to Wine.
|
|
</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>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>
|