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