snpefk/xpadneo

Advanced Linux Driver for Xbox One Wireless Controller (shipped with Xbox One S)

If you want to support me or accelerate the development of a special feature, consider a small donation ❤️
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

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 all Force Feedback/Rumble effects through Linux ff-memless effect emulation
• 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 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, and independent of software layers (SDL2, Stadia via Chrome Gamepad API, etc)
• Working Select, Start, Mode buttons
• Supports Battery Level Indication (including the Play `n Charge Kit)
• 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 make 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 here in this case.
• On generic distributions, it doesn't need DKMS but requires a configured kernel source tree, then: cd hid-xpadneo && make modules && sudo make modules_install

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
• If using DKMS, run sudo ./install.sh
• If not using DKMS, follow steps above (generic distribution)
• Done!

Connection

• sudo bluetoothctl
• [bluetooth]# scan on
• wait until all available devices are listed (otherwise it may be hard to identify which one is the gamepad)
• 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 address (e.g. C8:3F:26:XX:XX:XX)
• [bluetooth]# pair <MAC>
• [bluetooth]# trust <MAC>
• [bluetooth]# connect <MAC>
• The <MAC> parameter is optional if the command line already shows the controller name

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

Configuration

• If using DKMS: Use sudo ./configure.sh to configure the driver as you wish. The script will guide you through the available options.

Update

In order to update xpadneo, do the following

• Update your cloned repo: git pull
• If using DKMS: Run sudo ./update.sh
• otherwise follow the steps above (generic distribution)

Uninstallation

• If using DKSM: Run sudo ./uninstall.sh to remove all installed versions of hid-xpadneo
• otherwise follow the steps above (generic distribution)

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

• Troubleshooting
• Debugging
• Compatible BT Dongles