1 ---------------------------
2 Linux Gamepad Specification
3 ---------------------------
4
5 :Author: 2013 by David Herrmann <dh.herrmann@gm
6
7
8 Introduction
9 ~~~~~~~~~~~~
10 Linux provides many different input drivers fo
11 having user-space deal with different button-m
12 document defines how gamepads are supposed to
13
14 Geometry
15 ~~~~~~~~
16 As "gamepad" we define devices which roughly l
17
18 ____________________________
19 / [__ZL__] [__ZR__] \
20 / [__ TL __] [__ TR __] \
21 __/________________________________\__
22 / _ \
23 / /\ __ (N)
24 / || __ |MO| __ _ _
25 | <===DP===> |SE| |ST| (W) -|- (E
26 \ || ___ ___ _
27 /\ \/ / \ / \ (S)
28 / \________ | LS | ____ | RS | ________/
29 | / \ \___/ / \ \___/ / \
30 | / \_____/ \_____/ \
31 | / \
32 \_____/ \___
33
34 |________|______| |______|__________
35 D-Pad Left Right Action Pa
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
45 differently labeled on most devices so we
46 SOUTH, WEST and EAST.
47 - D-Pad (Direction-pad)
48 4 buttons (on the left side) that point up
49 - Menu-Pad
50 Different constellations, but most-times 2
51 Furthermore, many gamepads have a fancy br
52 special system-button. It often looks diff
53 is used to pop up system-menus or system-s
54 - Analog-Sticks
55 Analog-sticks provide freely moveable stic
56 all devices have both or any, but they are
57 Analog-sticks may also provide a digital b
58 - Triggers
59 Triggers are located on the upper-side of
60 Not all devices provide them, but the uppe
61 Left- and Right-Triggers, the lower button
62 - Rumble
63 Many devices provide force-feedback featur
64 simple rumble motors.
65
66 Detection
67 ~~~~~~~~~
68
69 All gamepads that follow the protocol describe
70 an alias for BTN_SOUTH/BTN_A. It can be used t
71 However, not all gamepads provide all features
72 features that you need, first. How each featur
73
74 Legacy drivers often don't comply to these rul
75 for backwards-compatibility reasons, you need
76 user-space yourself. Some of them might also p
77 change the mappings so you can advise users to
78
79 All new gamepads are supposed to comply with t
80 bugs, if they don't.
81
82 There are a lot of less-featured/less-powerful
83 the buttons from this protocol. However, they
84 fashion. For example, the "Nintendo Wii Nunchu
85 and one analog stick. It reports them as if it
86 analog stick and two trigger buttons on the ri
87 But that means, that if you only support "real
88 devices for _all_ reported events that you nee
89 devices that report a small subset of the even
90
91 No other devices, that do not look/feel like a
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 b
102 device reports BTN_SOUTH (which BTN_GAMEPAD
103 of the labels on the buttons, the codes are
104 physical position of the buttons.
105
106 Please note that 2- and 3-button pads are fa
107 want to filter gamepads that do not report a
108
109 - 2-Button Pad:
110
111 If only 2 action-buttons are present, th
112 BTN_EAST. For vertical layouts, the uppe
113 horizontal layouts, the button more on t
114
115 - 3-Button Pad:
116
117 If only 3 action-buttons are present, th
118 to right): BTN_WEST, BTN_SOUTH, BTN_EAST
119 If the buttons are aligned perfectly ver
120 (from top down): BTN_WEST, BTN_SOUTH, BT
121
122 - 4-Button Pad:
123
124 If all 4 action-buttons are present, the
125 different formations. If diamond-shaped,
126 BTN_WEST, BTN_SOUTH, BTN_EAST according
127 If rectangular-shaped, the upper-left bu
128 is BTN_WEST, lower-right is BTN_SOUTH an
129
130 - D-Pad:
131
132 Every gamepad provides a D-Pad with four dir
133 Some of these are available as digital butto
134 may even report both. The kernel does not co
135 applications should support both and choose
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, positiv
147
148 - Analog-Sticks:
149
150 The left analog-stick is reported as ABS_X,
151 reported as ABS_RX, ABS_RY. Zero, one or two
152 If analog-sticks provide digital buttons, th
153 BTN_THUMBL (first/left) and BTN_THUMBR (seco
154
155 (for ABS values negative is left/up, positiv
156
157 - Triggers:
158
159 Trigger buttons can be available as digital
160 space must correctly deal with any situation
161 mode.
162
163 Upper trigger buttons are reported as BTN_TR
164 or ABS_HAT1Y (left). Lower trigger buttons a
165 ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2
166
167 If only one trigger-button combination is pr
168 reported as "right" triggers (BTN_TR/ABS_HAT
169
170 (ABS trigger values start at 0, pressure is
171
172 - Menu-Pad:
173
174 Menu buttons are always digital and are mapp
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
184
185 Many pads also have a third button which is
186 and meaning. Such buttons are mapped as BTN_
187 "HOME" button, the Xbox "X" button or the So
188
189 - Rumble:
190
191 Rumble is advertised as FF_RUMBLE.
192
193 - Profile:
194
195 Some pads provide a multi-value profile sele
196 XBox Adaptive and the XBox Elite 2 controlle
197 switched, its newly selected value is emitte
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.