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