Add list of controller profiles

Signed-off-by: Mattias Andrée <maandree@kth.se>

2 files changed, 1053 insertions, 1 deletions

diff --git a/TODO b/TODO
index fd8cdc5..cd2f714 100644
--- a/TODO
+++ b/TODO
@@ -1,6 +1,7 @@
+Add support for profiles (conformation, button names/shapes/colours, controller layout images)
 Add support for quirks
 Add support for leds
-Add support for accelerometer
+Add support for accelerometer and gyroscope
 Add support for creating instance from a file descriptor
 Add man pages
 Add readme file
diff --git a/libgamepad.h b/libgamepad.h
index 46a09e2..0e70cba 100644
--- a/libgamepad.h
+++ b/libgamepad.h
@@ -38,6 +38,1057 @@ enum libgamepad_attachment_event_type {
 
 
 /**
+ * Device categorisation
+ */
+enum libgamepad_class {
+	/**
+	 * Unknown category
+	 */
+	LIBGAMEPAD_CLASS_UNKNOWN,
+
+	/**
+	 * Unlisted category
+	 */
+	LIBGAMEPAD_CLASS_OTHER,
+
+	/**
+	 * Game controller
+	 */
+	LIBGAMEPAD_CLASS_GAME_CONTROLLER,
+
+	/**
+	 * Joystick
+	 */
+	LIBGAMEPAD_CLASS_JOYSTICK,
+
+	/**
+	 * Steering wheel
+	 */
+	LIBGAMEPAD_CLASS_STEERING_WHEEL,
+
+	/**
+	 * TV remote controller
+	 */
+	LIBGAMEPAD_CLASS_TV_CONTROLLER,
+
+	/**
+	 * 3D modelling mouse
+	 */
+	LIBGAMEPAD_CLASS_3D_MOUSE,
+
+	/**
+	 * Motion sensor (typically camera)
+	 */
+	LIBGAMEPAD_CLASS_MOTION_SENSOR,
+
+	/**
+	 * Piano or similar instrument
+	 */
+	LIBGAMEPAD_CLASS_PIANO,
+
+	/**
+	 * Guitar
+	 */
+	LIBGAMEPAD_CLASS_GUITAR,
+
+	/**
+	 * Drum set
+	 */
+	LIBGAMEPAD_CLASS_DRUMS,
+
+	/**
+	 * Gun
+	 */
+	LIBGAMEPAD_CLASS_GUN,
+
+	/**
+	 * Pen
+	 */
+	LIBGAMEPAD_CLASS_PEN,
+
+	/**
+	 * Non-interactive sensor,
+	 * e.g. accelerometer built into laptop
+	 */
+	LIBGAMEPAD_CLASS_SENSOR
+};
+
+
+/**
+ * Game controller profiles
+ * 
+ * This list only contains well-known profiles, mainly
+ * the primary controllers from video gaming consoles
+ * and handheld gaming consoles
+ */
+enum libgamepad_game_controller {
+	/**
+	 * Unknown controller profile
+	 */
+	LIBGAMEPAD_CONTROLLER_UNKNOWN,
+
+	/**
+	 * Unlisted controller profile
+	 */
+	LIBGAMEPAD_CONTROLLER_OTHER,
+
+	/* TODO force feedback capabilities */
+
+	/**
+	 * Amazon Luna Controller
+	 * 
+	 * Released 2022-03-01 for Amazon Luna
+	 * 
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "Y"
+	 *     - West  = "X"
+	 *     - South = "A"
+	 *     - East  = "B"
+	 *     Digital button "LB" at upper left index finger position
+	 *     Digital button "RB" at upper right index finger position
+	 *     Analogue button "LT" at lower left index finger position
+	 *     Analogue button "RT" at lower right index finger position
+	 *     Four buttons at upper centre position:
+	 *     - West   = Home (icon: circle)
+	 *     - Centre = Action (icon: brand)
+	 *     - East   = Menu (icon: three vertically stacked horizontal line)
+	 *     - South  = Microphone (icon: microphone)
+	 * 
+	 * Other features:
+	 * - Built in microphone
+	 * - Stereo headset port
+	 * - Wireless via WiFi
+	 * - Wireless via Bluetooth Low Energi 4.2
+	 * - RGB LED on Action button (??)
+	 */
+	LIBGAMEPAD_CONTROLLER_AMAZON_LUNA,
+
+	/**
+	 * DualSense
+	 * 
+	 * Released 2020-11-12 for PlayStation 5
+	 * 
+	 * Layout:
+	 *     Digital D-pad at upper left thumb position
+	 *     Clickable analogue stick at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = Triangle
+	 *     - West  = Square
+	 *     - South = Cross
+	 *     - East  = Circle
+	 *     Digital button "L1" at upper left index finger position
+	 *     Digital button "R1" at upper right index finger position
+	 *     Analogue button "L2" at lower left index finger position
+	 *     Analogue button "R2" at lower right index finger position
+	 *     Digital Create (logo: \|/) button north east of D-pad
+	 *     Digital Options (logo: three vertically stacked horizontal line)
+	 *       button north west of upper right thumb position
+	 *     Two digital buttons between analogue stick:
+	 *     - North = PS (icon: brand)
+	 *     - South = Microphone mute (icon: NW-to-SE diagonally crossed out microphone)
+	 *     Clickable 2-point capacitive touchpad between upper thumb positions
+	 * 
+	 * Other features:
+	 * - Built in dual-microphone array
+	 * - Built in single-channel speaker
+	 * - Stereo headset port
+	 * - Extension port
+	 * - Wireless via WiFi
+	 * - Wireless via Bluetooth 5.1
+	 * - RGB LED
+	 * - 5 digital LEDs
+	 * - 3 axis accelerometer
+	 * - 3 axis gyroscope
+	 */
+	LIBGAMEPAD_CONTROLLER_DUAL_SENSE,
+
+	/**
+	 * Google Stadia Controller
+	 * 
+	 * Released 2019-11-19 for Google Stadia
+	 *
+	 * Layout:
+	 *     Digital D-pad at upper left thumb position
+	 *     Clickable analogue stick at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "Y"
+	 *     - West  = "X"
+	 *     - South = "A"
+	 *     - East  = "B"
+	 *     Digital button "L1" at upper left index finger position
+	 *     Digital button "R1" at upper right index finger position
+	 *     Analogue button "L2" at lower left index finger position
+	 *     Analogue button "R2" at lower right index finger position
+	 *     Digital Stadia (icon: brand) button between analogue sticks
+	 *     2 digital buttons at inner left thumb position:
+	 *     - North = Options (icon: three horizontally stacked dots)
+	 *     - East  = Google Assistant (icon: four uniquely arrayed dots)
+	 *     2 digital buttons at inner right thumb position:
+	 *     - North = Menu (icon: three vertically stacked horizontal lines)
+	 *     - West  = Capture (icon: corners of a square)
+	 * 
+	 * Other features:
+	 * - Built in microphone (??)
+	 * - Stereo headset port
+	 * - Wireless via WiFi
+	 * - Wireless via Bluetooth Low Energi 4.2
+	 * - LED (unknown capabilities)
+	 */
+	LIBGAMEPAD_CONTROLLER_GOOGLE_STADIA,
+
+	/**
+	 * Nintendo Switch Pro Controller
+	 * 
+	 * Released 2017-03-03 for Nintendo Switch
+	 * 
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "X"
+	 *     - West  = "Y"
+	 *     - South = "B"
+	 *     - East  = "A"
+	 *     Digital button "L" at upper left index finger position
+	 *     Digital button "R" at upper right index finger position
+	 *     Digital button "ZL" at lower left index finger position
+	 *     Digital button "ZR" at lower right index finger position
+	 *     Digital Stadia (icon: brand) button between analogue sticks
+	 *     2 digital buttons at inner left thumb position:
+	 *     - North = "−"
+	 *     - East  = Capture (icon: circle; shape: square)
+	 *     2 digital buttons at inner right thumb position:
+	 *     - North = "+"
+	 *     - West  = Home (icon: house)
+	 * 
+	 * Other features:
+	 * - Wireless via Bluetooth
+	 * - Wireless via NFC
+	 * - Accelerometer (3 axis??)
+	 * - Gyroscope (3 axis??)
+	 * - 4 digital LEDs (??)
+	 * 
+	 * Some versions seem to have additional features
+	 */
+	LIBGAMEPAD_CONTROLLER_NINTENDO_SWITCH_PRO,
+
+	/**
+	 * Joy-Con L
+	 * 
+	 * Released 2017-03-03 for Nintendo Switch
+	 * 
+	 * Layout (when rotated 90 degrees counter-clockwise to become horizontal):
+	 *     Clickable analogue stick at left thumb position
+	 *     4 digital directional buttons stick a bit inwards of right thumb position
+	 *     Digital "−" button north west of analogue stick
+	 *     Digital Capture (icon: circle; shape: square)
+	 *       button north east of directional buttons
+	 *     On front side (hidden when attached):
+	 *       Digital "SL" at left index finger position
+	 *       Digital "SR" at right index finger position
+	 *       Digital synchronisaton button left of "SR"
+	 * 
+	 * Additional layout (described from attached state):
+	 *     Digital "L" button at upper left index finger position
+	 *     Digital "ZL" button at lower left index finger position
+	 * 
+	 * Other features:
+	 * - Wireless via Bluetooth 3.0
+	 * - Accelerometer (3 axis??)
+	 * - Gyroscope (3 axis??)
+	 * - 4 digital LEDs, hidden when attached (??)
+	 */
+	LIBGAMEPAD_CONTROLLER_JOY_CON_L,
+
+	/**
+	 * Joy-Con R
+	 * 
+	 * Released 2017-03-03 for Nintendo Switch
+	 * 
+	 * Layout (when rotated 90 degrees clockwise to become horizontal):
+	 *     Clickable analogue stick a bit inwards of left thumb position
+	 *     4 digital buttons stick at right thumb position
+	 *     - North = "Y" ("X" when not rotated)
+	 *     - West  = "B" ("Y" when not rotated)
+	 *     - South = "A" ("B" when not rotated)
+	 *     - East  = "X" ("A" when not rotated)
+	 *     Digital "+" button north east of group of 4 digital buttons
+	 *     Digital Home (icon: house) button north west of analogue stick
+	 *     On front side (hidden when attached):
+	 *       Digital "SL" at left index finger position
+	 *       Digital "SR" at right index finger position
+	 *       Digital synchronisaton button left of "SR"
+	 * 
+	 * Additional layout (described from attached state):
+	 *     Digital "R" button at upper right index finger position
+	 *     Digital "ZR" button at lower right index finger position
+	 * 
+	 * Other features:
+	 * - Wireless via Bluetooth 3.0
+	 * - Wireless via NFC
+	 * - Accelerometer (3 axis??)
+	 * - Gyroscope (3 axis??)
+	 * - 4 digital LEDs, hidden when attached (??)
+	 * - Infrared depth camera for motion sensoring
+	 */
+	LIBGAMEPAD_CONTROLLER_JOY_CON_R,
+
+	/**
+	 * Joy-Con
+	 * 
+	 * Released 2017-03-03 for Nintendo Switch
+	 * 
+	 * Joy-Con L and Joy-Con R together in attached state
+	 */
+	LIBGAMEPAD_CONTROLLER_JOY_CON,
+
+	/**
+	 * Steam Controller
+	 * 
+	 * Released 2015-11-10 for Steam
+	 * 
+	 * TODO Document Steam Controller
+	 */
+	LIBGAMEPAD_CONTROLLER_STEAM,
+
+	/**
+	 * Xbox Wireless Controller
+	 * 
+	 * Released 2013-11-22 for Xbox One, also primary
+	 * controller for Xbox Series X and Xbox Series S
+	 * 
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position
+	 *     - North = "Y" (colour: yellow)
+	 *     - West  = "X" (colour: blue)
+	 *     - South = "A" (colour: green)
+	 *     - East  = "B" (colour: red)
+	 *     3 or 4 digital buttons at centre position
+	 *     - North = Xbox (icon: brand)
+	 *     - West  = View (icon: two z-stacked windows)
+	 *     - East  = Menu (icon: three vertically stacked horizontal lines)
+	 * 
+	 * Other features:
+	 * - Wireless via proprietary protocol
+	 * - Wireless via Bluetooth 4.0 (second revision)
+	 * - Stereo headset port (second revision)
+	 * - Extension port
+	 * 
+	 * Some versions have additional buttons.
+	 * "Y", "X", "A", and "B" are not coloured on some versions.
+	 */
+	LIBGAMEPAD_CONTROLLER_XBOX_WIRELESS,
+
+	/**
+	 * Xbox Wireless Controller, third revision
+	 * 
+	 * Released 2020-11-10 for Xbox Series X and Xbox Series S
+	 * 
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position
+	 *     - North = "Y" (colour: yellow)
+	 *     - West  = "X" (colour: blue)
+	 *     - South = "A" (colour: green)
+	 *     - East  = "B" (colour: red)
+	 *     3 or 4 digital buttons at centre position
+	 *     - North = Xbox (icon: brand)
+	 *     - West  = View (icon: two z-stacked windows)
+	 *     - South = Share (icon: flat rectangle with upper edge replace with an up-arrow)
+	 *     - East  = Menu (icon: three vertically stacked horizontal lines)
+	 * 
+	 * Other features:
+	 * - Wireless via proprietary protocol
+	 * - Wireless via Bluetooth Low Energy
+	 * - Stereo headset port
+	 * - Extension port
+	 * 
+	 * Some versions have additional buttons.
+	 * "Y", "X", "A", and "B" are not coloured on some versions.
+	 */
+	LIBGAMEPAD_CONTROLLER_XBOX_WIRELESS_REV_3,
+
+	/**
+	 * DualShock 4
+	 * 
+	 * Released 2013-11-15 for PlayStation 4
+	 * 
+	 * Layout:
+	 *     Digital D-pad at upper left thumb position
+	 *     Clickable analogue stick at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = Triangle (colour: green)
+	 *     - West  = Square (colour: pink)
+	 *     - South = Cross (colour: blue)
+	 *     - East  = Circle (colour: red)
+	 *     Digital button "L1" at upper left index finger position
+	 *     Digital button "R1" at upper right index finger position
+	 *     Analogue button "L2" at lower left index finger position
+	 *     Analogue button "R2" at lower right index finger position
+	 *     Digital "SHARE" button north east of D-pad
+	 *     Digital "OPTIONS" button north west of upper right thumb position
+	 *     Digital PS (icon: brand) button between analogue stick
+	 *     Clickable 2-point capacitive touchpad between upper thumb positions
+	 * 
+	 * Other features:
+	 * - Stereo headset port
+	 * - Extension port
+	 * - Wireless via Bluetooth 2.1+EDR
+	 * - RGB LED
+	 * - 3 axis accelerometer
+	 * - 3 axis gyroscope
+	 * - Built in single-channel speaker
+	 */
+	LIBGAMEPAD_CONTROLLER_DUAL_SHOCK_4,
+
+	/**
+	 * Ouya controller
+	 * 
+	 * Released 2013-06-25 for Ouya
+	 *
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "Y" (colour: orange–yellow)
+	 *     - West  = "U" (colour: blue)
+	 *     - South = "O" (colour: lime)
+	 *     - East  = "A" (colour: red)
+	 *     Digital Menu (icon: U inscribed in a ring) button between,
+	 *        but slightly below, the D-pad and right stick
+	 *     Touchpad (details missing) between upper thumb positions
+	 *     Digital button at upper left index finger position
+	 *     Digital button at upper right index finger position
+	 *     Analogue button at lower left index finger position
+	 *     Analogue button at lower right index finger position
+	 * 
+	 * Other features:
+	 * - Wireless via Bluetooth
+	 */
+	LIBGAMEPAD_CONTROLLER_OUYA,
+
+	/**
+	 * Wii U Pro Controller
+	 * 
+	 * Released 2012-11-18 for Wii U
+	 * 
+	 * TODO Document Wii U Pro Controller
+	 */
+	LIBGAMEPAD_CONTROLLER_WII_U_PRO,
+
+	/**
+	 * Wii U GamePad
+	 * 
+	 * Released 2012-11-18 for Wii U
+	 * 
+	 * TODO Document Wii U GamePad
+	 */
+	LIBGAMEPAD_CONTROLLER_WII_U,
+
+	/**
+	 * PlayStation Move Navigation controller
+	 * 
+	 * Released 2010-09-15 for PlayStation 3
+	 * 
+	 * TODO Document PlayStation Move Navigation controller
+	 */
+	LIBGAMEPAD_CONTROLLER_PLAYSTATION_MOVE_NAVIGATION,
+
+	/**
+	 * PlayStation Move
+	 * 
+	 * Released 2010-09-15 for PlayStation 3
+	 * 
+	 * TODO Document PlayStation Move
+	 */
+	LIBGAMEPAD_CONTROLLER_PLAYSTATION_MOVE,
+
+	/**
+	 * Classic Controller Pro
+	 * 
+	 * Released 2009-??-?? for Wii
+	 * 
+	 * TODO Document Classic Controller Pro
+	 */
+	LIBGAMEPAD_CONTROLLER_WII_CLASSIC_PRO,
+
+	/**
+	 * DualShock 3
+	 * 
+	 * Released 2007-11-11 for PlayStation 3
+	 * 
+	 * Note:
+	 * - Newer Linux drivers no longer report pressure on the D-pad
+	 * - Newer Linux drivers no longer report pressure L1, L2, Triangle, Square, Cross, or Circle
+	 * - Newer Linux drivers report one less motion axis than older drivers
+	 * - Older Linux drivers failed to report left pressure on the D-pad
+	 * 
+	 * Adds rumble support to `LIBGAMEPAD_CONTROLLER_SIXAXIS`
+	 */
+	LIBGAMEPAD_CONTROLLER_DUAL_SHOCK_3,
+
+	/**
+	 * Classic Controller
+	 * 
+	 * Released 2006-11-19 for Wii
+	 * 
+	 * TODO Document Classic Controller
+	 */
+	LIBGAMEPAD_CONTROLLER_WII_CLASSIC,
+
+	/**
+	 * Nunchuk
+	 * 
+	 * Released 2006-11-19 for Wii
+	 * 
+	 * TODO Document Nunchuk
+	 */
+	LIBGAMEPAD_CONTROLLER_NUNCHUK,
+
+	/**
+	 * Wii Remote
+	 * 
+	 * Released 2006-11-19 for Wii
+	 * 
+	 * TODO Document Wii Remote
+	 */
+	LIBGAMEPAD_CONTROLLER_WII_REMOTE,
+
+	/**
+	 * Wii Remote Plus
+	 * 
+	 * Released 2010-10-28 for Wii
+	 * 
+	 * Adds (3 axis?) gyroscope to `LIBGAMEPAD_CONTROLLER_WII_REMOTE`
+	 */
+	LIBGAMEPAD_CONTROLLER_WII_REMOTE_PLUS,
+
+	/**
+	 * Sixaxis
+	 * 
+	 * Released 2006-11-11 for PlayStation 3
+	 * 
+	 * Note:
+	 * - Newer Linux drivers no longer report pressure on the D-pad
+	 * - Newer Linux drivers no longer report pressure L1, L2, Triangle, Square, Cross, or Circle
+	 * - Newer Linux drivers report one less motion axis than older drivers
+	 * - Older Linux drivers failed to report left pressure on the D-pad
+	 * 
+	 * Layout:
+	 *     Pressure-sensitive D-pad at upper left thumb position
+	 *     Clickable analogue stick at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 Pressure-sensitive buttons at upper right thumb position:
+	 *     - North = Triangle (colour: green)
+	 *     - West  = Square (colour: pink)
+	 *     - South = Cross (colour: blue)
+	 *     - East  = Circle (colour: red)
+	 *     Pressure-sensitive button "L1" at upper left index finger position
+	 *     Pressure-sensitive button "R1" at upper right index finger position
+	 *     Analogue button "L2" at lower left index finger position
+	 *     Analogue button "R2" at lower right index finger position
+	 *     3 digital buttons at centre position:
+	 *     - West  = "SELECT" (shape: flat rectangle)
+	 *     - East  = "START"  (shape: flat play icon)
+	 *     - South = PS (icon: brand)
+	 * 
+	 * Other features:
+	 * - Stereo headset port
+	 * - Extension port
+	 * - Wireless via Bluetooth 2.1+EDR
+	 * - 4 digital LEDs numbered 1 through 4
+	 * - 3 axis accelerometer
+	 * - 3 axis gyroscope
+	 * - Built in single-channel speaker
+	 */
+	LIBGAMEPAD_CONTROLLER_SIXAXIS,
+
+	/**
+	 * Xbox 360 Controller
+	 * 
+	 * Released 2005-11-22 for Xbox 360
+	 * 
+	 * TODO Document Xbox 360 Controller
+	 */
+	LIBGAMEPAD_CONTROLLER_XBOX_360,
+
+	/**
+	 * Xbox Controller S
+	 * 
+	 * Released 2002-??-?? for Xbox
+	 * 
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 Pressure-sensitive buttons at upper right thumb position:
+	 *     - North = "Y" (colour: orange)
+	 *     - West  = "X" (colour: blue)
+	 *     - South = "A" (colour: green)
+	 *     - East  = "B" (colour: red)
+	 *     Digital button "L" at left index finger position
+	 *     Digital button "R" at right index finger position
+	 *     Analogue button "LT" at left long finger position
+	 *     Analogue button "RT" at right long finger position
+	 *     2 digital buttons west of lower left thumb position
+	 *     - North = "BACK" (icon: mirrored play icon)
+	 *     - East  = "START"  (icon: play icon)
+	 *     2 Pressure-sensitive  buttons east of lower right thumb position
+	 *     - East  = Black (colour: black)
+	 *     - South = White  (colour: white)
+	 */
+	LIBGAMEPAD_CONTROLLER_XBOX_S,
+
+	/**
+	 * Xbox Controller
+	 * 
+	 * Released 2001-11-15 for Xbox
+	 * 
+	 * Layout:
+	 *     Clickable analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     6 Pressure-sensitive buttons at upper right thumb position:
+	 *     - North = "Y" (colour: orange)
+	 *     - West  = "X" (colour: blue)
+	 *     - South = "A" (colour: green)
+	 *     - East  = "B" (colour: red)
+	 *     - North east (slightly off) of "Y" = White (colour: white)
+	 *     - North east (slightly off) of "B" = Black (colour: black)
+	 *     Digital button "L" at left index finger position
+	 *     Digital button "R" at right index finger position
+	 *     Analogue button "LT" at left long finger position
+	 *     Analogue button "RT" at right long finger position
+	 *     2 digital buttons at lower centre thumb position
+	 *     - East = "BACK" 
+	 *     - West = "START"
+	 */
+	LIBGAMEPAD_CONTROLLER_XBOX,
+
+	/**
+	 * Nintendo GameCube controller
+	 * 
+	 * Released 2001-09-14 for Nintendo GameCube
+	 * 
+	 * Layout:
+	 *     Analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     Analogue "C" (colour: yellow) stick at lower right thumb position
+	 *     4 digit buttons at upper right thumb position:
+	 *     - Centre           = "A" (colour: green; extra large)
+	 *     - South west       = "B" (colour: red)
+	 *     - North north west = "Y" (shape: circle arc)
+	 *     - North east east  = "X" (shape: circle arc)
+	 *     Digital button "Z" (colour: blue) at upper right index finger position
+	 *     Analogue button "L" at lower left index finger position
+	 *     Analogue button "R" at lower right index finger position
+	 *     Digital "START/PAUSE" button at centre thumb position
+	 * 
+	 * Other features:
+	 * - "L" and "R" sends digital signal when fully depressed
+	 */
+	LIBGAMEPAD_CONTROLLER_NINTENDO_GAME_CUBE,
+
+	/**
+	 * DualShock 2 Analog Controller
+	 * 
+	 * Released 2000-03-04 for PlayStation 2
+	 * 
+	 * Layout:
+	 *     Pressure-sensitive D-pad at upper left thumb position
+	 *     Clickable analogue stick at lower left thumb position
+	 *     Clickable analogue stick at lower right thumb position
+	 *     4 Pressure-sensitive buttons at upper right thumb position:
+	 *     - North = Triangle (colour: green)
+	 *     - West  = Square (colour: pink)
+	 *     - South = Cross (colour: blue)
+	 *     - East  = Circle (colour: red)
+	 *     Pressure-sensitive button "L1" at upper left index finger position
+	 *     Pressure-sensitive button "R1" at upper right index finger position
+	 *     Pressure-sensitive button "L2" at lower left index finger position
+	 *     Pressure-sensitive button "R2" at lower right index finger position
+	 *     2 digital buttons at centre position:
+	 *     - West = "SELECT" (shape: flat rectangle)
+	 *     - East = "START"  (shape: flat play icon)
+	 * 
+	 * Other features:
+	 * - LED-indicated digital "ANALOG" button at south part of center position
+	 *   for toggling between analogue and digital mode
+	 *   (TODO What does digital mode on DualShock 2 do?)
+	 */
+	LIBGAMEPAD_CONTROLLER_DUAL_SHOCK_2,
+
+	/**
+	 * Dreamcast controller
+	 * 
+	 * Released 1998-11-27 for Dreamcast
+	 * 
+	 * Layout:
+	 *     Analogue stick at upper left thumb position
+	 *     Digital D-pad at lower left thumb position
+	 *     4 digital buttons at upper right thumb position:
+	 *     - North = "Y" (colour: green)
+	 *     - West  = "X" (colour: yellow)
+	 *     - South = "A" (colour: red)
+	 *     - East  = "B" (colour: blue)
+	 *     Digital "START" (shape: up-pointing equilateral trangle)
+	 *       button at lower centre thumb position
+	 * 
+	 * Other features:
+	 * - 2 expansion sockets
+	 */
+	LIBGAMEPAD_CONTROLLER_DREAMCAST,
+
+	/**
+	 * DualShock Analog Controller
+	 * 
+	 * Released 1997-11-20 for PlayStation
+	 * 
+	 * TODO Document DualShock Analog Controller
+	 */
+	LIBGAMEPAD_CONTROLLER_DUAL_SHOCK,
+
+	/**
+	 * Dual Analog Controller
+	 * 
+	 * Released 1997-04-25 for PlayStation
+	 * 
+	 * TODO Document Dual Analog Controller
+	 */
+	LIBGAMEPAD_CONTROLLER_DUAL_ANALOG,
+
+	/**
+	 * 3D Pad
+	 * 
+	 * Released 1996-07-05 for Sega Saturn
+	 * 
+	 * TODO Document 3D Pad
+	 */
+	LIBGAMEPAD_CONTROLLER_3D_PAD,
+
+	/**
+	 * Nintendo 64 controller
+	 * 
+	 * Released 1996-06-23 for Nintendo 64
+	 * 
+	 * Layout:
+	 *     M-shaped, allowing it to be hold one-handed as
+	 *       a gun or two-handed as a regular game controller
+	 *     Digital D-pad at left thumb position
+	 *     Analogue stick at middle thumb position
+	 *     4 directional "C" (colour: yellow) buttons at right thumb position
+	 *     Digital "L" button at left index finger position
+	 *     Digital "Z" button at middle index finger position
+	 *     Digital "R" button at right index finger position
+	 *     Digital "START" (colour: red) button north of middle thumb position
+	 *     2 digital buttons south east of right thumb position
+	 *     - North = "B" (colour: green)
+	 *     - West  = "A" (colour: blue)
+	 * 
+	 * Other features:
+	 * - Expension slot
+	 */
+	LIBGAMEPAD_CONTROLLER_NINTENDO_64,
+
+	/**
+	 * Virtual Boy controller
+	 *
+	 * Released 1995-07-21 for Virtual Boy
+	 *
+	 * Layout:
+	 *     Digital D-pad at outer left thumb position
+	 *     Digital D-pad at outer right thumb position
+	 *     Digital "SELECT" button at middle left thumb position
+	 *     Digital "A" button at middle right thumb position
+	 *     Digital "START" button at inner left thumb position
+	 *     Digital "B" button at inner right thumb position
+	 *     Digital button at rear left index finger position
+	 *     Digital button at rear right index finger position
+	 */
+	LIBGAMEPAD_CONTROLLER_VIRTUAL_BOY,
+
+	/**
+	 * PlayStation Controller
+	 * 
+	 * Released 1994-12-03 for PlayStation
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     4 digital buttons at right thumb position:
+	 *     - North = Triangle (colour: green)
+	 *     - West  = Square (colour: pink)
+	 *     - South = Cross (colour: blue)
+	 *     - East  = Circle (colour: red)
+	 *     Digital button "L1" at upper left index finger position
+	 *     Digital button "R1" at upper right index finger position
+	 *     Digital button "L2" at lower left index finger position
+	 *     Digital button "R2" at lower right index finger position
+	 *     2 digital buttons at centre position:
+	 *     - West = "SELECT" (shape: flat rectangle)
+	 *     - East = "START"  (shape: flat play icon)
+	 */
+	LIBGAMEPAD_CONTROLLER_PLAY_STATION,
+
+	/**
+	 * Sega Saturn controller
+	 * 
+	 * Released 1994-11-22 for Sega Saturn
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     6 digital buttons at right thumb position:
+	 *     - Lower left   = "A"
+	 *     - Lower middle = "B"
+	 *     - Lower right  = "C"
+	 *     - Upper left   = "X"
+	 *     - Upper middle = "Y"
+	 *     - Upper right  = "Z"
+	 *     Digital button left index finger position
+	 *     Digital button right index finger position
+	 *     Digital "START" (shape: horizontal line) button at centre position
+	 */
+	LIBGAMEPAD_CONTROLLER_SEGA_SATURN,
+
+	/**
+	 * 6-Button Arcade Pad
+	 * 
+	 * Released 1993-??-?? for Sega Mega Drive
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     6 digital buttons at right thumb position:
+	 *     - Lower left   = "A"
+	 *     - Lower middle = "B"
+	 *     - Lower right  = "C"
+	 *     - Upper left   = "X"
+	 *     - Upper middle = "Y"
+	 *     - Upper right  = "Z"
+	 *     Digital "MODE" button right index finger position
+	 *     Digital "START" (shape: horizontal line) button at centre position
+	 * 
+	 * Conforming platforms:
+	 * - Sega Nomad (however "MODE" is east of "START" which is far south east of "A")
+	 */
+	LIBGAMEPAD_CONTROLLER_6_BUTTON_ARCADE_PAD,
+
+	/**
+	 * Gravis PC GamePad
+	 * 
+	 * Released 1992-??-?? for PC
+	 *
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     4 digital buttons at right thumb position
+	 *     - North = blue
+	 *     - East  = red
+	 *     - South = yellow
+	 *     - West  = green
+	 * 
+	 * Other features:
+	 * - Has a switch for rotating the layout 180 degrees
+	 * - Has a switch for turning two buttons into autofire versions of the other two
+	 */
+	LIBGAMEPAD_CONTROLLER_GRAVIS_PC,
+
+	/**
+	 * SNES controller
+	 * 
+	 * Released 1990-11-21 for SNES (Super Nintendo Entertainment System)
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     4 digital buttons at right thumb position:
+	 *     - North = "X" (colour: blue)
+	 *     - East  = "Y" (colour: green)
+	 *     - South = "B" (colour: yellow)
+	 *     - West  = "A" (colour: red)
+	 *     Digital "L" button at left index finger position
+	 *     Digital "R" button at right index finger position
+	 *     2 digital (/ shaped) buttons at centre thumb position:
+	 *     - East = "SELECT"
+	 *     - West = "START"
+	 *
+	 * The buttons are uncoloured on some versions
+	 */
+	LIBGAMEPAD_CONTROLLER_SNES,
+
+	/**
+	 * Sega Mega Drive controller
+	 * 
+	 * Released 1988-10-29 for Sega Mega Drive
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     3 digital buttons at right thumb position:
+	 *     - Left   = "A"
+	 *     - Middle = "B"
+	 *     - Right  = "C"
+	 *     Digital "START" (shape: horizontal line) above "B"
+	 */
+	LIBGAMEPAD_CONTROLLER_SEGA_MEGA_DRIVE,
+
+	/**
+	 * Master System controller
+	 * 
+	 * Released 1986-09-?? for Master System
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     2 digital buttons at right thumb position:
+	 *     - East  = "1 START"
+	 *     - West  = "2"
+	 */
+	LIBGAMEPAD_CONTROLLER_MASTER_SYSTEM,
+
+	/**
+	 * NES controller
+	 * 
+	 * Released 1983-07-15 for NES (Nintendo Entertainment System)
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     2 digital buttons at right thumb position:
+	 *     - East  = "B"
+	 *     - West  = "A"
+	 *     2 digital buttons (shape: horizontal line) at centre thumb position:
+	 *     - East  = "SELECT"
+	 *     - West  = "START"
+	 * 
+	 * Conforming platforms:
+	 * - Nintendo Game Boy
+	 * - Supervision (however "START" is also labelled "PAUSE" and the "SELECT" and "START"
+	 *                buttons are horizontal and north (slightly east) for "A" and "B" which
+	 *                are with a / slant)
+	 * - Mega Duck (however "SELECT" and "START" are south of "A" and "B")
+	 */
+	LIBGAMEPAD_CONTROLLER_NES,
+
+	/**
+	 * Steam Deck
+	 * 
+	 * Handheld gaming PC released 2022-02-25
+	 * 
+	 * Layout:
+	 *     Digital D-pad at outer left thumb position
+	 *     Analogue stick with capacitive touch at natural left thumb position
+	 *     Analogue stick with capacitive touch at natural right thumb position
+	 *     4 digital buttons at outer right thumb position:
+	 *     - North = "Y"
+	 *     - East  = "X"
+	 *     - South = "A"
+	 *     - West  = "B"
+	 *     Multi-touch trackpad at lower left thumb position
+	 *     Multi-touch trackpad at lower right thumb position
+	 *     Digital "L1" button at upper left index finger position
+	 *     Digital "R1" button at upper right index finger position
+	 *     Analogue "L2" button at lower left index finger position
+	 *     Analogue "R2" button at lower right index finger position
+	 *     Digital "L4" button at left long finger position
+	 *     Digital "R4" button at right long finger position
+	 *     Digital "L5" button at left ring finger position
+	 *     Digital "R5" button at right ring finger position
+	 *     Digital "STEAM" button beneath lower left thumb position
+	 *     Digital Quick Access (icon: three horizontally stacked dots)
+	 *       button beneath lower right thumb position
+	 *     Digital View (icon: two z-stacked windows) button
+	 *       north west of natural left thumb position
+	 *     Digital Menu (icon: three vertically stacked horizontal lines)
+	 *       button north east of natural right thumb position
+	 *     2 digital buttons inward from upper left index finger position:
+	 *     - Outer = Volume "−"
+	 *     - Inner = Volume "+"
+	 * 
+	 * Other features:
+	 * - 3 axis accelerometer
+	 * - 3 axis gyroscope
+	 * - Ambient light sensor
+	 */
+	LIBGAMEPAD_CONTROLLER_STEAM_DECK,
+
+	/**
+	 * Game Boy Advanced
+	 *
+	 * Handheld gaming console released 2001-03-21
+	 *
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     2 digital buttons at south south west of D-pad
+	 *     - North = "START"
+	 *     - South = "SELECT"
+	 *     2 digital buttons at right thumb position:
+	 *     - East = "B"
+	 *     - West = "A"
+	 *     Digital "L" button at left index finger position
+	 *     Digital "R" button at right index finger position
+	 *
+	 * Conforming platforms:
+	 * - Game King (however "SELECT" and "START" are north of D-pad,
+	 *              "SELECT" to east and "START to west)
+	 */
+	LIBGAMEPAD_CONTROLLER_GAME_BOY_ADVANCED,
+
+	/**
+	 * Game Gear
+	 * 
+	 * Handheld gaming console released 1990-10-06
+	 * 
+	 * Layout:
+	 *     Digital D-pad at left thumb position
+	 *     2 digital buttons at right thumb position:
+	 *     - East  = "1"
+	 *     - North = "2"
+	 *     Digital "START" (colour: blue, shape: corda-cut circle)
+	 *       button noroth of right thumb position
+	 */
+	LIBGAMEPAD_CONTROLLER_GAME_GEAR
+};
+
+
+/**
+ * Joystick profiles
+ * 
+ * This list only contains well-known profiles, mainly
+ * the primary controllers from video gaming consoles
+ */
+enum libgamepad_joystick {
+	/**
+	 * Unknown joystick profile
+	 */
+	LIBGAMEPAD_JOYSTICK_UNKNOWN,
+
+	/**
+	 * Unlisted joystick profile
+	 */
+	LIBGAMEPAD_JOYSTICK_OTHER,
+
+	/**
+	 * Atari CX40 joystick
+	 *
+	 * Released 1978 for Atari 2600
+	 *
+	 * Layout:
+	 *     8-directional digital joystick in centre
+	 *     Digital button at north east
+	 */
+	LIBGAMEPAD_JOYSTICK_ATARI_CX40
+};
+
+
+/**
  * Device type
  *
  * A device can have any number of these applied to