2279 lines
85 KiB
XML
2279 lines
85 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 choice="opt" rep="repeat">OPTION</arg>
|
|
<arg choice="opt">--</arg>
|
|
<arg choice="opt">COMMAND</arg>
|
|
<arg choice="opt">ARGUMENTS</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 to use the
|
|
configurability of <command>xboxdrv</command> on regular PC
|
|
joysticks, keyboards and mice 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>-D</option>, <option>--daemon</option></term>
|
|
<listitem>
|
|
<para>
|
|
Run xboxdrv as daemon. This option hasn't been tested
|
|
much and it is not recommented to be used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-c</option>, <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>--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>
|
|
<para>
|
|
To load multiple configuration options use:
|
|
</para>
|
|
<programlisting><![CDATA[xboxdrv --config first.ini --alt-config second.ini --alt-config third.ini]]></programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o</option>, <option>--option</option> <replaceable class="parameter">NAME=VALUE</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Set an option as if it would come from a config file from the command line.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--write-config</option> <replaceable class="parameter">FILE</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Write an example configuration file to <replaceable class="parameter">FILE</replaceable>.
|
|
</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>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Evdev Option</title>
|
|
<variablelist>
|
|
<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>-q</option>, <option>--quit</option></term>
|
|
<listitem>
|
|
<para>
|
|
Exit xboxdrv after setting LED or rumble values.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Chatpad Options (experimental)</title>
|
|
<para>
|
|
Chatpad support is still experimental. Basic keyboard usage
|
|
will work, there is however currently no support for
|
|
customization or the green and orange key modifiers.
|
|
</para>
|
|
<para>
|
|
Starting xboxdrv multiple times in a row with
|
|
the <option>--chatpad</option> option can crash the
|
|
controller. Unplugging it and plugging it back in should reset
|
|
it.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--chatpad</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enables the support for the Xbox360 Chatpad. WARNING:
|
|
This is preliminary code, it will crash your gamepad
|
|
when xboxdrv is started multiple times and won't provide
|
|
proper keymapping for any of the umlauts and special
|
|
characters.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--chatpad-no-init</option></term>
|
|
<listitem>
|
|
<para>
|
|
This will start chatpad support with out sending the
|
|
init sequence, thus potentially avoiding crashing the
|
|
controller if xboxdrv is started multiple times.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--chatpad-debug</option></term>
|
|
<listitem>
|
|
<para>
|
|
Output raw chatpad data to the stdout for debugging purpose.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Headset Options (experimental, Xbox360 USB only)</title>
|
|
<para>
|
|
Xboxdrv does not support the headset, the options below are
|
|
for developers only and will dump raw headset data, not .wav
|
|
files.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--headset</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enable headset support and dump incomming data to stdout.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--headset-dump</option> <replaceable class="parameter">FILE</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Enable headset support and dump incomming data to FILE.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--headset-play</option> <replaceable class="parameter">FILE</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Enable headset support and send FILE to the headset for playback.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Force Feedback</title>
|
|
<variablelist>
|
|
<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 and will
|
|
amplify small rumble commands, rumble commands already
|
|
at the maximum will stay unchanged.
|
|
</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>-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>-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>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Uinput Preset Configuration Options</title>
|
|
<para>
|
|
The following options are simple shortcuts for common
|
|
configurations that can be accomplished
|
|
by <option>--ui-buttonmap</option>
|
|
and <option>--ui-axismap</option>.
|
|
</para>
|
|
<variablelist>
|
|
<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>--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 your
|
|
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>--mimic-xpad</option></term>
|
|
<listitem>
|
|
<para>
|
|
Causes xboxdrv to use the same axis and button names as the xpad kernel driver.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Uinput Configuration Options</title>
|
|
<variablelist>
|
|
<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>--name DEVNAME</option></term>
|
|
<listitem>
|
|
<para>
|
|
Changes the descriptive name the device will have
|
|
</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-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-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>--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>
|
|
<para>
|
|
For documentation on the filters you can apply to events
|
|
see <link linkend="buttonfilter" endterm="buttonfilter.title" />.
|
|
</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>
|
|
|
|
<para>
|
|
For information on how to use axis filters, see <link linkend="axisfilter" endterm="axisfilter.title" />.
|
|
</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=-1.0,Y1=-1.0</programlisting>
|
|
|
|
<para>
|
|
A value of 0 gives you the default linear sensitivity,
|
|
values larger then 0 will give you higher sensitivity,
|
|
while values smaller then 0 will give you lower
|
|
sensitivity. Sensitivity values in the range of [-1, 1]
|
|
will generally give good results, everything beyond that
|
|
won't be of much practical use.
|
|
</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, this means that both the
|
|
minimum value and the maximum value of the axis will
|
|
always stay the same, just the response inbetween
|
|
changes.
|
|
</para>
|
|
<para>
|
|
For a complete freeform way to change the axis response
|
|
see the <option>Response Curve Filter</option>.
|
|
</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>
|
|
</variablelist>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 id="inputfilter">
|
|
<title id="inputfilter.title">Input Filter</title>
|
|
<para>
|
|
Input filter allow to manipulate the events that come from the
|
|
controller. They can be used
|
|
on <option>--buttonmap</option>, <option>--axismap</option>, <option>--ui-buttonmap</option>
|
|
and <option>--ui-axismap</option>. The difference between the
|
|
two is that the <option>--ui-...</option> versions applies to
|
|
the uinput events, while the other version applies to Xbox360
|
|
controller events.
|
|
</para>
|
|
<refsect2 id="buttonfilter">
|
|
<title id="buttonfilter.title">Button Filter</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>tog</option>, <option>toggle</option></term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>inv</option>, <option>invert</option></term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>auto</option>, <option>autofire</option>:<replaceable>RATE</replaceable>:<replaceable>DELAY</replaceable></term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>log</option>:<replaceable>STRING</replaceable></term>
|
|
<listitem>
|
|
<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>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2 id="axisfilter">
|
|
<title id="axisfilter.title">Axis Filter</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>cal</option>, <option>calibration</option>:<replaceable>MIN</replaceable>:<replaceable>CENTER</replaceable>:<replaceable>MAX</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
See <option>--calibration</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>sen</option>, <option>sensitivity</option>:<replaceable>SENSITIVITY</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
See <option>--axis-sensitivity</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>dead</option>,
|
|
<option>deadzone</option>:<replaceable>VALUE</replaceable>,
|
|
<option>deadzone</option>:<replaceable>MIN</replaceable>:<replaceable>CENTER</replaceable>:<replaceable>MAX</replaceable>
|
|
</term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>rel</option>, <option>relative</option>:<replaceable>SPEED</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
See <option>--relative-axis</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>resp</option>, <option>response</option>:<replaceable>VALUES</replaceable>:...</term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>log</option>:<replaceable>STRING</replaceable></term>
|
|
<listitem>
|
|
<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>
|
|
</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 &
|
|
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>
|