0001 ---------------------------
0002 Linux Gamepad Specification
0003 ---------------------------
0004
0005 :Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
0006
0007
0008 Introduction
0009 ~~~~~~~~~~~~
0010 Linux provides many different input drivers for gamepad hardware. To avoid
0011 having user-space deal with different button-mappings for each gamepad, this
0012 document defines how gamepads are supposed to report their data.
0013
0014 Geometry
0015 ~~~~~~~~
0016 As "gamepad" we define devices which roughly look like this::
0017
0018 ____________________________ __
0019 / [__ZL__] [__ZR__] \ |
0020 / [__ TL __] [__ TR __] \ | Front Triggers
0021 __/________________________________\__ __|
0022 / _ \ |
0023 / /\ __ (N) \ |
0024 / || __ |MO| __ _ _ \ | Main Pad
0025 | <===DP===> |SE| |ST| (W) -|- (E) | |
0026 \ || ___ ___ _ / |
0027 /\ \/ / \ / \ (S) /\ __|
0028 / \________ | LS | ____ | RS | ________/ \ |
0029 | / \ \___/ / \ \___/ / \ | | Control Sticks
0030 | / \_____/ \_____/ \ | __|
0031 | / \ |
0032 \_____/ \_____/
0033
0034 |________|______| |______|___________|
0035 D-Pad Left Right Action Pad
0036 Stick Stick
0037
0038 |_____________|
0039 Menu Pad
0040
0041 Most gamepads have the following features:
0042
0043 - Action-Pad
0044 4 buttons in diamonds-shape (on the right side). The buttons are
0045 differently labeled on most devices so we define them as NORTH,
0046 SOUTH, WEST and EAST.
0047 - D-Pad (Direction-pad)
0048 4 buttons (on the left side) that point up, down, left and right.
0049 - Menu-Pad
0050 Different constellations, but most-times 2 buttons: SELECT - START
0051 Furthermore, many gamepads have a fancy branded button that is used as
0052 special system-button. It often looks different to the other buttons and
0053 is used to pop up system-menus or system-settings.
0054 - Analog-Sticks
0055 Analog-sticks provide freely moveable sticks to control directions. Not
0056 all devices have both or any, but they are present at most times.
0057 Analog-sticks may also provide a digital button if you press them.
0058 - Triggers
0059 Triggers are located on the upper-side of the pad in vertical direction.
0060 Not all devices provide them, but the upper buttons are normally named
0061 Left- and Right-Triggers, the lower buttons Z-Left and Z-Right.
0062 - Rumble
0063 Many devices provide force-feedback features. But are mostly just
0064 simple rumble motors.
0065
0066 Detection
0067 ~~~~~~~~~
0068
0069 All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
0070 an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
0071 However, not all gamepads provide all features, so you need to test for all
0072 features that you need, first. How each feature is mapped is described below.
0073
0074 Legacy drivers often don't comply to these rules. As we cannot change them
0075 for backwards-compatibility reasons, you need to provide fixup mappings in
0076 user-space yourself. Some of them might also provide module-options that
0077 change the mappings so you can advise users to set these.
0078
0079 All new gamepads are supposed to comply with this mapping. Please report any
0080 bugs, if they don't.
0081
0082 There are a lot of less-featured/less-powerful devices out there, which re-use
0083 the buttons from this protocol. However, they try to do this in a compatible
0084 fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
0085 and one analog stick. It reports them as if it were a gamepad with only one
0086 analog stick and two trigger buttons on the right side.
0087 But that means, that if you only support "real" gamepads, you must test
0088 devices for _all_ reported events that you need. Otherwise, you will also get
0089 devices that report a small subset of the events.
0090
0091 No other devices, that do not look/feel like a gamepad, shall report these
0092 events.
0093
0094 Events
0095 ~~~~~~
0096
0097 Gamepads report the following events:
0098
0099 - Action-Pad:
0100
0101 Every gamepad device has at least 2 action buttons. This means, that every
0102 device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
0103 of the labels on the buttons, the codes are sent according to the
0104 physical position of the buttons.
0105
0106 Please note that 2- and 3-button pads are fairly rare and old. You might
0107 want to filter gamepads that do not report all four.
0108
0109 - 2-Button Pad:
0110
0111 If only 2 action-buttons are present, they are reported as BTN_SOUTH and
0112 BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
0113 horizontal layouts, the button more on the right is BTN_EAST.
0114
0115 - 3-Button Pad:
0116
0117 If only 3 action-buttons are present, they are reported as (from left
0118 to right): BTN_WEST, BTN_SOUTH, BTN_EAST
0119 If the buttons are aligned perfectly vertically, they are reported as
0120 (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST
0121
0122 - 4-Button Pad:
0123
0124 If all 4 action-buttons are present, they can be aligned in two
0125 different formations. If diamond-shaped, they are reported as BTN_NORTH,
0126 BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.
0127 If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left
0128 is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.
0129
0130 - D-Pad:
0131
0132 Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right
0133 Some of these are available as digital buttons, some as analog buttons. Some
0134 may even report both. The kernel does not convert between these so
0135 applications should support both and choose what is more appropriate if
0136 both are reported.
0137
0138 - Digital buttons are reported as:
0139
0140 BTN_DPAD_*
0141
0142 - Analog buttons are reported as:
0143
0144 ABS_HAT0X and ABS_HAT0Y
0145
0146 (for ABS values negative is left/up, positive is right/down)
0147
0148 - Analog-Sticks:
0149
0150 The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
0151 reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
0152 If analog-sticks provide digital buttons, they are mapped accordingly as
0153 BTN_THUMBL (first/left) and BTN_THUMBR (second/right).
0154
0155 (for ABS values negative is left/up, positive is right/down)
0156
0157 - Triggers:
0158
0159 Trigger buttons can be available as digital or analog buttons or both. User-
0160 space must correctly deal with any situation and choose the most appropriate
0161 mode.
0162
0163 Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
0164 or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
0165 ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).
0166
0167 If only one trigger-button combination is present (upper+lower), they are
0168 reported as "right" triggers (BTN_TR/ABS_HAT1X).
0169
0170 (ABS trigger values start at 0, pressure is reported as positive values)
0171
0172 - Menu-Pad:
0173
0174 Menu buttons are always digital and are mapped according to their location
0175 instead of their labels. That is:
0176
0177 - 1-button Pad:
0178
0179 Mapped as BTN_START
0180
0181 - 2-button Pad:
0182
0183 Left button mapped as BTN_SELECT, right button mapped as BTN_START
0184
0185 Many pads also have a third button which is branded or has a special symbol
0186 and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
0187 "HOME" button, the XBox "X"-button or Sony "PS" button.
0188
0189 - Rumble:
0190
0191 Rumble is advertised as FF_RUMBLE.
