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