From 8e36d9692abaab56c969cda14496c9ed22438e30 Mon Sep 17 00:00:00 2001 From: Ingo Ruhnke <grumbel@gmx.de> Date: Fri, 28 Jan 2011 16:40:39 +0100 Subject: [PATCH] Improved and updated the man-page --- TODO | 15 +- doc/xboxdrv.1 | 322 ++++++++++++++++------------ doc/xboxdrv.xml | 553 ++++++++++++++++++++++++++++-------------------- 3 files changed, 518 insertions(+), 372 deletions(-) diff --git a/TODO b/TODO index 6538b63..d6bcdbc 100644 --- a/TODO +++ b/TODO @@ -42,6 +42,15 @@ $ dput my-ppa ../xboxdrv_0.7.1-1~lucid1_source.changes Stuff to do before 0.7.1 release: ================================= +* improve output in daemon mode, when --quiet is not given print the number of allocated controller slots + +* [ERROR] XboxdrvDaemon::process_match(): no free controller slot found, controller will be ignored + - should include info about what controller is ignored + +* update debian package description + +* update the later man page sections, they are pretty much out of date + * write a tutorial * write lots of well documented examples @@ -71,8 +80,10 @@ Stuff to do before 0.7.1 release: * match again sysname could make sense, seems somewhat constant: "5-2" Xbox1 controller results in "5-2.1", due to being really two devices - * add match rule for usb iSerial (might be the only way to tell - similar devices appart) + * redesign match rules and only use single argument? would make + match group more logical: + + --match-group vendor=045f,product=028f * fix bugs that pop up diff --git a/doc/xboxdrv.1 b/doc/xboxdrv.1 index efc6c1f..4dc5049 100644 --- a/doc/xboxdrv.1 +++ b/doc/xboxdrv.1 @@ -37,7 +37,7 @@ well as more complicated things like mouse and keyboard emulation, auto-fire and throttle control emulation. .PP It is also possible for \fBxboxdrv\fR to read input -data directly from an event device, this allows to use the +data directly from an event device, this allows the use of the configurability of \fBxboxdrv\fR on regular PC joysticks, keyboards and mice and thus lets \fBxboxdrv\fR serve a similar purpose @@ -47,7 +47,9 @@ option \*(T<\fB\-\-evdev\fR\*(T> below for more information. When a \*(T<\fBCOMMAND\fR\*(T> 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. +in wrapper scripts. See the section +[Writing Start-Up Scripts for Games] +for more information. .SH OPTIONS .SS "GENERAL OPTIONS" .TP @@ -1285,6 +1287,7 @@ See \*(T<\fB\-\-square\-axis\fR\*(T>. \*(T<\fBrotate\fR\*(T>=\fIXAXIS\fR:\fIYAXIS\fR:\fIDEGREE\fR:\fIMIRROR\fR Rotates the stick given by \fIXAXIS\fR and \fIYAXIS\fR by \fIDEGREE\fR and optionally \fIMIRRORS\fR it. .SH "RUNNING XBOXDRV" +.SS "USING A SINGLE CONTROLLER" Plug in your Xbox360 gamepad and then unload the xpad driver via: .PP .nf @@ -1298,9 +1301,10 @@ If you want to permanently unload it add the following line to \*(T<blacklist xpad\*(T> .fi .PP -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 \*(T<\fI/dev/input/jsX\fR\*(T> device: +Next you have to load the uinput kernel module which allows +userspace programms to create virtual input devices and the +joydev module handles the \*(T<\fI/dev/input/jsX\fR\*(T> +devices: .PP .nf \*(T<$ modprobe uinput @@ -1325,18 +1329,36 @@ should often be enough) start the driver as root via: \*(T<$ sudo xboxdrv\*(T> .fi .PP -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: +This will create /dev/input/js0 and allow you to access the +gamepad from any game. To exit the driver press Ctrl-c. +.PP +By default xboxdrv will echo all controller events to the +console, this makes it easy to see if things are properly +working, but will eat a lot of CPU, thus it is strongly +recomment to disabled that output with +the \*(T<\fB\-\-silent\fR\*(T> option. +.PP +The trigger buttons are handled by xboxdrv normally as axis, +giving you analog feedback, while this reproduces the Xbox360 +controller the most accurately, it will confuse many and only +be useful in a few, racing games mainly. So in the majority of +cases it is recomment to change the triggers to regular buttons via: +.PP +.nf +\*(T<$ xboxdrv \-\-trigger\-as\-button\*(T> +.fi +.SS "USING MULTIPLE CONTROLLER" +If you want to use multiple wired controllers you need to start +multiple instances of the xboxdrv driver and append the -i +argument to select the appropriate controller like this: .PP .nf \*(T<$ xboxdrv \-i 1\*(T> .fi .PP -If you have multiple wireless controller you need to start multiple -instances of the xboxdrv driver and append the --wid argument like -this: +If you have multiple wireless controller you need to start +multiple instances of the xboxdrv driver and append +the \*(T<\fB\-\-wid\fR\*(T> option like this: .PP .nf \*(T<$ xboxdrv \-\-wid 1\*(T> @@ -1344,41 +1366,56 @@ this: .PP You have to sync the wireless controller as usual. .PP -This will then use the second detected controller, see to see which id -your controller has: +To see a list of all the controllers that xboxdrv detects +being connected to your system use: .PP .nf \*(T<$ xboxdrv \-\-list\-controller\*(T> .fi -.PP -When everything works as expected it is recomment that you run xboxdrv -with the silent option: +.SS "HOTPLUGGING AND XBOXDRV DAEMON" +To allow hotplugging of gamepads xboxdrv has to be run in +daemon mode. This is accomplished with +the \*(T<\fB\-\-daemon\fR\*(T> option: .PP .nf -\*(T<$ xboxdrv \-\-silent\*(T> +\*(T<$ xboxdrv \-\-daemon\*(T> .fi .PP -This will suppress the logging of events to the console and will -gurantee that no uneccesarry CPU cycles are wasted. +When launched in daemon mode xboxdrv will listen to udev +events and thus be notified whenever a new USB device gets +plugged into the computer. It will then match that device +against its list of supported devices and launch a separate +thread to handle that gamepad. .PP -If you want to abuse the led or rumble of the gamepad for notification -in scripts you can do see via: +Note that xboxdrv will not allow an arbitarily large number of +controllers to be used in that mode, it can only handle as +many controllers as you have allocated controller slots at +startup. New slots can be allocated +with \*(T<\fB\-\-next\-controller\fR\*(T> and by default one +slot is always allocated, thus to support three controller you +would run it with: .PP .nf -\*(T<$ xboxdrv \-\-led 10 \-\-rumble 30,30 \-\-quit\*(T> +\*(T<$ xboxdrv \-\-daemon \-\-next\-controller \-\-next\-controller\*(T> .fi .PP -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: +Each controller slot can be configured individually and you +can limit which gamepad gets assigned to which slot with +the \*(T<\fB\-\-match\fR\*(T> option. +.PP +Note that xboxdrv will create the virtual uinput devices on +startup, not when a gamepad gets plugged in, this allows to +plug in gamepads even after a game or an application like XBMC +has already been launched and still have it all function +properly. +.PP +In daemon mode xboxdrv can be detached from the current shell +via \*(T<\fB\-\-detach\fR\*(T>, to get a handle on it to kill +it you can write its pid via the \*(T<\fB\-\-pid\-file\fR\*(T>: .PP .nf -\*(T<$ xboxdrv \-\-\-led 0 \-\-rumble 0,0 \-\-quit\*(T> +\*(T<$ sudo xboxdrv \-\-daemon \-\-detach \-\-pid\-file /var/run/xboxdrv.pid\*(T> .fi -.PP -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. .SH TESTING Knowing how to test a xboxdrv configuration is absolutely crucial in understanding what is wrong in a given setup. Testing the @@ -1394,23 +1431,26 @@ 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. .PP -evtest is available in the tools/ directory, you might also find it in -your distribution. +evtest is available in the tools/ directory or as part of your +distribution in the package \*(T<\fIevtest\fR\*(T>. your +distribution. .SS JSTEST jstest lets you read the output out of a joystick event device (/dev/input/js0). .PP jstest is available in the tools/ directory or as part of your -distribution. +distribution \*(T<\fIjoystick\fR\*(T>. .SS SDL-JSTEST sdl-jstest lets you see events as games using SDL see them. This is very important when you want to set and test the SDL_LINUX_JOYSTICK environment variables. .PP -Currently available via: +It is currently available via: .PP .nf \*(T<$ svn co svn://svn.berlios.de/windstille/trunk/sdl\-jstest\*(T> .fi +.PP +Or from the same Ubuntu PPA that also contains xboxdrv in the package \*(T<\fIsdl\-jstest\fR\*(T>. .SS XEV xev lets you see the events that Xorg sees. Note however that you might not see all events, since some will be grapped by your Window @@ -1421,9 +1461,18 @@ xev is part of every Linux distribution, on Ubuntu its available via: .nf \*(T<$ apt\-get install x11\-utils\*(T> .fi -.SS JSCALC -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. +.SS "JSCALC AND JSCALIBRATOR" +Both of these tools lets you calibrate your gamepad, however +with pretty much all current gamepads this is no longer +needed and actually harmful as it might overwrite a perfectly +good working configuration with a broken one (unplugging the +gamepad or a reboot will fix that). So avoid them unless you +clearly understand the issues of using them. +.PP +If your gamepad produces incorrect data and you do want to +calibrate it you might want to check out the +option \*(T<\fB\-\-calibration\fR\*(T>, which lets you tweak +the way xboxdrv interprets your gamepad data. .SS MOUSE No tools for testing the output on /dev/input/mouseX are known. .SS NOTE @@ -1457,12 +1506,15 @@ 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: +1,2,3,... aliases are used, which makes things a little easier to read: .PP .nf -\*(T<$ xboxdrv \-\-dpad\-only \e - \-\-trigger\-as\-button \e - \-\-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\*(T> +\*(T<$ xboxdrv \e + \-\-dpad\-only \e + \-\-trigger\-as\-button \e + \-\-buttonmap lb=1,x=2,y=3,lt=4,a=5,b=6 \e + \-\-buttonmap rb=1,rb=2,rb=3 \e + \-\-buttonmap rt=4,rt=5,rt=6\*(T> .fi .SS "CH FLIGHTSTICK EMULATION IN DOSBOX:" In \*(T<\fIdosbox.conf\fR\*(T> set: @@ -1525,6 +1577,32 @@ 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. +.SH "WRITING START-UP SCRIPTS FOR GAMES" +When you want full game specific configurability and automatic +launching of xboxdrv, it is easiest to write little startup +scripts for your games that will launch xboxdrv, launch your +game and then when the game is finished tear down xboxdrv: +.PP +.nf +\*(T<#!/bin/sh + +exec xboxdrv \e + \-\-trigger\-as\-button \-s \e + \-\- \e + your_favorite_game + +# EOF #\*(T> +.fi +.PP +Here \*(T<\fIyour_favorite_game\fR\*(T> is the executable +of your game and is passed to xboxdrv as last argument. This +will cause xboxdrv to start the game and keep running as long as +the game is running, when the game is done, xboxdrv will quit +automatically. +.PP +If you want to pass parameters to the game you have to add +a \*(T<\fB\-\-\fR\*(T> separator, as otherwise your options to +the game would be eaten up by xboxdrv. .SH "SDL NOTES" To let SDL know which axis act as a hat and which act as normal axis you have to set an environment variable: @@ -1564,15 +1642,16 @@ SDL_JOYSTICK_DEVICE Joystick device to use in the linux joystick driver, in addition to the usual: \*(T<\fI/dev/js*\fR\*(T>, \*(T<\fI/dev/input/event*\fR\*(T>, \*(T<\fI/dev/input/js*\fR\*(T> .SH TROUBLESHOOTING .SS "\(dqNO XBOX OR XBOX360 CONTROLLER FOUND\(dq" -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: +This means that either your controller isn't plugged in or is +not recognized by the driver. To fix this you need to know the +idVendor and the idProduct numbers, which you can find out +via: .PP .nf \*(T<$ lsusb \-v\*(T> .fi .PP -Once done you can try to add them to this array in \*(T<\fIxpad_device.cpp\fR\*(T>: +Once done you can try to add them to this array in \*(T<\fIsrc/xpad_device.cpp\fR\*(T>: .PP .nf \*(T<XPadDevice xpad_devices[] = { ... }\*(T> @@ -1600,20 +1679,6 @@ of: .fi .PP Along with all the "Unknown data" lines you get. -.SS "PROGRAM STARTS AND THEN JUST DOES NOTHING" -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: -.PP -.nf -\*(T<$ xboxdrv \-v\*(T> -.fi -.PP -This will cause the driver to output all the events that it received -from the controller. .SS "\(dqERROR: NO STUITABLE UINPUT DEVICE FOUND\(dq" 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 @@ -1629,7 +1694,7 @@ itself works with: 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. -.SH "KEYBOARD EMULATION" +.SS "KEYBOARD EMULATION" When you try to let xboxdrv send a keyboard events via \*(T<\fB\-\-ui\-buttonmap\fR\*(T> or \*(T<\fB\-\-ui\-axismap\fR\*(T> Xorg must register the device @@ -1652,7 +1717,50 @@ containing: .fi .PP This will tell HAL and later Xorg that xboxdrv acts as keyboard. -.SH "XORG TROUBLE" +.SS "WACOM ISSUES" +In some older kernels a Wacom graphic tablet creates a +joystick device, so xboxdrv or any other real joysticks ends +up as \*(T<\fI/dev/input/js1\fR\*(T> instead +of \*(T<\fI/dev/input/js0\fR\*(T>. In many games this +causes the joystick to not function any more. +.PP +A temporary workaround for this is to simply delete the joystick +device js0 and replace it with a symbolic link js1 via: +.PP +.nf +\*(T<$ sudo ln \-sf /dev/input/js1 /dev/input/js0\*(T> +.fi +.PP +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. +.PP +In newer kernels this issue is fixed. +.SS "UINPUT ISSUES" +On Ubuntu 9.04 the permissions of the uinput device have +changed to 0640, meaning only root has access to the device. +To change this back so that users in the group root have +access the device and in turn can run xboxdrv without sudo you +have to create a file +called \*(T<\fI/etc/udev/rules.d/55\-permissions\-uinput.rules\fR\*(T> +with the content: +.PP +.nf +\*(T<KERNEL=="uinput", MODE="0660", GROUP="root"\*(T> +.fi +.SS "WINE ISSUES" +When using the Xbox360 gamepad in Wine it is not specially +handled as Xbox360 gamepad, but as generic DirectInput gamepad. +This means games will not display the proper button labels, but +just numbers (i.e. 'Btn1' instead of 'A' for example). Aside +from that it should work fine. +.PP +XInput support (the Microsoft DirectInput replacment, not the +Xorg xinput) is as of January 2011 not implemented in Wine, so +games that require XInput and don't have an DirectInput fallback +will not work with a Xbox360 controller, unofficial patches +however do exist. +.SH "XORG ISSUES" If you start xboxdrv and instead of having a fully working joystick, you end up controlling the mouse that might be due to recent changes in Xorg and its device hotplug handling. There @@ -1711,45 +1819,6 @@ 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. -.SH "WACOM TROUBLE" -In recent kernels a Wacom graphic tablet creates a joystick device, so -xboxdrv or any other real joysticks ends up as \*(T<\fI/dev/input/js1\fR\*(T> instead -of \*(T<\fI/dev/input/js0\fR\*(T>. In many games this causes the joystick to not -function any more. -.PP -A temporary workaround for this is to simply delete the joystick -device js0 and replace it with a symbolic link js1 via: -.PP -.nf -\*(T<$ sudo ln \-sf /dev/input/js1 /dev/input/js0\*(T> -.fi -.PP -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. -.SH "UINPUT TROUBLE" -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: -.PP -\*(T<\fI/etc/udev/rules.d/55\-permissions\-uinput.rules\fR\*(T> -.PP -With the content: -.PP -.nf -\*(T<KERNEL=="uinput", MODE="0660", GROUP="root"\*(T> -.fi -.SH "WINE TROUBLE" -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. -.PP -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. .SH "FORCE FEEDBACK PROGRAMMING" For documentation on the FF interface see: .TP 0.2i @@ -1771,53 +1840,34 @@ information can be found at: \fBfftest\fR is an application you can use to test the force feedback interface. .PP -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. -.PP -"Tomb Raider: Anniversary" running in Wine seems to work together with -xboxdrv and rumble, but hasn't been intensivly tested. -.SH "WRITING START-UP SCRIPTS FOR GAMES" -When you want configurability and automatic launching, it is recomment -that you write little startup scripts for your games, such as this: -.PP -.nf -\*(T<#!/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 #\*(T> -.fi -.PP -That way you can individually configure every game and not -have to worry about launching xboxdrv manually. +Force feedback is disabed by default since it causes trouble in +certain application. "Tomb Raider: Legend" for example when run +in Wine crashes at startup when rumble is enabled, while it +works perfectly normal when rumble is disabled. .SH BUGS +.SS "X11 KEYSYM ISSUES" X11 keysyms might not work correctly in \*(T<\fB\-\-ui\-buttonmap a=XK_Foobar\fR\*(T> when Foobar is mapped to multiple keycodes in the keymap. .PP Workaround: Use \fBKEY_\fR instead or cleanup your keymap .PP +Newer versions of Xorg will also do perform some auto +configuration that might lead to your keymap being switched +whenever a new keyboard is detected, in cases of custom +Xmodmaps this might confuse xboxdrv and make the XK_ style +names unusable. No workaround for that is known right now. +.SS "NON-INTERRUPTABLE PROCESSES DUE TO FORCE FEEDBACK" Force feedback support is brittle, if you Ctrl-c the driver in the wrong moment you will end up with a dead uninterruptable process and basically have to reboot. This looks like it might be a kernel issue and not a xboxdrv one. .PP Workaround: Kill the app that uses xboxdrv before xboxdrv itself. +.SS "BUG REPORTS AND FEATURE REQUESTS" +If you have bug reports or feature request report them by +email to: .PP -Report bugs to Ingo Ruhnke <\*(T<grumbel@gmx.de\*(T>>. +Ingo Ruhnke <\*(T<grumbel@gmx.de\*(T>> .SH COPYRIGHT Copyright \(co 2010 Ingo Ruhnke <\*(T<grumbel@gmx.de\*(T>> License GPLv3+: GNU GPL version 3 or later @@ -1826,9 +1876,9 @@ License GPLv3+: GNU GPL version 3 or later are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. .SH "SEE ALSO" -\fBxboxdrv-daemon\fR(1), \fBevtest\fR(1), \fBjstest\fR(1), +\fBjstest-gtk\fR(1), \fBxev\fR(1), \fBfftest\fR(1), \fBlsusb\fR(1) diff --git a/doc/xboxdrv.xml b/doc/xboxdrv.xml index c58d054..beeda44 100644 --- a/doc/xboxdrv.xml +++ b/doc/xboxdrv.xml @@ -60,7 +60,7 @@ </para> <para> It is also possible for <command>xboxdrv</command> to read input - data directly from an event device, this allows to use the + data directly from an event device, this allows the use of the configurability of <command>xboxdrv</command> on regular PC joysticks, keyboards and mice and thus lets <command>xboxdrv</command> serve a similar purpose @@ -71,7 +71,9 @@ 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. + in wrapper scripts. See the section + <link linkend="wrapperscripts" endterm="wrapperscripts.title" /> + for more information. </para> </refsect1> @@ -1862,96 +1864,148 @@ NAME = STRING ;]]></programlisting> <refsect1> <title>Running xboxdrv</title> - <para> - Plug in your Xbox360 gamepad and then unload the xpad driver via: - </para> + <refsect2> + <title>Using a single controller</title> + <para> + Plug in your Xbox360 gamepad and then unload the xpad driver via: + </para> - <programlisting>$ rmmod xpad</programlisting> + <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> + <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> + <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> + <para> + Next you have to load the uinput kernel module which allows + userspace programms to create virtual input devices and the + joydev module handles the <filename>/dev/input/jsX</filename> + devices: + </para> - <programlisting><![CDATA[$ modprobe uinput + <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> + 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> + <para> + Once ensured that xpad is out of the way and everything is in place + start the userspace driver with: + </para> - <programlisting>$ xboxdrv</programlisting> + <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> + <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> + <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> + <para> + This will create /dev/input/js0 and allow you to access the + gamepad from any game. To exit the driver press Ctrl-c. + </para> - <programlisting>$ xboxdrv -i 1</programlisting> + <para> + By default xboxdrv will echo all controller events to the + console, this makes it easy to see if things are properly + working, but will eat a lot of CPU, thus it is strongly + recomment to disabled that output with + the <option>--silent</option> option. + </para> - <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> + <para> + The trigger buttons are handled by xboxdrv normally as axis, + giving you analog feedback, while this reproduces the Xbox360 + controller the most accurately, it will confuse many and only + be useful in a few, racing games mainly. So in the majority of + cases it is recomment to change the triggers to regular buttons via: + </para> + <programlisting>$ xboxdrv --trigger-as-button</programlisting> + </refsect2> - <programlisting>$ xboxdrv --wid 1</programlisting> + <refsect2> + <title>Using multiple controller</title> + <para> + If you want to use multiple wired controllers you need to start + multiple instances of the xboxdrv driver and append the -i + argument to select the appropriate controller like this: + </para> - <para> - You have to sync the wireless controller as usual. - </para> + <programlisting>$ xboxdrv -i 1</programlisting> - <para>This will then use the second detected controller, see to see which id - your controller has:</para> + <para> + If you have multiple wireless controller you need to start + multiple instances of the xboxdrv driver and append + the <option>--wid</option> option like this: + </para> - <programlisting>$ xboxdrv --list-controller</programlisting> + <programlisting>$ xboxdrv --wid 1</programlisting> - <para>When everything works as expected it is recomment that you run xboxdrv - with the silent option:</para> + <para> + You have to sync the wireless controller as usual. + </para> - <programlisting>$ xboxdrv --silent</programlisting> + <para> + To see a list of all the controllers that xboxdrv detects + being connected to your system use: + </para> - <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> + <programlisting>$ xboxdrv --list-controller</programlisting> + </refsect2> + + <refsect2> + <title>Hotplugging and Xboxdrv Daemon</title> + <para> + To allow hotplugging of gamepads xboxdrv has to be run in + daemon mode. This is accomplished with + the <option>--daemon</option> option: + </para> + <programlisting>$ xboxdrv --daemon</programlisting> + <para> + When launched in daemon mode xboxdrv will listen to udev + events and thus be notified whenever a new USB device gets + plugged into the computer. It will then match that device + against its list of supported devices and launch a separate + thread to handle that gamepad. + </para> + <para> + Note that xboxdrv will not allow an arbitarily large number of + controllers to be used in that mode, it can only handle as + many controllers as you have allocated controller slots at + startup. New slots can be allocated + with <option>--next-controller</option> and by default one + slot is always allocated, thus to support three controller you + would run it with: + </para> + <programlisting>$ xboxdrv --daemon --next-controller --next-controller</programlisting> + <para> + Each controller slot can be configured individually and you + can limit which gamepad gets assigned to which slot with + the <option>--match</option> option. + </para> + <para> + Note that xboxdrv will create the virtual uinput devices on + startup, not when a gamepad gets plugged in, this allows to + plug in gamepads even after a game or an application like XBMC + has already been launched and still have it all function + properly. + </para> + <para> + In daemon mode xboxdrv can be detached from the current shell + via <option>--detach</option>, to get a handle on it to kill + it you can write its pid via the <option>--pid-file</option>: + </para> + <programlisting>$ sudo xboxdrv --daemon --detach --pid-file /var/run/xboxdrv.pid</programlisting> + </refsect2> </refsect1> <refsect1> @@ -1977,8 +2031,9 @@ $ modprobe joydev]]></programlisting> </para> <para> - evtest is available in the tools/ directory, you might also find it in - your distribution. + evtest is available in the tools/ directory or as part of your + distribution in the package <filename>evtest</filename>. your + distribution. </para> </refsect2> @@ -1990,7 +2045,7 @@ $ modprobe joydev]]></programlisting> <para> jstest is available in the tools/ directory or as part of your - distribution. + distribution <filename>joystick</filename>. </para> </refsect2> @@ -2003,10 +2058,14 @@ $ modprobe joydev]]></programlisting> </para> <para> - Currently available via: + It is currently available via: </para> <programlisting>$ svn co svn://svn.berlios.de/windstille/trunk/sdl-jstest</programlisting> + + <para> + Or from the same Ubuntu PPA that also contains xboxdrv in the package <filename>sdl-jstest</filename>. + </para> </refsect2> <refsect2> @@ -2024,10 +2083,20 @@ $ modprobe joydev]]></programlisting> </refsect2> <refsect2> - <title>jscalc</title> + <title>jscalc and jscalibrator</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. + Both of these tools lets you calibrate your gamepad, however + with pretty much all current gamepads this is no longer + needed and actually harmful as it might overwrite a perfectly + good working configuration with a broken one (unplugging the + gamepad or a reboot will fix that). So avoid them unless you + clearly understand the issues of using them. + </para> + <para> + If your gamepad produces incorrect data and you do want to + calibrate it you might want to check out the + option <option>--calibration</option>, which lets you tweak + the way xboxdrv interprets your gamepad data. </para> </refsect2> @@ -2049,7 +2118,7 @@ $ modprobe joydev]]></programlisting> </refsect1> <refsect1> - <title>EXAMPLES</title> + <title>Examples</title> <refsect2> <title>Keyboard Emulation</title> @@ -2086,11 +2155,14 @@ $ modprobe joydev]]></programlisting> 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> + 1,2,3,... aliases are used, which makes things a little easier to read:</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> + <programlisting><![CDATA[$ xboxdrv \ + --dpad-only \ + --trigger-as-button \ + --buttonmap lb=1,x=2,y=3,lt=4,a=5,b=6 \ + --buttonmap rb=1,rb=2,rb=3 \ + --buttonmap rt=4,rt=5,rt=6]]></programlisting> </refsect2> <refsect2> @@ -2164,6 +2236,38 @@ joysticktype = ch]]></programlisting> </refsect2> </refsect1> + <refsect1 id="wrapperscripts"> + <title id="wrapperscripts.title">Writing Start-Up Scripts for Games</title> + <para> + When you want full game specific configurability and automatic + launching of xboxdrv, it is easiest to write little startup + scripts for your games that will launch xboxdrv, launch your + game and then when the game is finished tear down xboxdrv: + </para> + + <programlisting><![CDATA[#!/bin/sh + +exec xboxdrv \ + --trigger-as-button -s \ + -- \ + your_favorite_game + +# EOF #]]></programlisting> + + <para> + Here <filename>your_favorite_game</filename> is the executable + of your game and is passed to xboxdrv as last argument. This + will cause xboxdrv to start the game and keep running as long as + the game is running, when the game is done, xboxdrv will quit + automatically. + </para> + <para> + If you want to pass parameters to the game you have to add + a <option>--</option> separator, as otherwise your options to + the game would be eaten up by xboxdrv. + </para> + </refsect1> + <refsect1> <title>SDL Notes</title> <para> @@ -2229,14 +2333,15 @@ $ export SDL_JOYSTICK_DEVICE]]></programlisting> <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: + This means that either your controller isn't plugged in or is + not recognized by the driver. To fix this you need to know the + idVendor and the idProduct numbers, which you can find out + via: </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> + <para>Once done you can try to add them to this array in <filename>src/xpad_device.cpp</filename>:</para> <programlisting><![CDATA[XPadDevice xpad_devices[] = { ... }]]></programlisting> @@ -2271,25 +2376,6 @@ $ export SDL_JOYSTICK_DEVICE]]></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> @@ -2314,22 +2400,21 @@ $ export SDL_JOYSTICK_DEVICE]]></programlisting> 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> + <refsect2 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[ + <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <deviceinfo version="0.2"> <device> @@ -2339,13 +2424,73 @@ $ export SDL_JOYSTICK_DEVICE]]></programlisting> </device> </deviceinfo>]]></programlisting> - <para> - This will tell HAL and later Xorg that xboxdrv acts as keyboard. - </para> + <para> + This will tell HAL and later Xorg that xboxdrv acts as keyboard. + </para> + </refsect2> + + <refsect2> + <title>Wacom issues</title> + <para> + In some older 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> + + <para> + In newer kernels this issue is fixed. + </para> + </refsect2> + + <refsect2> + <title>uinput issues</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 <filename>/etc/udev/rules.d/55-permissions-uinput.rules</filename> + with the content: + </para> + <programlisting>KERNEL=="uinput", MODE="0660", GROUP="root"</programlisting> + </refsect2> + + <refsect2> + <title>Wine issues</title> + <para> + When using the Xbox360 gamepad in Wine it is not specially + handled as Xbox360 gamepad, but as generic DirectInput gamepad. + This means games will not display the proper button labels, but + just numbers (i.e. 'Btn1' instead of 'A' for example). Aside + from that it should work fine. + </para> + <para> + XInput support (the Microsoft DirectInput replacment, not the + Xorg xinput) is as of January 2011 not implemented in Wine, so + games that require XInput and don't have an DirectInput fallback + will not work with a Xbox360 controller, unofficial patches + however do exist. + </para> + </refsect2> </refsect1> <refsect1> - <title>Xorg Trouble</title> + <title>Xorg issues</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 @@ -2420,61 +2565,6 @@ EndSection]]></programlisting> </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> @@ -2499,65 +2589,60 @@ EndSection]]></programlisting> <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> + <para> + Force feedback is disabed by default since it causes trouble in + certain application. "Tomb Raider: Legend" for example when run + in Wine crashes at startup when rumble is enabled, while it + works perfectly normal when rumble is disabled. + </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> + + <refsect2> + <title>X11 keysym issues</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>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> + Newer versions of Xorg will also do perform some auto + configuration that might lead to your keymap being switched + whenever a new keyboard is detected, in cases of custom + Xmodmaps this might confuse xboxdrv and make the XK_ style + names unusable. No workaround for that is known right now. + </para> + </refsect2> - <para> - Workaround: Kill the app that uses xboxdrv before xboxdrv itself. - </para> + <refsect2> + <title>Non-interruptable processes due to force feedback</title> - <para> - Report bugs to Ingo Ruhnke <email>grumbel@gmx.de</email>. - </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> + </refsect2> + + <refsect2> + <title>Bug Reports and Feature Requests</title> + <para> + If you have bug reports or feature request report them by + email to: + </para> + <para> + Ingo Ruhnke <email>grumbel@gmx.de</email> + </para> + </refsect2> </refsect1> <refsect1> @@ -2574,10 +2659,6 @@ wait $XBOXPID <refsect1> <title>See also</title> <para> - <citerefentry> - <refentrytitle>xboxdrv-daemon</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry>, <citerefentry> <refentrytitle>evtest</refentrytitle> <manvolnum>1</manvolnum> @@ -2586,6 +2667,10 @@ wait $XBOXPID <refentrytitle>jstest</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>, + <citerefentry> + <refentrytitle>jstest-gtk</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, <citerefentry> <refentrytitle>xev</refentrytitle> <manvolnum>1</manvolnum>