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).

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

xone is a driver aiming for fully supporting all Microsoft GIP devices thus replacing the xpad driver in the kernel. It supports Xbox One and Xbox Series X|S accessories.
xow is an unmaintained driver for the Xbox One S controllers, which has been superseded by xone. Kudos to @medusalix for working together on finding some work-arounds for controller firmware bugs.
xpad supports this and many other controllers in USB mode.
MissionControl aims to support the controller on Nintendo Switch via Bluetooth.

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

Heads Up Package Maintainers

Licensing of the project has changed, so please update your packaging if you maintain a package for this driver. Please refer to LICENSE.md for details. If you have any questions, please ask.

The project introduced some packaging helpers and changed the installation process. Please see Packaging.

Version v0.11 dropped the dependency on CONFIG_INPUT_FF_MEMLESS and uses a more precise method to run rumble effects, eliminating aliasing effects due to different frequencies of games (60 fps and above) and ff-memless (20 hz). Our new method allows frequencies up to 100 hz which is the limit of the controller's hardware.

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.

Paddle Button Codes Changed

To stay compatible with SDL and current kernel development, the button codes for the grip paddles of XBE2 controllers have been moved to the official kernel standards as of kernel 6.17. We will also reflect this change for older kernel versions so user-space can rely on a consistent mapping. If you remapped those buttons with third-party software, you will need to redo those mappings.

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:

https://github.com/atar-axis/xpadneo/issues/428
https://github.com/libsdl-org/SDL/commit/9567989eb3ce9c858f0fe76806c5ccad69da89ba
https://github.com/libsdl-org/SDL/commit/0f4b15e16b7f07a46db6dc8e651f8c1849d658c5

Known issues:

The Share button will currently not be recognized by SDL2, scheduled to be fixed in xpadneo v0.11
If SDL2 uses hidraw, mappings will be wrong, export SDL_JOYSTICK_HIDAPI=0 in your profile or find which software enabled hidraw device access to all drivers

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:

All non-XBE2 controllers will claim to have a Share button no matter if it physically exists. As HID doesn't report the internal model number, xpadneo cannot fix it currently. The button is currently mapped to F12, so this has no consequences.
All XBE2 controllers will claim to have a full keyboard and the Share button is actually the Profile button. Since Share is currently mapped to F12, this will have no consequences.

Advantages of this Driver

Supports Bluetooth
Supports direct rumble effects avoiding aliasing effects by not using ff-memless (streaming mode only)
Supports Trigger Force Feedback in every game by applying a pressure-dependent effect intensity to the current rumble effect (not even supported in Windows)
Supports adjusting rumble intensity including disabling rumble
Offers a consistent mapping, even if the Gamepad was paired to Windows/Xbox before, and independent of software layers (SDL2, Stadia via Chrome Gamepad API, etc)
Working paddles (buttons on the backside of the controller)
Correct axis range (signed, important for e.g. RPCS3)
Supports battery level indication (including the Play 'n Charge Kit)
Easy installation
Exposes the currently selected profile to user-space (Xbox Elite 2 controllers, or emulated)
Supports customization through profiles (work in progress)
Supports grip paddles (as shipped with the Xbox Elite 2 controller)
Optional high-precision mode for Wine/Proton users (disables dead zones so games don't apply an additional one)
Share button support on supported controllers
Works as a mouse if you are in couch-mode (press <key>Guide</key>+<key>Select</key>)

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.

There are two modes for rumble: Streaming and non-streaming. Streaming means, a game will send one rumble command per frame. Non-streaming means, effects are sent in advance, planned into the future, and can potentially play at the same time. This is mostly useful for force feedback effects, which Xbox controllers cannot replicate, they only support haptic feedback. Thus, non-streaming rumble programming is not supported, and we found no game that uses it. We will still detect it and log that incident to dmesg once, so users can report if they found a game that uses it.

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:

Upload of profile mappings and sensitivity curves is currently not supported.

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.d/99-xpadneo-quirks.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 sup

Xpadneo

Install / Use

README