Xpad - Linux USB Driver for Xbox Compatible Controllers

Xbox 호환 컨트롤러 범위와 unknown-device 옵션

`xpad`는 Microsoft 정품과 타사 Xbox 호환 컨트롤러를 Linux input 장치로 노출하는 USB 드라이버입니다. Windows `xinput`의 영향으로 PC 게임이 Xbox 호환성에 집중하면서 널리 사용됐습니다.

하위 호환성을 위해 모든 버튼을 digital로 보고합니다. 이 차이는 face button이 실제 analog인 Original Xbox 컨트롤러에만 영향을 주며 이후 모델은 face button 자체가 digital입니다.

문서 작성 시점에는 일부 Xbox 360 모델만 rumble을 지원하고 Original Xbox와 Xbox One은 지원하지 않습니다. Xbox One rumble protocol이 역공학되지 않았다는 역사적 상태가 기록돼 있습니다.

`dpad_to_buttons`와 `triggers_to_buttons`는 unknown controller에만 영향을 줍니다. Known pad의 동작을 강제할 수 있다는 과거 commit message는 잘못됐습니다. Unknown dance pad는 좌우 또는 상하 동시 누름을 보존하려면 `dpad_to_buttons=1`이 필요합니다.

=======================================================
xpad - Linux USB driver for Xbox compatible controllers
=======================================================

This driver exposes all first-party and third-party Xbox compatible
controllers. It has a long history and has enjoyed considerable usage
as Windows' xinput library caused most PC games to focus on Xbox
controller compatibility.

Due to backwards compatibility all buttons are reported as digital.
This only affects Original Xbox controllers. All later controller models
have only digital face buttons.

Rumble is supported on some models of Xbox 360 controllers but not of
Original Xbox controllers nor on Xbox One controllers. As of writing
the Xbox One's rumble protocol has not been reverse-engineered but in
the future could be supported.


Notes
=====

The number of buttons/axes reported varies based on 3 things:

- if you are using a known controller
- if you are using a known dance pad
- if using an unknown device (one not listed below), what you set in the
  module configuration for "Map D-PAD to buttons rather than axes for unknown
  pads" (module option dpad_to_buttons)

If you set dpad_to_buttons to N and you are using an unknown device
the driver will map the directional pad to axes (X/Y).
If you said Y it will map the d-pad to buttons, which is needed for dance
style games to function correctly. The default is Y.

dpad_to_buttons has no effect for known pads. A erroneous commit message
claimed dpad_to_buttons could be used to force behavior on known devices.
This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
unknown controllers.

일반 컨트롤러와 Dance Pad 입력 매핑

일반 컨트롤러에서는 directional pad가 전용 X/Y axes로 매핑됩니다. Joystick 1.2.15의 `jstest` 2.1.0 기준으로 8개 축과 10개 버튼을 보고합니다.

Original Xbox의 오른쪽 여섯 버튼 A, B, X, Y, black, white는 장치가 8비트 unsigned analog 값으로 보고한다고 알려졌지만, 드라이버는 digital mode로 제공합니다. 문서 작성자는 Quake 3의 설정과 게임 동작을 확인했습니다.

Known Xbox dance pad는 `jstest`에서 6개 축과 14개 버튼을 보고합니다. D-pad를 axes로 표현하면 left+right 또는 up+down을 동시에 나타낼 수 없어 DDR 게임이 동작하지 않으므로, known dance pad는 자동으로 D-pad를 buttons에 매핑합니다.

Unknown Xbox controller는 기본 설정으로 대개 동작합니다. 그러나 목록에 없는 dance pad는 module configuration에서 `dpad_to_buttons=1`을 설정하지 않으면 제대로 동작하지 않습니다.

Normal Controllers
------------------

With a normal controller, the directional pad is mapped to its own X/Y axes.
The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) will report 8
axes and 10 buttons.

All 8 axes work, though they all have the same range (-32768..32767)
and the zero-setting is not correct for the triggers (I don't know if that
is some limitation of jstest, since the input device setup should be fine. I
didn't have a look at jstest itself yet).

All of the 10 buttons work (in digital mode). The six buttons on the
right side (A, B, X, Y, black, white) are said to be "analog" and
report their values as 8 bit unsigned, not sure what this is good for.

I tested the controller with quake3, and configuration and
in game functionality were OK. However, I find it rather difficult to
play first person shooters with a pad. Your mileage may vary.


Xbox Dance Pads
---------------

When using a known dance pad, jstest will report 6 axes and 14 buttons.

For dance style pads (like the redoctane pad) several changes
have been made.  The old driver would map the d-pad to axes, resulting
in the driver being unable to report when the user was pressing both
left+right or up+down, making DDR style games unplayable.

Known dance pads automatically map the d-pad to buttons and will work
correctly out of the box.

If your dance pad is recognized by the driver but is using axes instead
of buttons, see section 0.3 - Unknown Controllers

I've tested this with Stepmania, and it works quite well.


Unknown Controllers
-------------------

If you have an unknown Xbox controller, it should work just fine with
the default settings.

HOWEVER if you have an unknown dance pad not listed below, it will not
work UNLESS you set "dpad_to_buttons" to 1 in the module configuration.

Xbox 세대별 USB 연결과 Original 어댑터

모든 세대의 Xbox 컨트롤러는 유선 구간에서 USB를 사용하지만 커넥터와 무선 방식이 다릅니다.

Original Xbox 컨트롤러는 독자 커넥터를 표준 USB로 바꾸는 adapter cable이 필요합니다. 컨트롤러 자체는 두 expansion slot과 controller device를 위한 3-port hub를 포함한 USB compound device이며, 표준 USB 1.0의 4핀 대신 5핀 커넥터를 쓴다는 점이 주된 차이입니다.

연장 케이블의 trip splitter를 사용하면 원래 컨트롤러 케이블을 자르지 않아 Xbox 본체에도 계속 사용할 수 있습니다. 상세 배선 참고 링크는 원문 references에 보존합니다.

USB adapters
============

All generations of Xbox controllers speak USB over the wire.

- Original Xbox controllers use a proprietary connector and require adapters.
- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver
  for Windows'
- Wired Xbox 360 controllers use standard USB connectors.
- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not
  yet supported.
- Xbox One controllers can be wired and use standard Micro-USB connectors.



Original Xbox USB adapters
--------------------------

Using this driver with an Original Xbox controller requires an
adapter cable to break out the proprietary connector's pins to USB.
You can buy these online fairly cheap, or build your own.

Such a cable is pretty easy to build. The Controller itself is a USB
compound device (a hub with three ports for two expansion slots and
the controller device) with the only difference in a nonstandard connector
(5 pins vs. 4 on standard USB 1.0 connectors).

You just need to solder a USB connector onto the cable and keep the
yellow wire unconnected. The other pins have the same order on both
connectors so there is no magic to it. Detailed info on these matters
can be found on the net ([1]_, [2]_, [3]_).

Thanks to the trip splitter found on the cable you don't even need to cut the
original one. You can buy an extension cable and cut that instead. That way,
you can still use the controller with your Xbox, if you have one ;)

드라이버 자동 로드와 지원 장치 식별

필요한 adapter를 연결하면 `xpad` module이 자동으로 로드돼야 합니다. `/sys/kernel/debug/usb/devices`에서 USB descriptor와 interface의 `Driver=xpad` 여부를 확인할 수 있습니다.

전체 최신 지원 목록과 vendor/product ID는 소스의 `xpad_device[]` 배열을 기준으로 해야 합니다. 문서는 역사적 version 0.0.6에서 지원한 다섯 장치를 별도로 기록합니다.

인식되지 않은 일반 모델은 Generic Xbox controller로 동작해야 합니다. 인식되지 않은 Dance Pad는 `dpad_to_buttons`를 설정해야 합니다.

Driver Installation
===================

Once you have the adapter cable, if needed, and the controller connected
the xpad module should be auto loaded. To confirm you can cat
/sys/kernel/debug/usb/devices. There should be an entry like those:

.. code-block:: none
   :caption: dump from InterAct PowerPad Pro (Germany)

    T:  Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs=  1
    P:  Vendor=05fd ProdID=107a Rev= 1.00
    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
    E:  Ad=81(I) Atr=03(Int.) MxPS=  32 Ivl= 10ms
    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl= 10ms

.. code-block:: none
   :caption: dump from Redoctane Xbox Dance Pad (US)

    T:  Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12  MxCh= 0
    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
    P:  Vendor=0c12 ProdID=8809 Rev= 0.01
    S:  Product=XBOX DDR
    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
    E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms


Supported Controllers
=====================

For a full list of supported controllers and associated vendor and product
IDs see the xpad_device[] array\ [4]_.

As of the historic version 0.0.6 (2006-10-10) the following devices
were supported::

 original Microsoft XBOX controller (US),    vendor=0x045e, product=0x0202
 smaller  Microsoft XBOX controller (US),    vendor=0x045e, product=0x0289
 original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
 InterAct PowerPad Pro (Germany),            vendor=0x05fd, product=0x107a
 RedOctane Xbox Dance Pad (US),              vendor=0x0c12, product=0x8809

Unrecognized models of Xbox controllers should function as Generic
Xbox controllers. Unrecognized Dance Pad controllers require setting
the module option 'dpad_to_buttons'.

If you have an unrecognized controller please see 0.3 - Unknown Controllers

수동 시험, 공헌과 변경 이력

드라이버는 `jstest`로 수동 시험합니다. `modprobe xpad`, `modprobe joydev`, `jstest /dev/js0` 순서로 실행합니다.

스틱과 버튼을 움직일 때 한 줄의 값이 바뀌면 기본 기능이 동작합니다. 문서는 ITO Takayuki의 상세 자료, `usb-skeleton`, Greg Kroah-Hartman과 Vojtech Pavlik의 `iforce` input driver가 초기 구현에 도움을 줬다고 기록합니다.

네 개의 reference에는 Xbox controller 배선 자료와 최신 `xpad_device` 소스 검색 링크가 포함됩니다. 현재 지원 여부는 역사적 목록보다 실제 커널 배열을 우선해야 합니다.

Manual Testing
==============

To test this driver's functionality you may use 'jstest'.

For example::

    > modprobe xpad
    > modprobe joydev
    > jstest /dev/js0

If you're using a normal controller, there should be a single line showing
18 inputs (8 axes, 10 buttons), and its values should change if you move
the sticks and push the buttons.  If you're using a dance pad, it should
show 20 inputs (6 axes, 14 buttons).

It works? Voila, you're done ;)



Thanks
======

I have to thank ITO Takayuki for the detailed info on his site
    http://euc.jp/periphs/xbox-controller.ja.html.

His useful info and both the usb-skeleton as well as the iforce input driver
(Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping
the basic functionality.



References
==========

.. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
.. [2] http://xpad.xbox-scene.com/
.. [3] http://www.markosweb.com/www/xboxhackz.com/
.. [4] https://elixir.bootlin.com/linux/latest/ident/xpad_device


Historic Edits
==============

2002-07-16 - Marko Friedemann <mfr@bmx-chemnitz.de>
 - original doc

2005-03-19 - Dominic Cerquetti <binary1230@yahoo.com>
 - added stuff for dance pads, new d-pad->axes mappings

Later changes may be viewed with
'git log --follow Documentation/input/devices/xpad.rst'