| Linux Gamepad API | |
| ---------------------------------------------------------------------------- | |
| 1. Intro | |
| ~~~~~~~~ | |
| Linux provides many different input drivers for gamepad hardware. To avoid | |
| having user-space deal with different button-mappings for each gamepad, this | |
| document defines how gamepads are supposed to report their data. | |
| 2. Geometry | |
| ~~~~~~~~~~~ | |
| As "gamepad" we define devices which roughly look like this: | |
| ____________________________ __ | |
| / [__ZL__] [__ZR__] \ | | |
| / [__ TL __] [__ TR __] \ | Front Triggers | |
| __/________________________________\__ __| | |
| / _ \ | | |
| / /\ __ (N) \ | | |
| / || __ |MO| __ _ _ \ | Main Pad | |
| | <===DP===> |SE| |ST| (W) -|- (E) | | | |
| \ || ___ ___ _ / | | |
| /\ \/ / \ / \ (S) /\ __| | |
| / \________ | LS | ____ | RS | ________/ \ | | |
| | / \ \___/ / \ \___/ / \ | | Control Sticks | |
| | / \_____/ \_____/ \ | __| | |
| | / \ | | |
| \_____/ \_____/ | |
| |________|______| |______|___________| | |
| D-Pad Left Right Action Pad | |
| Stick Stick | |
| |_____________| | |
| Menu Pad | |
| Most gamepads have the following features: | |
| - Action-Pad | |
| 4 buttons in diamonds-shape (on the right side). The buttons are | |
| differently labeled on most devices so we define them as NORTH, | |
| SOUTH, WEST and EAST. | |
| - D-Pad (Direction-pad) | |
| 4 buttons (on the left side) that point up, down, left and right. | |
| - Menu-Pad | |
| Different constellations, but most-times 2 buttons: SELECT - START | |
| Furthermore, many gamepads have a fancy branded button that is used as | |
| special system-button. It often looks different to the other buttons and | |
| is used to pop up system-menus or system-settings. | |
| - Analog-Sticks | |
| Analog-sticks provide freely moveable sticks to control directions. Not | |
| all devices have both or any, but they are present at most times. | |
| Analog-sticks may also provide a digital button if you press them. | |
| - Triggers | |
| Triggers are located on the upper-side of the pad in vertical direction. | |
| Not all devices provide them, but the upper buttons are normally named | |
| Left- and Right-Triggers, the lower buttons Z-Left and Z-Right. | |
| - Rumble | |
| Many devices provide force-feedback features. But are mostly just | |
| simple rumble motors. | |
| 3. Detection | |
| ~~~~~~~~~~~~ | |
| All gamepads that follow the protocol described here map BTN_GAMEPAD. This is | |
| an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such. | |
| However, not all gamepads provide all features, so you need to test for all | |
| features that you need, first. How each feature is mapped is described below. | |
| Legacy drivers often don't comply to these rules. As we cannot change them | |
| for backwards-compatibility reasons, you need to provide fixup mappings in | |
| user-space yourself. Some of them might also provide module-options that | |
| change the mappings so you can advise users to set these. | |
| All new gamepads are supposed to comply with this mapping. Please report any | |
| bugs, if they don't. | |
| There are a lot of less-featured/less-powerful devices out there, which re-use | |
| the buttons from this protocol. However, they try to do this in a compatible | |
| fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons | |
| and one analog stick. It reports them as if it were a gamepad with only one | |
| analog stick and two trigger buttons on the right side. | |
| But that means, that if you only support "real" gamepads, you must test | |
| devices for _all_ reported events that you need. Otherwise, you will also get | |
| devices that report a small subset of the events. | |
| No other devices, that do not look/feel like a gamepad, shall report these | |
| events. | |
| 4. Events | |
| ~~~~~~~~~ | |
| Gamepads report the following events: | |
| Action-Pad: | |
| Every gamepad device has at least 2 action buttons. This means, that every | |
| device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless | |
| of the labels on the buttons, the codes are sent according to the | |
| physical position of the buttons. | |
| Please note that 2- and 3-button pads are fairly rare and old. You might | |
| want to filter gamepads that do not report all four. | |
| 2-Button Pad: | |
| If only 2 action-buttons are present, they are reported as BTN_SOUTH and | |
| BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For | |
| horizontal layouts, the button more on the right is BTN_EAST. | |
| 3-Button Pad: | |
| If only 3 action-buttons are present, they are reported as (from left | |
| to right): BTN_WEST, BTN_SOUTH, BTN_EAST | |
| If the buttons are aligned perfectly vertically, they are reported as | |
| (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST | |
| 4-Button Pad: | |
| If all 4 action-buttons are present, they can be aligned in two | |
| different formations. If diamond-shaped, they are reported as BTN_NORTH, | |
| BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location. | |
| If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left | |
| is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST. | |
| D-Pad: | |
| Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right | |
| Some of these are available as digital buttons, some as analog buttons. Some | |
| may even report both. The kernel does not convert between these so | |
| applications should support both and choose what is more appropriate if | |
| both are reported. | |
| Digital buttons are reported as: | |
| BTN_DPAD_* | |
| Analog buttons are reported as: | |
| ABS_HAT0X and ABS_HAT0Y | |
| (for ABS values negative is left/up, positive is right/down) | |
| Analog-Sticks: | |
| The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is | |
| reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present. | |
| If analog-sticks provide digital buttons, they are mapped accordingly as | |
| BTN_THUMBL (first/left) and BTN_THUMBR (second/right). | |
| (for ABS values negative is left/up, positive is right/down) | |
| Triggers: | |
| Trigger buttons can be available as digital or analog buttons or both. User- | |
| space must correctly deal with any situation and choose the most appropriate | |
| mode. | |
| Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL | |
| or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or | |
| ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL). | |
| If only one trigger-button combination is present (upper+lower), they are | |
| reported as "right" triggers (BTN_TR/ABS_HAT1X). | |
| (ABS trigger values start at 0, pressure is reported as positive values) | |
| Menu-Pad: | |
| Menu buttons are always digital and are mapped according to their location | |
| instead of their labels. That is: | |
| 1-button Pad: Mapped as BTN_START | |
| 2-button Pad: Left button mapped as BTN_SELECT, right button mapped as | |
| BTN_START | |
| Many pads also have a third button which is branded or has a special symbol | |
| and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo | |
| "HOME" button, the XBox "X"-button or Sony "PS" button. | |
| Rumble: | |
| Rumble is advertised as FF_RUMBLE. | |
| ---------------------------------------------------------------------------- | |
| Written 2013 by David Herrmann <dh.herrmann@gmail.com> |