search

atar-axis / xpadneo

Advanced Linux Driver for Xbox One Wireless Controller (shipped with Xbox One S)
https://atar-axis.github.io/xpadneo/
GNU General Public License v3.0
2.03k stars 115 forks source link
dkms dkms-packages gamepad hid linux-driver linux-drivers xbox xbox-controller xbox-one xpad xpadneo

readme

ko-fi

If you want to support me or accelerate the development of a special feature, consider a small donation :heart: Just leave a message if your donation is for a specific use (like a new hardware or a specific function).

Build Status Average time to resolve an issue Packaging status Discord

Advanced Linux Driver for Xbox One Wireless Gamepad

xpadneo Logo

Quote from @atar-axis (Florian Dollinger), creator of the initial driver:

This is the first driver for the Xbox One Wireless Gamepad (which is shipped with the Xbox One S). I wrote it for a student project at fortiss GmbH and it is fully functional but does only support the connection via Bluetooth as yet - more will follow.

Many thanks to Kai Krakow who sponsored me a Xbox One Wireless Controller :video_game: (including Wireless Adapter) and a pack of mouthwatering guarana cacao :coffee:

Other Projects

These other projects may not support some of the advanced features of xpadneo.

Breaking Changes

Kernel 4.18 or newer required

As of xpadneo v0.10, we require kernel 4.18 or later to utilize HID_QUIRK_INPUT_PER_APP which splits the gamepad into multiple sub-devices to fix problems and incompatibilities at several layers.

SDL2 2.28 Compatibility

Thanks to @slouken from SDL2, xpadneo mappings are now auto-detected in the upcoming SDL2 2.28 release. This will fix long-standing problems with Steam Input and SDL2 games. With this release, we will also have full paddle support.

If you still see problems, ensure that you didn't create custom controllerdb entries. See also:

Known issues:

Quirks by Design

With BLE firmware, all models switched to a unified HID report descriptor, only the XBE2 controller identifies with PID 0x0B22 while the other models identify with PID 0x0B13. This has some known consequences:

Advantages of this Driver

Unavailable Features

Across all models, xpadneo won't support audio features of the controllers because the firmware doesn't support audio in Bluetooth mode. In the future, xpadneo may support audio when USB and dongle support will be added.

Xbox One S Wireless Controller

This is the initial controller supported from the first version of xpadneo. All features are fully supported. This controller uses emulated profile switching support (see below).

Xbox Elite Series 2 Wireless Controller

Basic support for the Xbox Elite Series 2 Wireless controller is present, covering all the features of the driver. The following features are missing:

This controller uses native profile switching support (see below).

Xbox Series X|S Wireless Controller

Full support for the Xbox Series X|S controller is present including the share button. This is currently statically mapped to keyboard event KEY_F12 to take screenshots with Steam. It will be configurable in the future. This controller uses emulated profile switching support (see below).

This controller uses BLE (Bluetooth low energy) and can only be supported if your Bluetooth dongle also supports BLE.

Known problems: The controller may not properly set its connection parameters, resulting in laggy and choppy input experience. See also: Troubleshooting.

8BitDo Controllers

This driver supports the Nintendo layout of those controllers to exposes them correctly as button A, B, X, and Y as labelled on the device. This is swapped compared to the original Xbox controller layout. However, this feature is not enabled by default. If you want to use this feature, you have to add a quirk flag to the module options:

# /etc/modprobe.conf
options hid_xpadneo quirks=E4:17:D8:xx:xx:xx+32

where you replace xx:xx:xx with the values from your controller MAC (as shown in dmesg). The value 32 enables Nintendo layout. If you'll want to add other quirk flags, simply add the values, e.g. 32 + 7 (default quirks for 8BitDo) = 39. After changing this, reload the driver or reboot.

This controller uses emulated profile switching support (see below).

Breaking change: Users of previous versions of the driver may want to remove their custom SDL mappings. Full support has been added for these controllers and broken mapping of previously versions no longer needs to be applied. See also: SDL.

GuliKit KingKong Controller Family

This driver supports the GuliKit King Kong controller family, the driver was tested with model NS09 (using firmware v2.0) and NS39 (aka KK3 MAX, firmware v3.6) but should work just fine for the older models, too. If in doubt, follow the firmware upgrade guides on the GuliKit home page to receive the latest firmware. Both the Android mode and the X-Input mode are supported but it may depend on your Bluetooth stack which mode works better for you (Android mode didn't pair for me).

This driver supports the Nintendo layout of those controllers to exposes them correctly as button A, B, X, and Y as labelled on the device. This is swapped compared to the original Xbox controller layout. However, this feature is not enabled by default. If you want to use this feature, you have to add a quirk flag to the module options:

# /etc/modprobe.conf
options hid_xpadneo quirks=98:B6:EA:xx:xx:xx+32

where you replace xx:xx:xx with the values from your controller MAC (as shown in dmesg). The value 32 enables Nintendo layout. If you'll want to add other quirk flags, simply add the values, e.g. 32 + 131 (default quirks for GuliKit) = 163. After changing this, reload the driver or reboot.

However, alternatively the controller supports swapping the buttons on the fly, too: Just press and hold the settings button, the click the plus button. Thus, the quirks flag is just a matter of setting the defaults.

This controller uses emulated profile switching support (see below).

GameSir T4 Cyclone Family

This driver supports the GameSir T4 Cyclone controller family, tested by the community. The Pro-models also support trigger rumble but since we cannot distinguish both models by the Bluetooth MAC OUI, we simply enable the trigger rumble protocol for both variants. This should not introduce any problems but if it does, and your model does not have trigger rumble support, you can explicitly tell the driver to not use the trigger rumble motors by adding a quirk flag:

# /etc/modprobe.conf
options hid_xpadneo quirks=A0:5A:5D:xx:xx:xx+2

This controller uses emulated profile switching support (see below).

Profile Switching

The driver supports switching between different profiles, either through emulation or by using the hardware switch that comes with some models. This switching can be done at any time even while in a game. The API for customizing each profile does not exist yet.

Native Profile Switching Support

The driver support native profile switching for the Xbox Elite Series 2 controller. However, the feature is not finalized yet:

Emulated Profile Switching Support

The driver emulates profile switching for controllers without a hardware profile switch by pressing buttons A, B, X, or Y while holding down the Xbox logo button. However, the following caveats apply:

Important: Emulated profile switching won't work if you disabled the shift-mode of the Xbox logo button (module parameter disable_shift_mode).

Getting Started

Distribution Packages

If your distribution has a maintained package, you can just use that and do not need to follow the manual install instructions below:

Packaging status

Notes for Package Maintainers

To properly support module signing and UEFI secure boot, openssl and mokutil are required additionally to the prerequisites below. The DKMS readme has more instructions.

Prerequisites

Make sure you have installed dkms, linux headers and a bluetooth implementation (e.g. bluez) and their dependencies.

Kernel maintainers should also include the uhid module (CONFIG_UHID) because otherwise Bluetooth LE devices (all models with firmware 5.x or higher) cannot create the HID input device which is handled in user-space by the bluez daemon.

Please feel free to add other distributions as well!

Installation

Connection

You know that everything works fine when you feel the gamepad rumble ;)

Configuration

Update

In order to update xpadneo, do the following

Uninstallation

Further Information

For further information please visit the GitHub Page https://atar-axis.github.io/xpadneo/ which is generated automatically from the content of the /docs folder.

You will find there e.g. the following sections