From 3bd8e13800f90fad2539e48b9eb1e79e02c22271 Mon Sep 17 00:00:00 2001 From: David Hedlund Date: Wed, 31 Jul 2024 04:08:48 +0200 Subject: [PATCH 1/4] docs/controller-autoconfiguration.md: Added a new "Controller name scheme" section Added a new "Controller name scheme" section --- docs/guides/controller-autoconfiguration.md | 48 ++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/docs/guides/controller-autoconfiguration.md b/docs/guides/controller-autoconfiguration.md index 20fc04d5d8..d78cddcfb6 100644 --- a/docs/guides/controller-autoconfiguration.md +++ b/docs/guides/controller-autoconfiguration.md @@ -157,7 +157,53 @@ Here's how to set up a default-off configuration: 3. Do not add "(default-off)" to the values of the input_device_display_name and input_driver variables in the config file. The default-off status is already indicated by the filename, so these variables should remain unmodified for clarity. 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 + +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. + +#### Understanding controller names + +When you configure a controller in RetroArch, you can save its profile through the following path: +**Settings > Input > RetroPad Binds > Port 1 Controls > Save Controller Profile**. +This action generates a configuration file (e.g., "udev/Foo.cfg") that includes an `input_device` entry reflecting the controller's name (e.g., `input_device = Foo`). Notably, this name remains consistent across different controller drivers, including udev, sdl2, and linuxraw, as defined in **Settings > Drivers > Controller**. + +#### Variability of controller names + +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. + +#### 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 + +| Linux Kernel Version | Controller Name in RetroArch | Nintendo Switch Pro Controller HID Support | Controller name | +|----------------------|-------------------------------------------|-------------------------------------------|----------------------------------------------| +| 5.15 | Pro Controller | No | Pro Controller | +| 5.19 | Nintendo Switch Pro Controller | Yes | | +| 6.2.0 | Nintendo Switch Pro Controller | Yes | | +| 6.8.0 | Nintendo Co., Ltd. Pro Controller | Yes | Nintendo Co.,Ltd. Pro Controller | + +##### Configuration file examples + +###### Pro Controller (default-off).cfg +``` +# This file uses "Pro Controller" as the legacy controller name (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: +# 1) Comment out the input_vendor_id and input_product_id lines in the "Nintendo Co.,Ltd. Pro Controller.cfg" file. +# 2) Uncomment the input_vendor_id and input_product_id lines below: +# input_vendor_id = "1406" +# input_product_id = "8201" +``` + +###### Nintendo Co.,Ltd. Pro Controller.cfg +``` +input_device = "Nintendo Co.,Ltd. Pro Controller" +input_vendor_id = "1406" +input_product_id = "8201" +``` + ## Troubleshooting If your joypad is not configured properly, you should [generate a RetroArch log](/docs/guides/generating-retroarch-logs.md). Your log will show if a profile has been matched for your pad and the path of the corresponding profile. From 4f8aa72b3b06937f70399430fd8e9b974c25c875 Mon Sep 17 00:00:00 2001 From: David Hedlund Date: Wed, 31 Jul 2024 04:23:23 +0200 Subject: [PATCH 2/4] Update controller-autoconfiguration.md minor --- docs/guides/controller-autoconfiguration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/controller-autoconfiguration.md b/docs/guides/controller-autoconfiguration.md index d78cddcfb6..c4249f617e 100644 --- a/docs/guides/controller-autoconfiguration.md +++ b/docs/guides/controller-autoconfiguration.md @@ -187,7 +187,7 @@ The following table illustrates how the controller name for the Nintendo Switch ###### Pro Controller (default-off).cfg ``` -# This file uses "Pro Controller" as the legacy controller name (generated by RetroArch on Linux 5.15) +# This file uses the legacy controller name "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: From c739e65ff3cf7f6e8736426e647e36cef1fa54d6 Mon Sep 17 00:00:00 2001 From: David Hedlund Date: Wed, 31 Jul 2024 04:39:00 +0200 Subject: [PATCH 3/4] Update controller-autoconfiguration.md improved "Understanding controller names" --- docs/guides/controller-autoconfiguration.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/guides/controller-autoconfiguration.md b/docs/guides/controller-autoconfiguration.md index c4249f617e..2ee6f24502 100644 --- a/docs/guides/controller-autoconfiguration.md +++ b/docs/guides/controller-autoconfiguration.md @@ -164,9 +164,12 @@ In RetroArch, the management of controller configurations is essential for ensur #### Understanding controller names -When you configure a controller in RetroArch, you can save its profile through the following path: -**Settings > Input > RetroPad Binds > Port 1 Controls > Save Controller Profile**. -This action generates a configuration file (e.g., "udev/Foo.cfg") that includes an `input_device` entry reflecting the controller's name (e.g., `input_device = Foo`). Notably, this name remains consistent across different controller drivers, including udev, sdl2, and linuxraw, as defined in **Settings > Drivers > Controller**. +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. 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"`). + +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 From 6feb689a2a770c8892bbb6ae28316d9cc55ce7d7 Mon Sep 17 00:00:00 2001 From: David Hedlund Date: Thu, 1 Aug 2024 21:56:39 +0200 Subject: [PATCH 4/4] Update controller-autoconfiguration.md Added a new "#### Sony PlayStation controllers" section with a mapping template. --- docs/guides/controller-autoconfiguration.md | 36 +++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/guides/controller-autoconfiguration.md b/docs/guides/controller-autoconfiguration.md index 2ee6f24502..a72967a65c 100644 --- a/docs/guides/controller-autoconfiguration.md +++ b/docs/guides/controller-autoconfiguration.md @@ -179,7 +179,7 @@ The controller name may change depending on the version of the system, particula 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 -| Linux Kernel Version | Controller Name in RetroArch | Nintendo Switch Pro Controller HID Support | Controller name | +| Linux Kernel Version | Controller Name in RetroArch | Nintendo Switch Pro Controller HID Support | Selected controller name for the autoconfiguration file | |----------------------|-------------------------------------------|-------------------------------------------|----------------------------------------------| | 5.15 | Pro Controller | No | Pro Controller | | 5.19 | Nintendo Switch Pro Controller | Yes | | @@ -276,8 +276,9 @@ input_menu_toggle_btn = "8" ### 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. So if you are using a DualShock pad, RetroArch will refer to the buttons as Cross, Circle, Square and Triangle. +The third part are *input descriptors* used by RetroArch to display the labels of the buttons as they are written on your joypad. +Generic input descriptors: ``` input_b_btn_label = "A" input_y_btn_label = "X" @@ -305,3 +306,34 @@ input_r_y_plus_axis_label = "Right Analog Y+ (down)" input_r_y_minus_axis_label = "Right Analog Y- (up)" input_menu_toggle_btn_label = "Guide" ``` + +#### Sony PlayStation controllers + +So if you are using a Sony PlayStation controllers, RetroArch will refer to the buttons as Cross, Circle, Square and Triangle: +``` +input_b_btn_label = "Cross" +input_y_btn_label = "Square" +input_select_btn_label = "Create" +input_start_btn_label = "Options" +input_up_btn_label = "D-Pad Up" +input_down_btn_label = "D-Pad Down" +input_left_btn_label = "D-Pad Left" +input_right_btn_label = "D-Pad Right" +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_l3_btn_label = "L3" +input_r3_btn_label = "R3" +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)" +input_menu_toggle_btn_label = "PS" +```