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