DOCSEARCHbyAlgolia
Submit Docs

xpadneo Documentation

repository·master·Indexed 25 days ago

https://github.com/atar-axis/xpadneo

A Linux kernel driver for Xbox controllers providing improved Bluetooth connectivity, rumble support, and advanced feature handling. Documentation includes guides for runtime and permanent configuration via sysfs and modprobe, Bluetooth dongle troubleshooting for various chipsets (CSR, Qualcomm, Realtek), debugging techniques using dmesg, btmon, and evtest, and detailed HID report descriptors for Xbox One S, Xbox Elite 2, and compatible controllers like 8BitDo and GameSir.

Tokens
16.3K
Snippets
28
Records
60
Agent score
83%

What's inside xpadneo

  1. Update controller firmware using a Windows VM on Linux

    master

    If you do not have a native Windows installation, you can update firmware using a Windows Virtual Machine (e.g., VirtualBox).

    Critical Note on 'Bricking': During flashing, the controller enters a bootloader mode where its USB Product ID (PID) changes. If your VM is not configured to handle this PID change via specific USB filters, the update may fail. This is usually a temporary 'soft-brick' that can be recovered by unplugging the USB cable and removing the batteries.

    Recommended Hardware: Using an Xbox Wireless USB Dongle is the most reliable method for VM users because the dongle does not change its USB PID during updates, making USB passthrough much more stable.

  2. Fix SDL button mapping issues

    master

    To prevent SDL, Wine, or the HTML5 game controller API from applying incorrect button mappings to your controller, you can manually override the default behavior using the SDL_GAMECONTROLLERCONFIG environment variable. This is necessary because certain layers (like libSDL2 or Wine) may attempt to 'fix' mappings that are already correct via xpadneo.

    To apply this globally, add the export command to your logon scripts. Ensure you set the variable before starting the software.

  4. Install xpadneo package files and DKMS sources

    master

    When using the Makefile, xpadneo does not automatically build the DKMS module. The behavior depends on whether a PREFIX is provided:

    Standard Installation

    To install package files to the root directory (/) and automatically run dkms add to add the source code to the DKMS tree:

    make install

    Prefixed Installation (Manual DKMS)

    If you provide a PREFIX, the Makefile will skip DKMS actions. You must add the source to DKMS manually as a separate step:

    make PREFIX=/ install
dkms add hid-xpadneo

    Distribution-specific paths

    To install configuration files to /usr/lib instead of /etc (common in many distributions):

    make ETC_PREFIX=/usr/lib install

    To combine a prefixed installation with a manual DKMS step:

    make PREFIX=/tmp/xpadneo-image ETC_PREFIX=/usr/lib install
dkms add hid-xpadneo
    # Install package files to `/` and deploy the DKMS sources
make install

# Install package files but deploy the DKMS sources as a separate step
make PREFIX=/ install
dkms add hid-xpadneo

# Install package files to `/usr/lib` instead of `/etc`
make ETC_PREFIX=/usr/lib install

# This can be combined with prefixed installation
make PREFIX=/tmp/xpadneo-image ETC_PREFIX=/usr/lib install
dkms add hid-xpadneo

  5. Generate the SDL controller ID string

    master

    The ID used in the SDL_GAMECONTROLLERCONFIG string (e.g., 050000005e040000fd02000003090000) is composed of four 32-bit words in LSB order:

    1. Bus number
    2. Vendor ID
    3. Device ID
    4. Interface version or serial (firmware dependent)

    To find these values for your specific device:

    1. Check dmesg when xpadneo detects your device to find the device path.
    2. Navigate to the corresponding directory in /sys (e.g., /sys/class/hiddev/hiddevX/id/).
    3. Read the files in that directory to extract the required components.

  6. Prepare a Windows VM for firmware flashing

    master

    To update firmware via a VM, you must first set up a Windows environment with the necessary tools.

    Requirements:

    • VirtualBox
    • Windows 10 or Windows 11 ISO
    • Xbox Accessories app (installed from the Microsoft Store)

    Setup Steps:

    1. Install VirtualBox.
    2. Create a new Windows 10 or Windows 11 VM using the downloaded ISO.
    3. Complete the Windows setup.
    4. Install all Windows Updates and Microsoft Store updates.
    5. Install the Xbox Accessories app from the Microsoft Store.
    6. Shut down the VM.

  8. Configure SDL mappings in Steam

    master

    If you prefer not to use environment variables, you can add your controller mapping directly to the Steam configuration file.

    Steps:

    1. Locate your Steam config file at $STEAM_BASE/config/config.vdf.
    2. Find the line containing "SDL_GamepadBind".
    3. Add or adjust your controller mapping string.
    4. Important: Ensure Steam is not running while editing this file.

    Note: This may not work for Steam running in Wine, as the Wine SDL layer takes precedence and may still require the SDL_GAMECONTROLLERCONFIG environment variable.

  9. Capture generated input events using evtest

    master

    To provide the events generated by xpadneo (e.g., to demonstrate incorrect stick ranges or axis behavior), use this command to find the correct input event device for an 'Xbox Wireless Controller' and pipe it into evtest. Perform the problematic actions (like moving sticks) while the command is running.

    perl -0777 -l -ne 'print "/dev/input/$1\n" if /Name="Xbox Wireless Controller".*Handlers.*(event[0-9]+)/s' /proc/bus/input/devices | xargs evtest

  10. Configure Wine games for xpadneo

    master

    To ensure proper support for xpadneo when running games in Wine:

    1. Remove any previous xinput hacks (such as redirecting xinput*.dll to native or placing custom xinput DLLs in the game directory).
    2. Ensure your Wine build has SDL support compiled in.
    3. If the Wine SDL layer is active, you may still need to export the SDL_GAMECONTROLLERCONFIG environment variable before running Wine.

  11. Prevent Linux from interfering with USB passthrough

    master

    On Linux, the legacy xpad driver may automatically load and claim the controller, which breaks USB passthrough for firmware flashing. To prevent this, you must blacklist the driver.

    Steps:

    1. Create a new file in /etc/modprobe.d/ ending in .conf (e.g., /etc/modprobe.d/xpad-blacklist.conf).
    2. Add the following line to the file:
      blacklist xpad
    3. Reboot your Linux system.

    Note: You can undo this by removing the file and rebooting to use the xpad driver again.

    blacklist xpad

  12. Configure VirtualBox USB passthrough for firmware flashing

    master

    To ensure the VM maintains connection to the controller when it switches into bootloader mode (PID change), you must configure a specific USB filter in VirtualBox.

    Steps:

    1. Plug the controller into your PC via USB.
    2. Open your VM Settings and navigate to USB.
    3. Click the “Add new USB filter from device” icon (USB icon with a plus).
    4. Select your controller (or Xbox Wireless USB Dongle) from the list.
    5. Crucial: Edit the newly created filter. Remove all fields except:
      • Port
      • Name (can be any string)

    By removing the Device ID and Product ID fields, the filter will match the device based on the physical port, allowing the connection to persist even when the controller's PID changes during the update.