]> git.proxmox.com Git - mirror_ubuntu-artful-kernel.git/blame - Documentation/input/xpad.txt
ALSA: ali5451: fix spelling mistake in "ali_capture_preapre"
[mirror_ubuntu-artful-kernel.git] / Documentation / input / xpad.txt
CommitLineData
5469b196 1xpad - Linux USB driver for Xbox compatible controllers
1da177e4 2
5469b196
DD
3This driver exposes all first-party and third-party Xbox compatible
4controllers. It has a long history and has enjoyed considerable usage
5as Window's xinput library caused most PC games to focus on Xbox
6controller compatibility.
deb8ee43 7
5469b196
DD
8Due to backwards compatibility all buttons are reported as digital.
9This only effects Original Xbox controllers. All later controller models
10have only digital face buttons.
11
12Rumble is supported on some models of Xbox 360 controllers but not of
13Original Xbox controllers nor on Xbox One controllers. As of writing
14the Xbox One's rumble protocol has not been reverse engineered but in
15the future could be supported.
1da177e4
LT
16
17
deb8ee43
DC
180. Notes
19--------
deb8ee43
DC
20The number of buttons/axes reported varies based on 3 things:
21- if you are using a known controller
22- if you are using a known dance pad
23- if using an unknown device (one not listed below), what you set in the
24 module configuration for "Map D-PAD to buttons rather than axes for unknown
25 pads" (module option dpad_to_buttons)
1da177e4 26
5469b196
DD
27If you set dpad_to_buttons to N and you are using an unknown device
28the driver will map the directional pad to axes (X/Y).
29If you said Y it will map the d-pad to buttons, which is needed for dance
30style games to function correctly. The default is Y.
31
32dpad_to_buttons has no effect for known pads. A erroneous commit message
33claimed dpad_to_buttons could be used to force behavior on known devices.
34This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
35unknown controllers.
deb8ee43 36
deb8ee43
DC
37
380.1 Normal Controllers
39----------------------
40With a normal controller, the directional pad is mapped to its own X/Y axes.
41The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) will report 8
42axes and 10 buttons.
1da177e4 43
deb8ee43 44All 8 axes work, though they all have the same range (-32768..32767)
1da177e4
LT
45and the zero-setting is not correct for the triggers (I don't know if that
46is some limitation of jstest, since the input device setup should be fine. I
47didn't have a look at jstest itself yet).
48
49All of the 10 buttons work (in digital mode). The six buttons on the
50right side (A, B, X, Y, black, white) are said to be "analog" and
51report their values as 8 bit unsigned, not sure what this is good for.
52
53I tested the controller with quake3, and configuration and
54in game functionality were OK. However, I find it rather difficult to
55play first person shooters with a pad. Your mileage may vary.
56
57
deb8ee43
DC
580.2 Xbox Dance Pads
59-------------------
60When using a known dance pad, jstest will report 6 axes and 14 buttons.
61
62For dance style pads (like the redoctane pad) several changes
63have been made. The old driver would map the d-pad to axes, resulting
64in the driver being unable to report when the user was pressing both
65left+right or up+down, making DDR style games unplayable.
66
67Known dance pads automatically map the d-pad to buttons and will work
68correctly out of the box.
69
70If your dance pad is recognized by the driver but is using axes instead
71of buttons, see section 0.3 - Unknown Controllers
72
73I've tested this with Stepmania, and it works quite well.
74
75
a982ac06 760.3 Unknown Controllers
deb8ee43 77----------------------
a982ac06 78If you have an unknown xbox controller, it should work just fine with
deb8ee43
DC
79the default settings.
80
81HOWEVER if you have an unknown dance pad not listed below, it will not
82work UNLESS you set "dpad_to_buttons" to 1 in the module configuration.
83
a982ac06 84PLEASE, if you have an unknown controller, email Dom <binary1230@yahoo.com> with
deb8ee43
DC
85a dump from /proc/bus/usb and a description of the pad (manufacturer, country,
86whether it is a dance pad or normal controller) so that we can add your pad
87to the list of supported devices, ensuring that it will work out of the
88box in the future.
89
90
5469b196 911. USB adapters
1da177e4 92--------------
5469b196
DD
93All generations of Xbox controllers speak USB over the wire.
94- Original Xbox controllers use a proprietary connector and require adapters.
95- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver
96 for Windows'
97- Wired Xbox 360 controllers use standard USB connectors.
98- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not
99 yet supported.
100- Xbox One controllers can be wired and use standard Micro-USB connectors.
101
1da177e4 102
5469b196
DD
103
1041.1 Original Xbox USB adapters
105--------------
106Using this driver with an Original Xbox controller requires an
107adapter cable to break out the proprietary connector's pins to USB.
108You can buy these online fairly cheap, or build your own.
1da177e4 109
deb8ee43
DC
110Such a cable is pretty easy to build. The Controller itself is a USB
111compound device (a hub with three ports for two expansion slots and
112the controller device) with the only difference in a nonstandard connector
5469b196 113(5 pins vs. 4 on standard USB 1.0 connectors).
1da177e4
LT
114
115You just need to solder a USB connector onto the cable and keep the
116yellow wire unconnected. The other pins have the same order on both
117connectors so there is no magic to it. Detailed info on these matters
118can be found on the net ([1], [2], [3]).
119
120Thanks to the trip splitter found on the cable you don't even need to cut the
121original one. You can buy an extension cable and cut that instead. That way,
122you can still use the controller with your X-Box, if you have one ;)
123
124
5469b196 125
deb8ee43 1262. Driver Installation
1da177e4
LT
127----------------------
128
5469b196
DD
129Once you have the adapter cable, if needed, and the controller connected
130the xpad module should be auto loaded. To confirm you can cat
131/proc/bus/usb/devices. There should be an entry like the one at the end [4].
132
133
1da177e4 134
5469b196
DD
1353. Supported Controllers
136------------------------
137For a full list of supported controllers and associated vendor and product
138IDs see the xpad_device[] array[6].
139
140As of the historic version 0.0.6 (2006-10-10) the following devices
141were supported:
142 original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202
143 smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289
1da177e4 144 original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
5469b196
DD
145 InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a
146 RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809
147
148Unrecognized models of Xbox controllers should function as Generic
149Xbox controllers. Unrecognized Dance Pad controllers require setting
150the module option 'dpad_to_buttons'.
151
152If you have an unrecognized controller please see 0.3 - Unknown Controllers
1da177e4 153
1da177e4 154
5469b196
DD
1554. Manual Testing
156-----------------
157To test this driver's functionality you may use 'jstest'.
1da177e4 158
5469b196 159For example:
1da177e4
LT
160> modprobe xpad
161> modprobe joydev
162> jstest /dev/js0
163
deb8ee43
DC
164If you're using a normal controller, there should be a single line showing
16518 inputs (8 axes, 10 buttons), and its values should change if you move
166the sticks and push the buttons. If you're using a dance pad, it should
167show 20 inputs (6 axes, 14 buttons).
1da177e4 168
deb8ee43 169It works? Voila, you're done ;)
1da177e4
LT
170
171
5469b196
DD
172
1735. Thanks
1da177e4
LT
174---------
175
176I have to thank ITO Takayuki for the detailed info on his site
177 http://euc.jp/periphs/xbox-controller.ja.html.
178
179His useful info and both the usb-skeleton as well as the iforce input driver
180(Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping
181the basic functionality.
182
183
1da177e4 184
5469b196
DD
1856. References
186-------------
1da177e4 187
5469b196
DD
188[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
189[2]: http://xpad.xbox-scene.com/
190[3]: http://www.markosweb.com/www/xboxhackz.com/
191[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
1da177e4
LT
192
193T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0
194D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1
195P: Vendor=05fd ProdID=107a Rev= 1.00
196C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
197I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
198E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
199E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
200
5469b196 201[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
deb8ee43
DC
202
203T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0
204D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
205P: Vendor=0c12 ProdID=8809 Rev= 0.01
206S: Product=XBOX DDR
207C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
208I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
209E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms
210E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms
211
5469b196
DD
212[6]: http://lxr.free-electrons.com/ident?i=xpad_device
213
214
215
2167. Historic Edits
217-----------------
1da177e4
LT
218Marko Friedemann <mfr@bmx-chemnitz.de>
2192002-07-16
deb8ee43
DC
220 - original doc
221
222Dominic Cerquetti <binary1230@yahoo.com>
2232005-03-19
224 - added stuff for dance pads, new d-pad->axes mappings
5469b196
DD
225
226Later changes may be viewed with 'git log Documentation/input/xpad.txt'