Documentation/input/gamepad.txt

   1                             Linux Gamepad API
   2 ----------------------------------------------------------------------------
   3
   4 1. Intro
   5 ~~~~~~~~
   6 Linux provides many different input drivers for gamepad hardware. To avoid
   7 having user-space deal with different button-mappings for each gamepad, this
   8 document defines how gamepads are supposed to report their data.
   9
  10 2. Geometry
  11 ~~~~~~~~~~~
  12 As "gamepad" we define devices which roughly look like this:
  13
  14             ____________________________              __
  15            / [__ZL__]          [__ZR__] \               |
  16           / [__ TL __]        [__ TR __] \              | Front Triggers
  17        __/________________________________\__         __|
  18       /                                  _   \          |
  19      /      /\           __             (N)   \         |
  20     /       ||      __  |MO|  __     _       _ \        | Main Pad
  21    |    <===DP===> |SE|      |ST|   (W) -|- (E) |       |
  22     \       ||    ___          ___       _     /        |
  23     /\      \/   /   \        /   \     (S)   /\      __|
  24    /  \________ | LS  | ____ |  RS | ________/  \       |
  25   |         /  \ \___/ /    \ \___/ /  \         |      | Control Sticks
  26   |        /    \_____/      \_____/    \        |    __|
  27   |       /                              \       |
  28    \_____/                                \_____/
  29
  30        |________|______|    |______|___________|
  31          D-Pad    Left       Right   Action Pad
  32                  Stick       Stick
  33
  34                    |_____________|
  35                       Menu Pad
  36
  37 Most gamepads have the following features:
  38   - Action-Pad
  39     4 buttons in diamonds-shape (on the right side). The buttons are
  40     differently labeled on most devices so we define them as NORTH,
  41     SOUTH, WEST and EAST.
  42   - D-Pad (Direction-pad)
  43     4 buttons (on the left side) that point up, down, left and right.
  44   - Menu-Pad
  45     Different constellations, but most-times 2 buttons: SELECT - START
  46     Furthermore, many gamepads have a fancy branded button that is used as
  47     special system-button. It often looks different to the other buttons and
  48     is used to pop up system-menus or system-settings.
  49   - Analog-Sticks
  50     Analog-sticks provide freely moveable sticks to control directions. Not
  51     all devices have both or any, but they are present at most times.
  52     Analog-sticks may also provide a digital button if you press them.
  53   - Triggers
  54     Triggers are located on the upper-side of the pad in vertical direction.
  55     Not all devices provide them, but the upper buttons are normally named
  56     Left- and Right-Triggers, the lower buttons Z-Left and Z-Right.
  57   - Rumble
  58     Many devices provide force-feedback features. But are mostly just
  59     simple rumble motors.
  60
  61 3. Detection
  62 ~~~~~~~~~~~~
  63 All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
  64 an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
  65 However, not all gamepads provide all features, so you need to test for all
  66 features that you need, first. How each feature is mapped is described below.
  67
  68 Legacy drivers often don't comply to these rules. As we cannot change them
  69 for backwards-compatibility reasons, you need to provide fixup mappings in
  70 user-space yourself. Some of them might also provide module-options that
  71 change the mappings so you can advise users to set these.
  72
  73 All new gamepads are supposed to comply with this mapping. Please report any
  74 bugs, if they don't.
  75
  76 There are a lot of less-featured/less-powerful devices out there, which re-use
  77 the buttons from this protocol. However, they try to do this in a compatible
  78 fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
  79 and one analog stick. It reports them as if it were a gamepad with only one
  80 analog stick and two trigger buttons on the right side.
  81 But that means, that if you only support "real" gamepads, you must test
  82 devices for _all_ reported events that you need. Otherwise, you will also get
  83 devices that report a small subset of the events.
  84
  85 No other devices, that do not look/feel like a gamepad, shall report these
  86 events.
  87
  88 4. Events
  89 ~~~~~~~~~
  90 Gamepads report the following events:
  91
  92 Action-Pad:
  93   Every gamepad device has at least 2 action buttons. This means, that every
  94   device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
  95   of the labels on the buttons, the codes are sent according to the
  96   physical position of the buttons.
  97   Please note that 2- and 3-button pads are fairly rare and old. You might
  98   want to filter gamepads that do not report all four.
  99     2-Button Pad:
 100       If only 2 action-buttons are present, they are reported as BTN_SOUTH and
 101       BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
 102       horizontal layouts, the button more on the right is BTN_EAST.
 103     3-Button Pad:
 104       If only 3 action-buttons are present, they are reported as (from left
 105       to right): BTN_WEST, BTN_SOUTH, BTN_EAST
 106       If the buttons are aligned perfectly vertically, they are reported as
 107       (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST
 108     4-Button Pad:
 109       If all 4 action-buttons are present, they can be aligned in two
 110       different formations. If diamond-shaped, they are reported as BTN_NORTH,
 111       BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.
 112       If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left
 113       is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.
 114
 115 D-Pad:
 116   Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right
 117   Some of these are available as digital buttons, some as analog buttons. Some
 118   may even report both. The kernel does not convert between these so
 119   applications should support both and choose what is more appropriate if
 120   both are reported.
 121     Digital buttons are reported as:
 122       BTN_DPAD_*
 123     Analog buttons are reported as:
 124       ABS_HAT0X and ABS_HAT0Y
 125       (for ABS values negative is left/up, positive is right/down)
 126
 127 Analog-Sticks:
 128   The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
 129   reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
 130   If analog-sticks provide digital buttons, they are mapped accordingly as
 131   BTN_THUMBL (first/left) and BTN_THUMBR (second/right).
 132     (for ABS values negative is left/up, positive is right/down)
 133
 134 Triggers:
 135   Trigger buttons can be available as digital or analog buttons or both. User-
 136   space must correctly deal with any situation and choose the most appropriate
 137   mode.
 138   Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
 139   or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
 140   ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).
 141   If only one trigger-button combination is present (upper+lower), they are
 142   reported as "right" triggers (BTN_TR/ABS_HAT1X).
 143     (ABS trigger values start at 0, pressure is reported as positive values)
 144
 145 Menu-Pad:
 146   Menu buttons are always digital and are mapped according to their location
 147   instead of their labels. That is:
 148     1-button Pad: Mapped as BTN_START
 149     2-button Pad: Left button mapped as BTN_SELECT, right button mapped as
 150                   BTN_START
 151   Many pads also have a third button which is branded or has a special symbol
 152   and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
 153   "HOME" button, the XBox "X"-button or Sony "PS" button.
 154
 155 Rumble:
 156   Rumble is advertised as FF_RUMBLE.
 157
 158 ----------------------------------------------------------------------------
 159   Written 2013 by David Herrmann <dh.herrmann@gmail.com>