xpadneo: Bluetooth Xbox One controller support on Linux, and when xone is the better pick

What xpadneo fixes for Xbox One controllers on Linux

The controller shipped with the Xbox One S speaks Bluetooth, but the in-kernel xpad driver the README points to only handles USB mode. xpadneo exists to close that gap: it is an out-of-tree HID driver that the project describes as the first driver for the Xbox One Wireless Gamepad, written by Florian Dollinger for a student project. The audience is narrow and specific. You have an Xbox One S controller, or an Xbox Elite 2 with its grip paddles, you connect it over Bluetooth, and you want the hardware features the stock path does not expose.

The feature list is where the driver earns its place. Trigger force feedback is applied as a pressure-dependent effect intensity on top of the current rumble effect, which the README notes is not even supported on Windows. Rumble intensity can be adjusted or disabled outright. Axis ranges are signed, which the README calls out as important for RPCS3. Battery level is reported, including for the Play 'n Charge Kit. Button mapping stays consistent even if the controller was previously paired to a Windows or Xbox machine, and independent of SDL2 or the Chrome Gamepad API. The Share button works on supported controllers, the currently selected profile is exposed to user-space on Elite 2 hardware, and there is a couch-mode trick where Guide plus Select makes the controller act as a mouse.

None of that is free. The driver is a kernel module, so every kernel upgrade is a rebuild, and the feature set stops at the Bluetooth boundary.

How the driver splits the gamepad and why ff-memless was dropped

Since v0.10 the driver requires kernel 4.18 or later because it uses HID_QUIRK_INPUT_PER_APP. That quirk splits one physical gamepad into multiple sub-devices instead of a single input node, which the README says fixes problems and incompatibilities at several layers. It is the reason the kernel floor exists, and it is the kind of design decision that shows up later: software that expects one device node per controller may need to look at several.

The rumble path changed in v0.11. Earlier versions depended on CONFIG_INPUT_FF_MEMLESS, which runs at roughly 20 Hz. Games that render at 60 fps or higher therefore produced aliasing between the game's effect frequency and the kernel's update rate. The new method runs effects directly and supports frequencies up to 100 Hz, which the README describes as the controller hardware's limit. The trade-off is that this direct path applies to streaming mode only; the README does not claim the same behaviour for every rumble mode.

There are also quirks the project accepts rather than solves. With BLE firmware, all models share a unified HID report descriptor. Only the XBE2 identifies as PID 0x0B22; other models identify as PID 0x0B13. Because HID does not report the internal model number, every non-XBE2 controller claims a Share button whether or not one exists, and every XBE2 claims a full keyboard with the Share button standing in for the Profile button. Share is mapped to F12, so the README says there are no consequences, but it is a real limitation of the protocol rather than a bug waiting to be fixed.

Installing xpadneo with DKMS and pairing a controller

The repository ships install.sh, uninstall.sh and update.sh at the top level, plus a Makefile whose install target prepares the package for DKMS deployment. The README's own advantage list calls installation easy, and the Makefile is explicit that DKMS and udevadm commands are only run when PREFIX is empty. Set PREFIX and the build warns that you must handle dkms commands in your package script yourself.

The conventional path is to clone the repository and run the installer, which needs root for the DKMS module and the udev rules:

git clone https://github.com/atar-axis/xpadneo.git
cd xpadneo
sudo ./install.sh

The Makefile install target also copies the documentation and DKMS source, and an install-all target adds the optional AppStream metainfo. If you prefer the Makefile directly, the same work is available as targets:

make build
sudo make install

After install, the driver loads as a kernel module. The udev rules in the repository are 60-xpadneo.rules and 70-xpadneo-disable-hidraw.rules, and the second one matters: it keeps SDL2 from grabbing the hidraw device, because the README states that if SDL2 uses hidraw the mappings will be wrong. If a game still misreads buttons, the documented workaround is an environment variable rather than a driver change:

export SDL_JOYSTICK_HIDAPI=0

Pairing itself is a Bluetooth operation, not an xpadneo one: put the controller into pairing mode and connect it through your desktop's Bluetooth settings. The README covers the pairing-mode question in its FAQ rather than in the install steps.

Where xpadneo stops: USB, dongles and audio

The clearest limitation is stated in the project's own words: the driver supports the connection via Bluetooth only. If you use the Xbox Wireless Adapter dongle, or you want the controller over a USB cable, xpadneo is not the tool. The README says future versions may add USB and dongle support, which is a statement of intent, not a current capability.

Audio is the second hard stop. Across all models, xpadneo will not support the controllers' audio features, because the README states the firmware does not support audio in Bluetooth mode. If you need the headset jack on the controller to carry game audio, no amount of configuration will get you there with this driver.

Platform coverage is the third. The README positions xpadneo against xone, which aims to support all Microsoft GIP devices and to replace xpad in the kernel, covering Xbox One and Xbox Series X|S accessories. Nothing in the README claims Series X|S support for xpadneo. There is also a mapping hazard that is easy to misdiagnose: if you previously created custom controllerdb entries for SDL2, the README warns that auto-detection in SDL2 2.28 will not behave as expected, and points at issue 428. The Share button is another known gap, listed as not recognized by SDL2 and scheduled for xpadneo v0.11. And a note for anyone who remapped the grip paddles on an Elite 2: the button codes moved to the official kernel standards as of kernel 6.17, so third-party remappings have to be redone.

xpadneo vs xone and xpad: three different scopes

The README names its alternatives directly, and the difference is scope rather than quality. xpad, which the README links to, supports the Xbox One controller and many others in USB mode. That makes it the right answer when your controller is plugged in, and the wrong answer for the Bluetooth case xpadneo was written for.

xone is the broader project. It aims for full support of all Microsoft GIP devices and to replace the xpad driver in the kernel, covering both Xbox One and Xbox Series X|S accessories. If you own a Series X|S controller, or you want one driver for a mixed collection of Microsoft devices, xone's stated goal covers ground xpadneo does not claim. The README's own caveat cuts the other way too: these other projects may not support some of the advanced features of xpadneo, which is where trigger force feedback, signed axis ranges and profile exposure live.

xow, which the README describes as unmaintained and superseded by xone, is listed mainly for historical context, and MissionControl solves the same controller problem on Nintendo Switch over Bluetooth rather than on Linux. The practical split is: xpadneo for Xbox One S and Elite 2 over Bluetooth on Linux, xone when you need GIP coverage or Series hardware, xpad when the cable is fine.

Licence, packaging and the cost of a kernel module

The source files carry SPDX-License-Identifier: GPL-3.0-or-later, while the repository's licence metadata is reported as NOASSERTION. The README has a heads-up for package maintainers saying licensing has changed and pointing at LICENSE.md for details, so anyone redistributing xpadneo should read that file rather than infer terms from the SPDX headers. Nothing here is legal advice, and the LICENSES/ directory exists precisely because the project takes per-file licensing seriously.

Upgrade cost is the real ongoing expense. The module is built through DKMS, so a kernel update triggers a rebuild, and a DKMS build failure on a new kernel leaves you without the driver until it is fixed. The Makefile's PREFIX handling is a signal of where this bites: distributions that install to a prefix must run the dkms commands in their own package scripts, and the build prints a warning saying so. The repository also warns that the installation process changed and that packaging helpers were introduced, which means older third-party recipes may not match the current layout.

On the positive side, the project is packaged widely enough that Repology tracks it across distributions, and the README links that packaging status. For most users the honest calculation is: install the distribution package if one exists for your release, and fall back to install.sh only when it does not.

Editorial conclusion

Adopt xpadneo if you use an Xbox One S or Xbox Elite 2 controller over Bluetooth on kernel 4.18 or newer and you want trigger rumble, battery reporting and a mapping that survives being paired to Windows first. Skip it if you need USB or dongle support, controller audio, or support for Xbox Series X|S accessories, since the README lists those as unavailable and points at xone for full GIP coverage. Before installing, check uname -r against the 4.18 floor, confirm your distribution packages xpadneo (Repology tracks it) or that DKMS is available, and decide whether the 70-xpadneo-disable-hidraw.rules udev rule fits your setup, because SDL2 games that grab hidraw will read the wrong mappings and the README's fix is to export SDL_JOYSTICK_HIDAPI=0.

Frequently asked questions

Official sources

1. atar-axis/xpadneo on GitHub
2. Issues
3. Project website
4. README
5. Releases