Linux Gamepad Specification

게임패드 규격의 목적과 물리 배치

Linux에는 여러 게임패드 입력 드라이버가 있습니다. 사용자 공간이 장치마다 다른 버튼 배치를 따로 처리하지 않도록 이 문서는 게임패드가 데이터를 보고하는 표준 방식을 정의합니다.

여기서 게임패드는 오른쪽 action pad, 왼쪽 D-pad, 가운데 menu pad, 좌우 analog stick, 전면의 좌우 trigger를 갖는 장치를 뜻합니다. 장치마다 일부 요소가 없을 수 있지만 물리적 위치를 기준으로 같은 의미의 Linux event code를 사용합니다.

---------------------------
Linux Gamepad Specification
---------------------------

:Author: 2013 by David Herrmann <dh.herrmann@gmail.com>


Introduction
~~~~~~~~~~~~
Linux provides many different input drivers for gamepad hardware. To avoid
having user-space deal with different button-mappings for each gamepad, this
document defines how gamepads are supposed to report their data.

Geometry
~~~~~~~~
As "gamepad" we define devices which roughly look like this::

            ____________________________              __
           / [__ZL__]          [__ZR__] \               |
          / [__ TL __]        [__ TR __] \              | Front Triggers
       __/________________________________\__         __|
      /                                  _   \          |
     /      /\           __             (N)   \         |
    /       ||      __  |MO|  __     _       _ \        | Main Pad
   |    <===DP===> |SE|      |ST|   (W) -|- (E) |       |
    \       ||    ___          ___       _     /        |
    /\      \/   /   \        /   \     (S)   /\      __|
   /  \________ | LS  | ____ |  RS | ________/  \       |
  |         /  \ \___/ /    \ \___/ /  \         |      | Control Sticks
  |        /    \_____/      \_____/    \        |    __|
  |       /                              \       |
   \_____/                                \_____/

       |________|______|    |______|___________|
         D-Pad    Left       Right   Action Pad
                 Stick       Stick

                   |_____________|
                      Menu Pad

주요 기능과 호환 게임패드 탐지

Action pad는 보통 오른쪽에 마름모꼴로 놓인 네 버튼이며, 장치별 라벨 대신 물리 위치에 따라 NORTH, SOUTH, WEST, EAST라 부릅니다. D-pad는 왼쪽의 상하좌우 네 방향 버튼입니다.

Menu pad는 배치가 다양하지만 대체로 SELECT와 START 두 버튼을 가지며, 시스템 메뉴나 설정을 여는 브랜드 버튼이 추가되기도 합니다. Analog stick은 자유로운 방향 입력을 제공하고 눌렀을 때 digital button으로도 동작할 수 있습니다.

Trigger는 패드 위쪽에 세로로 배치됩니다. 위쪽은 Left/Right Trigger, 아래쪽은 Z-Left/Z-Right로 부릅니다. 많은 장치는 force feedback을 제공하지만 대부분 단순 rumble motor입니다.

이 규격을 따르는 게임패드는 `BTN_GAMEPAD`를 매핑합니다. 이는 `BTN_SOUTH` 또는 `BTN_A`의 별칭이므로 게임패드를 식별하는 단서가 됩니다. 그러나 필요한 기능이 모두 있는지는 각 event capability를 별도로 검사해야 합니다.

기존 legacy driver는 하위 호환성 때문에 이 규칙과 다를 수 있습니다. 사용자 공간에서 보정 mapping을 제공하거나 driver module option을 안내해야 합니다. 새 게임패드는 이 mapping을 따라야 하며 위반은 버그로 보고해야 합니다.

Nintendo Wii Nunchuk처럼 기능이 적은 장치도 호환 방식으로 이 protocol의 일부 code를 재사용합니다. 이 장치는 오른쪽 trigger 두 개와 analog stick 하나만 있는 게임패드처럼 보고합니다. 완전한 게임패드만 지원하려면 애플리케이션이 필요한 모든 event를 확인해야 합니다.

Most gamepads have the following features:

  - Action-Pad
    4 buttons in diamonds-shape (on the right side). The buttons are
    differently labeled on most devices so we define them as NORTH,
    SOUTH, WEST and EAST.
  - D-Pad (Direction-pad)
    4 buttons (on the left side) that point up, down, left and right.
  - Menu-Pad
    Different constellations, but most-times 2 buttons: SELECT - START
    Furthermore, many gamepads have a fancy branded button that is used as
    special system-button. It often looks different to the other buttons and
    is used to pop up system-menus or system-settings.
  - Analog-Sticks
    Analog-sticks provide freely moveable sticks to control directions. Not
    all devices have both or any, but they are present at most times.
    Analog-sticks may also provide a digital button if you press them.
  - Triggers
    Triggers are located on the upper-side of the pad in vertical direction.
    Not all devices provide them, but the upper buttons are normally named
    Left- and Right-Triggers, the lower buttons Z-Left and Z-Right.
  - Rumble
    Many devices provide force-feedback features. But are mostly just
    simple rumble motors.

Detection
~~~~~~~~~

All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
However, not all gamepads provide all features, so you need to test for all
features that you need, first. How each feature is mapped is described below.

Legacy drivers often don't comply to these rules. As we cannot change them
for backwards-compatibility reasons, you need to provide fixup mappings in
user-space yourself. Some of them might also provide module-options that
change the mappings so you can advise users to set these.

All new gamepads are supposed to comply with this mapping. Please report any
bugs, if they don't.

There are a lot of less-featured/less-powerful devices out there, which re-use
the buttons from this protocol. However, they try to do this in a compatible
fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
and one analog stick. It reports them as if it were a gamepad with only one
analog stick and two trigger buttons on the right side.
But that means, that if you only support "real" gamepads, you must test
devices for _all_ reported events that you need. Otherwise, you will also get
devices that report a small subset of the events.

No other devices, that do not look/feel like a gamepad, shall report these
events.

Action pad, D-pad와 analog stick 이벤트

모든 게임패드는 action button을 최소 두 개 제공하며 `BTN_GAMEPAD`의 별칭인 `BTN_SOUTH`를 반드시 보고합니다. 버튼 라벨과 관계없이 code는 물리적 위치에 따라 정합니다. 두세 버튼 장치는 드물고 오래된 형태이므로 네 버튼을 모두 보고하지 않는 장치를 걸러낼 수도 있습니다.

D-pad는 상하좌우 네 방향을 제공합니다. Digital 방식은 `BTN_DPAD_*`, analog 방식은 `ABS_HAT0X`와 `ABS_HAT0Y`로 보고합니다. 한 장치가 둘 다 보낼 수도 있으며 kernel은 두 표현을 서로 변환하지 않으므로 애플리케이션이 둘 다 지원하고 적절한 것을 선택해야 합니다. ABS 음수는 왼쪽 또는 위, 양수는 오른쪽 또는 아래입니다.

왼쪽 analog stick은 `ABS_X`, `ABS_Y`, 오른쪽은 `ABS_RX`, `ABS_RY`로 보고합니다. Stick은 0개, 1개 또는 2개일 수 있습니다. Stick을 눌러 digital button으로 사용할 수 있으면 왼쪽은 `BTN_THUMBL`, 오른쪽은 `BTN_THUMBR`입니다.

Events
~~~~~~

Gamepads report the following events:

- Action-Pad:

  Every gamepad device has at least 2 action buttons. This means, that every
  device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
  of the labels on the buttons, the codes are sent according to the
  physical position of the buttons.

  Please note that 2- and 3-button pads are fairly rare and old. You might
  want to filter gamepads that do not report all four.

    - 2-Button Pad:

      If only 2 action-buttons are present, they are reported as BTN_SOUTH and
      BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
      horizontal layouts, the button more on the right is BTN_EAST.

    - 3-Button Pad:

      If only 3 action-buttons are present, they are reported as (from left
      to right): BTN_WEST, BTN_SOUTH, BTN_EAST
      If the buttons are aligned perfectly vertically, they are reported as
      (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST

    - 4-Button Pad:

      If all 4 action-buttons are present, they can be aligned in two
      different formations. If diamond-shaped, they are reported as BTN_NORTH,
      BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.
      If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left
      is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.

- D-Pad:

  Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right
  Some of these are available as digital buttons, some as analog buttons. Some
  may even report both. The kernel does not convert between these so
  applications should support both and choose what is more appropriate if
  both are reported.

    - Digital buttons are reported as:

      BTN_DPAD_*

    - Analog buttons are reported as:

      ABS_HAT0X and ABS_HAT0Y

  (for ABS values negative is left/up, positive is right/down)

- Analog-Sticks:

  The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
  reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
  If analog-sticks provide digital buttons, they are mapped accordingly as
  BTN_THUMBL (first/left) and BTN_THUMBR (second/right).

  (for ABS values negative is left/up, positive is right/down)

Trigger, menu, rumble, grip과 profile 이벤트

Trigger는 digital, analog 또는 두 방식 모두로 제공될 수 있으므로 사용자 공간이 모든 조합을 처리해야 합니다. 위쪽 오른쪽은 `BTN_TR` 또는 `ABS_HAT1X`, 위쪽 왼쪽은 `BTN_TL` 또는 `ABS_HAT1Y`입니다. 아래쪽 오른쪽 ZR은 `BTN_TR2` 또는 `ABS_HAT2X`, 아래쪽 왼쪽 ZL은 `BTN_TL2` 또는 `ABS_HAT2Y`입니다.

위·아래 구분 없이 trigger 한 쌍만 있으면 오른쪽 계열인 `BTN_TR` 또는 `ABS_HAT1X`로 보고합니다. Analog trigger 값은 0에서 시작하며 압력이 커질수록 양수로 증가합니다.

Menu button은 항상 digital이며 라벨이 아니라 위치로 매핑합니다. 하나면 `BTN_START`, 두 개면 왼쪽이 `BTN_SELECT`, 오른쪽이 `BTN_START`입니다. Nintendo HOME, Xbox X, PlayStation PS처럼 브랜드나 특수 기호가 있는 세 번째 button은 `BTN_MODE`로 매핑합니다.

Rumble 기능은 `FF_RUMBLE`로 알립니다. 후면 grip 또는 paddle button은 firmware가 일반 button처럼 재프로그래밍하기도 하지만 software에 직접 노출될 수도 있습니다. 오른쪽 위·아래는 `BTN_GRIPR`, `BTN_GRIPR2`, 왼쪽 위·아래는 `BTN_GRIPL`, `BTN_GRIPL2`를 사용합니다.

Xbox Adaptive와 Xbox Elite 2처럼 여러 profile을 고르는 switch가 있으면 활성 profile 변경 시 새 선택값을 `ABS_PROFILE` event로 보냅니다.

- Triggers:

  Trigger buttons can be available as digital or analog buttons or both. User-
  space must correctly deal with any situation and choose the most appropriate
  mode.

  Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
  or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
  ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).

  If only one trigger-button combination is present (upper+lower), they are
  reported as "right" triggers (BTN_TR/ABS_HAT1X).

  (ABS trigger values start at 0, pressure is reported as positive values)

- Menu-Pad:

  Menu buttons are always digital and are mapped according to their location
  instead of their labels. That is:

    - 1-button Pad:

      Mapped as BTN_START

    - 2-button Pad:

      Left button mapped as BTN_SELECT, right button mapped as BTN_START

  Many pads also have a third button which is branded or has a special symbol
  and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
  "HOME" button, the Xbox "X" button or the Sony PlayStation "PS" button.

- Rumble:

  Rumble is advertised as FF_RUMBLE.

- Grip buttons:

  Many pads include buttons on the rear, usually referred to as either grip or
  rear buttons, or paddles. These are often reprogrammable by the firmware to
  appear as "normal" buttons, but are sometimes exposed to software too. Some
  notable examples of this are the Steam Deck, which has R4, R5, L4, and L5 on
  the back; the Xbox Elite pads, which have P1-P4; and the Switch 2 Pro
  Controller, which has GL and GR.

  For these controllers, BTN_GRIPR and BTN_GRIPR2 should be used for the top
  and bottom (if present) right grip button(s), and BTN_GRIPL and BTN_GRIPL2
  should be used for the top and bottom (if present) left grip button(s).

- Profile:

  Some pads provide a multi-value profile selection switch. Examples include
  the Xbox Adaptive and the Xbox Elite 2 controllers. When the active profile
  is switched, its newly selected value is emitted as an ABS_PROFILE event.