Documentation/input/gamepad.rst

1 ---------------------------
3 ---------------------------
11 having user-space deal with different button-mappings for each gamepad, this
16 As "gamepad" we define devices which roughly look like this::
25    |    <===DP===> |SE|      |ST|   (W) -|- (E) |       |
35          D-Pad    Left       Right   Action Pad
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,
47   - D-Pad (Direction-pad)
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
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.
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
69 All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
70 an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
72 features that you need, first. How each feature is mapped is described below.
74 Legacy drivers often don't comply to these rules. As we cannot change them
75 for backwards-compatibility reasons, you need to provide fixup mappings in
76 user-space yourself. Some of them might also provide module-options that
82 There are a lot of less-featured/less-powerful devices out there, which re-use
85 and one analog stick. It reports them as if it were a gamepad with only one
99 - Action-Pad:
102   device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
106   Please note that 2- and 3-button pads are fairly rare and old. You might
109     - 2-Button Pad:
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.
115     - 3-Button Pad:
117       If only 3 action-buttons are present, they are reported as (from left
119       If the buttons are aligned perfectly vertically, they are reported as
122     - 4-Button Pad:
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,
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.
130 - D-Pad:
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
135   applications should support both and choose what is more appropriate if
138     - Digital buttons are reported as:
142     - Analog buttons are reported as:
146   (for ABS values negative is left/up, positive is right/down)
148 - Analog-Sticks:
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
155   (for ABS values negative is left/up, positive is right/down)
157 - Triggers:
159   Trigger buttons can be available as digital or analog buttons or both. User-
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
167   If only one trigger-button combination is present (upper+lower), they are
168   reported as "right" triggers (BTN_TR/ABS_HAT1X).
170   (ABS trigger values start at 0, pressure is reported as positive values)
172 - Menu-Pad:
175   instead of their labels. That is:
177     - 1-button Pad:
179       Mapped as BTN_START
181     - 2-button Pad:
183       Left button mapped as BTN_SELECT, right button mapped as BTN_START
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
189 - Rumble:
191   Rumble is advertised as FF_RUMBLE.
193 - Profile:
195   Some pads provide a multi-value profile selection switch.  An example is the
196   XBox Adaptive and the XBox Elite 2 controllers.  When the active profile is
197   switched, its newly selected value is emitted as an ABS_PROFILE event.