About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / input / gamepad.txt


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

1	                            Linux Gamepad API
2	----------------------------------------------------------------------------
3	
4	1. Intro
5	~~~~~~~~
6	Linux provides many different input drivers for gamepad hardware. To avoid
7	having user-space deal with different button-mappings for each gamepad, this
8	document defines how gamepads are supposed to report their data.
9	
10	2. Geometry
11	~~~~~~~~~~~
12	As "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	
37	Most 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	
61	3. Detection
62	~~~~~~~~~~~~
63	All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
64	an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
65	However, not all gamepads provide all features, so you need to test for all
66	features that you need, first. How each feature is mapped is described below.
67	
68	Legacy drivers often don't comply to these rules. As we cannot change them
69	for backwards-compatibility reasons, you need to provide fixup mappings in
70	user-space yourself. Some of them might also provide module-options that
71	change the mappings so you can advise users to set these.
72	
73	All new gamepads are supposed to comply with this mapping. Please report any
74	bugs, if they don't.
75	
76	There are a lot of less-featured/less-powerful devices out there, which re-use
77	the buttons from this protocol. However, they try to do this in a compatible
78	fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
79	and one analog stick. It reports them as if it were a gamepad with only one
80	analog stick and two trigger buttons on the right side.
81	But that means, that if you only support "real" gamepads, you must test
82	devices for _all_ reported events that you need. Otherwise, you will also get
83	devices that report a small subset of the events.
84	
85	No other devices, that do not look/feel like a gamepad, shall report these
86	events.
87	
88	4. Events
89	~~~~~~~~~
90	Gamepads report the following events:
91	
92	Action-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	
115	D-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	
127	Analog-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	
134	Triggers:
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	
145	Menu-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	
155	Rumble:
156	  Rumble is advertised as FF_RUMBLE.
157	
158	----------------------------------------------------------------------------
159	  Written 2013 by David Herrmann <dh.herrmann@gmail.com>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog