I would like to include support for the Xbox Elite Wireless Controller, therefore I started a crowdfunding project. It would be great if some of you would donate some cents for the necessary hardware.

Advanced Linux Driver for Xbox One Wireless Gamepad

This is the first and yet only 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 🎮 (including Wireless Adapter) and a pack of mouthwatering guarana cacao ☕

Advantages of this driver

• Supports Bluetooth
• Supports Force Feedback (Rumble) in General
• Supports Trigger Force Feedback (not even supported in Windows)
  see it in action: run misc/tools/directional_rumble_test/direction_rumble_test <event# in /dev/input>
• Supports disabling FF
• Supports multiple Gamepads at the same time (not even supported in Windows)
• Offers a consistent mapping, even if the Gamepad was paired to Windows/Xbox before
• Working Select, Start, Mode buttons
• Correct Axis Range (signed, important for e.g. RPCS3)
• Supports Battery Level Indication (including the Play `n Charge Kit)
  
• Supports faking the Input Device Version in order to prevent SDL from trying to fix an unbroken mapping.
• Easy Installation
• Agile Support and Development

Getting started

Prerequisites

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

• On Arch and Arch-based distros (like Antergos), try
  sudo pacman -S dkms linux-headers bluez bluez-utils
• On Debian based systems (like Ubuntu) you can install those packages by running
  sudo apt-get install dkms linux-headers-`uname -r`
• On Fedora, it is
  sudo dnf install dkms bluez bluez-tools kernel-devel-`uname -r` kernel-headers-`uname -r`
• On OSMC you will have to run the following commands
  sudo apt-get install dkms rbp2-headers-`uname -r`
sudo ln -s "/usr/src/rbp2-headers-`uname -r`" "/lib/modules/`uname -r`/build" (as a workaround)
• On Raspbian, it is
  sudo apt-get install dkms raspberrypi-kernel-headers
  If you recently updated your firmware using rpi-update the above package may not yet include the header files for your kernel.
  Please follow the steps described at rpi-src to get the headers for your currently running kernel.

Please feel free to add other Distributions as well!

Installation

• Download the Repository to your local machine git clone https://github.com/atar-axis/xpadneo.git
• cd xpadneo
• Run ./install.sh
• Done!

Connection

• sudo bluetoothctl
• [bluetooth]# scan on
• push the connect button on upper side of the gamepad, and hold it down, until the light starts flashing fast
• wait for the gamepad to show up in bluetoothctl, remember the MAC address (C8:3F:26:XX:XX:XX)
• [bluetooth]# pair <MAC>
• [bluetooth]# trust <MAC>
• [bluetooth]# connect <MAC>

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

The gamepad did not rumble ? Secure Boot may be enabled on your computer. On most Linux distribution, running mokutil --sb-state will tell you if it is the case. When Secure Boot is enabled, unsigned kernel module cannot be loaded. Two options are available:

1. Disable Secure Boot.
2. Sign the module yourself. Instructions for both of these options are available here.

Secure Boot is not enabled and pairing still fails? See Debugging.

Configuration

The driver can be reconfigured at runtime by accessing the following sysfs files in /sys/module/hid_xpadneo/parameters:

• debug_level (default 0)
  • 0 (no debug output) to 3 (all)
  • For more information, please take a look here
• disable_ff (default 0)
  • 0 (ff enabled) to 1 (ff disabled)
• trigger_rumble_damping (default 4)
  • Damp the strength of the trigger force feedback
  • 1 (none) to 256 (max)
• fake_dev_version (default 0x1130)
  • Fake the input device version to the given value (to prevent SDL from applying another mapping, see below)
  • Values from 1 to 0xFFFF are handled as a version number, 0 will retain the original version
• combined_z_axis (default `0´)
  • Combine the triggers (ABS_Z and ABS_RZ) to form a single axis ABS_Z which is used e.g. in flight simulators
  • The left and right trigger will work against each other.

Some settings may need to be changed at loading time of the module, take a look at the following example to see how that works:

Example To set the highest level of debug verbosity temporarily, run
echo 3 | sudo tee /sys/module/hid_xpadneo/parameters/debug_level To make the setting permanent and applied at loading time, try echo "options hid_xpadneo debug_level=3" | sudo tee /etc/modprobe.d/xpadneo.conf

Update

In order to update xpadneo, do the following

• Update your cloned directory (and reset all locally changes files) by running
  • git reset --hard
  • git pull
• Run ./update.sh

Uninstallation

• Run ./uninstall.sh to remove all installed versions of hid-xpadneo

Further information

If someone is interested in helping me getting this driver merged into the kernel, tell me. I would really appreciate that.

For further information, like instructions for troubleshooting, please visit the GitHub Page https://atar-axis.github.io/xpadneo/ which is generated automatically from the input of the /docs folder.