gamepad.rst 7.3 KB

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