| 1 | ---------------------------
|
| 2 | Linux Gamepad Specification
|
| 3 | ---------------------------
|
| 4 |
|
| 5 | :Author: 2013 by David Herrmann <[email protected]>
|
| 6 |
|
| 7 |
|
| 8 | Introduction
|
| 9 | ~~~~~~~~~~~~
|
| 10 | Linux provides many different input drivers for gamepad hardware. To avoid
|
| 11 | having user-space deal with different button-mappings for each gamepad, this
|
| 12 | document defines how gamepads are supposed to report their data.
|
| 13 |
|
| 14 | Geometry
|
| 15 | ~~~~~~~~
|
| 16 | As "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 |
|
| 41 | Most 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 |
|
| 66 | Detection
|
| 67 | ~~~~~~~~~
|
| 68 |
|
| 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.
|
| 71 | However, not all gamepads provide all features, so you need to test for all
|
| 72 | features that you need, first. How each feature is mapped is described below.
|
| 73 |
|
| 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
|
| 77 | change the mappings so you can advise users to set these.
|
| 78 |
|
| 79 | All new gamepads are supposed to comply with this mapping. Please report any
|
| 80 | bugs, if they don't.
|
| 81 |
|
| 82 | There are a lot of less-featured/less-powerful devices out there, which reuse
|
| 83 | the buttons from this protocol. However, they try to do this in a compatible
|
| 84 | fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
|
| 85 | and one analog stick. It reports them as if it were a gamepad with only one
|
| 86 | analog stick and two trigger buttons on the right side.
|
| 87 | But that means, that if you only support "real" gamepads, you must test
|
| 88 | devices for _all_ reported events that you need. Otherwise, you will also get
|
| 89 | devices that report a small subset of the events.
|
| 90 |
|
| 91 | No other devices, that do not look/feel like a gamepad, shall report these
|
| 92 | events.
|
| 93 |
|
| 94 | Events
|
| 95 | ~~~~~~
|
| 96 |
|
| 97 | Gamepads 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 the Sony PlayStation "PS" button.
|
| 188 |
|
| 189 | - Rumble:
|
| 190 |
|
| 191 | Rumble is advertised as FF_RUMBLE.
|
| 192 |
|
| 193 | - Grip buttons:
|
| 194 |
|
| 195 | Many pads include buttons on the rear, usually referred to as either grip or
|
| 196 | rear buttons, or paddles. These are often reprogrammable by the firmware to
|
| 197 | appear as "normal" buttons, but are sometimes exposed to software too. Some
|
| 198 | notable examples of this are the Steam Deck, which has R4, R5, L4, and L5 on
|
| 199 | the back; the Xbox Elite pads, which have P1-P4; and the Switch 2 Pro
|
| 200 | Controller, which has GL and GR.
|
| 201 |
|
| 202 | For these controllers, BTN_GRIPR and BTN_GRIPR2 should be used for the top
|
| 203 | and bottom (if present) right grip button(s), and BTN_GRIPL and BTN_GRIPL2
|
| 204 | should be used for the top and bottom (if present) left grip button(s).
|
| 205 |
|
| 206 | - Profile:
|
| 207 |
|
| 208 | Some pads provide a multi-value profile selection switch. Examples include
|
| 209 | the Xbox Adaptive and the Xbox Elite 2 controllers. When the active profile
|
| 210 | is switched, its newly selected value is emitted as an ABS_PROFILE event.
|