Skip to content
Advanced Linux Driver for Xbox One Wireless Controller (shipped with Xbox One S)
Branch: master
Clone or download
gordonsolar and atar-axis Create (#104)
* add: asyncio example

example class to use the xbox controller with python asyncio (asynchronous mode, coroutines) and evdev
not all buttons and triggers are included in this class - it is an example only.
python>=3.6 is necessary
script is tested on a raspberry pi 3
Latest commit 560e3ea May 15, 2019

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

Build Status Codacy Badge Average time to resolve an issue

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)
    Battery Level Indication
  • 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


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 here in this case.

Please feel free to add other Distributions as well!


  • Download the Repository to your local machine git clone
  • cd xpadneo
  • Run sudo ./
  • Done!


  • 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>

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


  • Use sudo ./ to configure the driver as you wish. The script will guide you through the available options.


In order to update xpadneo, do the following

  • Update your cloned repo: git pull
  • Run sudo ./


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

Further information

For further information please visit the GitHub Page which is generated automatically from the content of the /docs folder.

You will find there e.g. the following sections

You can’t perform that action at this time.