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