Merge pull request #969 from davidhedlund/patch-11

fpscan · web-flow · commit 7c85abca8c69 · 2024-08-04T08:05:19.000+03:00
Update controller-autoconfiguration.md: Updated the axis labels for analog L2 and R2 inputs. Replaced "controller name" with "Device Index". Described that linxraw does not provide Vendor ID (VID) and Product ID (PID) info
diff --git a/docs/guides/controller-autoconfiguration.md b/docs/guides/controller-autoconfiguration.md
@@ -1,18 +1,23 @@
 # Joypad Auto Configuration
 
-## How does matching work?
+## How does RetroArch match controllers?
 
-RetroArch is shipped with a set of configuration files for the most common joypads. When you plug a joypad for the first time, we try to find a matching profile in our set.
+When you connect a new controller to RetroArch, the system attempts to automatically configure it by matching it to known profiles. This matching process is crucial for ensuring that your controller works correctly with various games and emulators.
 
-The matching algorithm considers three criteria:
+The matching algorithm considers several key factors:
 
-   - Device name
-   - Vendor ID
-   - Product ID
+- **Controller driver (input_driver)**: The software interface used to communicate with the controller. To use a specific driver, RetroArch must be configured accordingly by navigating to **Settings -> Drivers -> Controller**.
+- **Device Index (input_device)**: The name of the controller as recognized by the system. The **Device Index** can be identified by navigating to **Settings -> Input -> RetroPad Binds -> Port 1 Controls**.
+- **Vendor ID (input_vendor_id)**: A unique identifier assigned to the controller's manufacturer.
+- **Product ID (input_product_id)**: A specific identifier for the particular controller model.
 
-We compute a matching score for each configuration file based on these three factors. The profile with the highest score is chosen to configure the pad.
+RetroArch evaluates each of these factors against its database of controller profiles. It then calculates a matching score for each profile, with the highest-scoring profile being selected to configure the controller.
 
-**Note**: The **Vendor ID** and **Product ID** pair is often abbreviated as **vid:pid**.
+RetroArch automatically utilizes the linuxraw driver, which operates differently than other drivers by providing only a device name instead of Vendor ID (VID) and Product ID (PID) information. This means that controller matching with the linuxraw driver depends primarily on the device name (Device Index), accessed through the JSIOCGNAME ioctl command, rather than the typical vid:pid identifiers.
+
+It's worth noting that the Vendor ID and Product ID pair is often abbreviated as "vid:pid" in technical discussions.
+
+This matching system allows RetroArch to support a wide range of controllers while minimizing the need for manual configuration in most cases.
 
 ## Why is it needed?
 
@@ -158,28 +163,44 @@ Here's how to set up a default-off configuration:
 
 This approach allows users to manually enable the configuration when needed, preventing automatic application that could interfere with common devices, and helps ensure a smoother experience for users while still providing the necessary configuration options for those who require them.
 
-### Controller name scheme
+### Device Index scheme for autoconfig files
+
+In RetroArch, the management of controller configurations is essential for ensuring proper functionality across various systems. This guide outlines how the Device Index are generated and how they can vary based on the Linux kernel version in GNU/Linux distributions.
+
+#### Understanding the Device Index
+
+RetroArch identifies physical controllers through a system called the Device Index. You can locate this identifier by navigating to:
+
+**Settings > Input > RetroPad Binds > Port 1 Binds > Device Index**
+
+The Device Index plays a crucial role when saving a controller profile. To save a profile, follow this path:
+
+**Settings > Input > RetroPad Binds > Port 1 Controls > Save Controller Profile**
+
 
-In RetroArch, the management of controller configurations is essential for ensuring proper functionality across various systems. This guide outlines how controller names are generated and how they can vary based on the Linux kernel version in GNU/Linux distributions.
+### Dual function of the Device Index
 
-#### Understanding controller names
+When you save a controller profile, the Device Index serves two important purposes:
 
-When you save a controller profile (**Settings > Input > RetroPad Binds > Port 1 Controls > Save Controller Profile**), RetroArch generates a controller name (e.g., "Foo"). This name serves two purposes:
+1. **Configuration File Naming**: It becomes an integral part of the configuration file's name. For example, if the Device Index is "Foo", the configuration file might be named "udev/Foo.cfg".
 
-1. It becomes part of the configuration file name (e.g., "udev/Foo.cfg").
-2. It's used as the value for the `input_device` variable within the configuration file (e.g., `input_device = "Foo"`).
+2. **Input Device Identification**: Within the configuration file itself, the Device Index is used as the value for the `input_device` variable. Following our example, you would see a line like this in the file:
+
+   `input_device = "Foo"`
+
+This dual functionality ensures that RetroArch can correctly identify and apply the appropriate settings for each unique controller.
 
 Importantly, this name remains consistent across various controller drivers, such as udev, sdl2, and linuxraw, as specified in **Settings > Drivers > Controller**.
 
-#### Variability of controller names
+#### Variability of the Device Index
 
-The controller name may change depending on the version of the system, particularly the Linux kernel version. To ensure compatibility, we utilize the most recent controller name that is supported by the system.
+The Device Index may change depending on the version of the system, particularly the Linux kernel version. To ensure compatibility, we utilize the most recent Device Index that is supported by the system.
 
 #### Example: Nintendo Switch Pro Controller on GNU/Linux
 
-The following table illustrates how the controller name for the Nintendo Switch Pro Controller varies across different Linux kernel versions, along with its HID support and corresponding autoconfig file names. As a side-note, the notation "(default-off)" indicates that the configuration is disabled by default to avoid 
+The following table illustrates how the Device Index for the Nintendo Switch Pro Controller varies across different Linux kernel versions, along with its HID support and corresponding autoconfig file names. As a side-note, the notation "(default-off)" indicates that the configuration is disabled by default to avoid 
 
-| Linux Kernel Version | Controller Name in RetroArch              | Nintendo Switch Pro Controller HID Support | Selected controller name for the autoconfiguration file                          |
+| Linux Kernel Version | Device Index in RetroArch              | Nintendo Switch Pro Controller HID Support | Selected Device Index for the autoconfiguration file                          |
 |----------------------|-------------------------------------------|-------------------------------------------|----------------------------------------------|
 | 5.15                 | Pro Controller                            | No                                        | Pro Controller             |
 | 5.19                 | Nintendo Switch Pro Controller            | Yes                                       |                                              |
@@ -190,7 +211,7 @@ The following table illustrates how the controller name for the Nintendo Switch
 
 ###### Pro Controller (default-off).cfg
 ```
-# This file uses the legacy controller name "Pro Controller" (generated by RetroArch on Linux 5.15)
+# This file uses the legacy Device Index "Pro Controller" (generated by RetroArch on Linux 5.15)
 # "(default-off)" was added to the file name to indicate that the autoconfig file is not active by default. See comments for input_vendor_id and input_product_id.
 input_device = "Pro Controller"
 # Due to the uncommon nature of this device, the autoconfig file is not active by default. This precaution is taken to avoid potential conflicts with the widely-used Nintendo Switch Pro Controller (nintendo-hid version) file. Button layouts are not compatible. To activate this configuration:
@@ -227,6 +248,7 @@ input_product_id = "3570"
 
 The second part is the mapping itself, where each button is assigned to a button of the RetroPad (the joypad abstraction of RetroArch).
 
+Example
 ```
 input_b_btn = "0"
 input_y_btn = "2"
@@ -255,26 +277,70 @@ input_r_y_minus_axis = "-4"
 input_menu_toggle_btn = "8"
 ```
 
-#### Axes (analog inputs)
+Note: These variable values are examples and should not be directly copied to your configuration file.
+
+#### Overview
+
+##### Axes (analog inputs)
+* They represent analog inputs from the controller, like joystick position (e.g., left joystick X-axis, right joystick Y-axis) or trigger pressure (e.g., L2 trigger, R2 trigger).
+* Variable names (for both mappings and labels) includes `_axis` define these (e.g., `input_l_x_plus_axis_label`, `input_r2_axis`).
+
+| Console          | Controller                       | Release Date   | Analog Thumb Sticks | L2/R2 Analog |
+|------------------|----------------------------------|----------------|---------------------|--------------|
+| PlayStation 1    | Sony Dual Analog Controller      | April 1997     | Yes                 | No           |
+| PlayStation 1    | Sony DualShock                   | November 1997  | Yes                 | No           |
+| PlayStation 2    | DualShock 2                      | 2000           | Yes                 | Yes          |
+| PlayStation 3    | Sixaxis                          | 2006           | Yes                 | Yes          |
+| PlayStation 3    | DualShock 3                      | 2008           | Yes                 | Yes          |
+| PlayStation 4    | DualShock 4                      | 2013           | Yes                 | Yes          |
+| PlayStation 5    | DualSense                        | 2020           | Yes                 | Yes          |
 
-* Variable names ending with `_axis` define these (e.g., `input_l_x_axis`, `input_r2_axis`).
-* They represent analog inputs from the controller, like joystick position (e.g., left joystick X-axis, right joystick Y-axis) or trigger pressure (e.g., left trigger, right trigger).
+###### Mapping variables
 * Axis definitions use `+` and `-` to indicate positive or negative direction (e.g., full press vs. no press).
 * The current RetroArch configurations have axis values that ranges from `0` to `10`. However, if RetroArch does not limit the values to `10`, underlying controller hardware could offer an even wider range.
 
-#### Buttons (digital inputs)
+Mapping variables with analog L2/R2 triggers:
+```
+input_l2_axis = "+2"
+input_r2_axis = "+5"
+```
+
+Note: These variable values are examples and should not be directly copied to your configuration file.
+
+###### Label variables
+The term "Analog" is included in the variable values for the analog inputs to clearly indicate that these inputs are analog in nature.
+
+Labels for analog thumb sticks:
+```
+input_l_x_plus_axis_label = "Left Analog X+ (right)"
+input_l_x_minus_axis_label = "Left Analog X- (left)"
+input_l_y_plus_axis_label = "Left Analog Y+ (down)"
+input_l_y_minus_axis_label = "Left Analog Y- (up)"
+input_r_x_plus_axis_label = "Right Analog X+ (right)"
+input_r_x_minus_axis_label = "Right Analog X- (left)"
+input_r_y_plus_axis_label = "Right Analog Y+ (down)"
+input_r_y_minus_axis_label = "Right Analog Y- (up)"
+```
+
+Labels for analog L2/R2 triggers:
+```
+input_l2_axis_label = "L2 Analog"
+input_r2_axis_label = "R2 Analog"
+```
+
+##### Buttons (digital inputs)
 
 * These are defined by variable names ending with `_btn` (e.g., `input_a_btn`, `input_start_btn`).
 * The current RetroArch configurations have button values that ranges from `0` to `203`. However, if RetroArch does not limit the values to `203`, underlying controller hardware could offer an even wider range.
 * RetroArch interprets these IDs (usually 1 for pressed, 0 for not pressed) to determine the button state.
 
-##### D-Pad directions (special digital inputs)
+###### D-Pad directions (special digital inputs)
 
 * D-pad directions use variable values beginning with `h0` (e.g., `input_up_btn = "h0up"`).
 * Four `h0` variables exist (`h0up`, `h0down`, `h0left`, `h0right`) for each direction on the D-pad.
 * Note: The value `h1` is used by a single controller (Nintendo_Wii_Remote_Classic_Controller.cfg).
 
-### Input descriptors
+#### Input descriptors
 
 The third part are *input descriptors* used by RetroArch to display the labels of the buttons as they are written on your joypad.
 
@@ -307,9 +373,9 @@ input_r_y_minus_axis_label = "Right Analog Y- (up)"
 input_menu_toggle_btn_label = "Guide"
 ```
 
-#### Sony PlayStation controllers
+#### Example: Controllers for Sony PlayStation 2 and later
 
-So if you are using a Sony PlayStation controllers, RetroArch will refer to the buttons as Cross, Circle, Square and Triangle:
+Labels for PlayStation controllers starting from PS2. Note that analog L2/R2 triggers (`input_l2_axis_label = "L2 Analog"`, and `input_r2_axis_label = "R2 Analog"`) are featured:
 ```
 input_b_btn_label = "Cross"
 input_y_btn_label = "Square"
@@ -323,8 +389,8 @@ input_a_btn_label = "Circle"
 input_x_btn_label = "Triangle"
 input_l_btn_label = "L1"
 input_r_btn_label = "R1"
-input_l2_axis_label = "L2"
-input_r2_axis_label = "R2"
+input_l2_axis_label = "L2 Analog"
+input_r2_axis_label = "R2 Analog"
 input_l3_btn_label = "L3"
 input_r3_btn_label = "R3"
 input_l_x_plus_axis_label = "Left Analog X+ (right)"
