/xone

Linux kernel driver for Xbox One and Xbox Series X|S accessories

Primary LanguageCGNU General Public License v2.0GPL-2.0

xone Release Badge Discord Badge Donate Button

xone is a Linux kernel driver for Xbox One and Xbox Series X|S accessories. It serves as a modern replacement for xpad, aiming to be compatible with Microsoft's Game Input Protocol (GIP).

Compatibility

  • Wired devices (via USB)
  • Wireless devices (with Xbox Wireless Dongle)
  • Bluetooth devices (check out xpadneo)

Important notes

This driver is still in active development. Use at your own risk! If you are running xow upgrading to xone is highly recommended! Always update your Xbox devices to the latest firmware version! Any feedback including bug reports, suggestions or ideas is greatly appreciated.

Features

  • Input and force feedback (rumble)
  • Battery reporting (UPower integration)
  • LED control (using /sys/class/leds)
  • Audio capture/playback (through ALSA)
  • Power management (suspend/resume and remote/wireless wakeup)

Supported devices

  • Gamepads
    • Xbox One Controllers
    • Xbox Series X|S Controllers
    • Third party controllers (PowerA, PDP, etc.)
  • Headsets
    • Xbox One Chat Headset
    • Xbox One Stereo Headset (adapter or jack)
    • Xbox Wireless Headset
    • Third party wireless headsets (SteelSeries, Razer, etc.)
  • Third party racing wheels (Thrustmaster, Logitech, etc.)
  • Xbox One Chatpad
  • Xbox Adaptive Controller
  • Mad Catz Rock Band 4 Wireless Stratocaster

⚠️ Standalone wireless headsets are currently not supported!

Releases

Packaging status

Feel free to package xone for any Linux distribution or hardware you like. Any issues regarding the packaging should be reported to the respective maintainers.

Installation

Prerequisites

  • Linux (kernel 4.15+ and headers)
  • DKMS
  • curl (for firmware download)
  • cabextract (for firmware extraction)

Guide

  1. Unplug your Xbox devices.

  2. Clone the repository:

git clone https://github.com/dlundqvist/xone
  1. Install xone:
cd xone
sudo ./install.sh --release

NOTE: Please omit the --release flag when asked for your debug logs.

  1. Download the firmware for the wireless dongle:
sudo xone-get-firmware.sh

NOTE: The --skip-disclaimer flag might be useful for scripting purposes.

  1. Plug in your Xbox devices.

Updating

Make sure to completely uninstall xone before updating:

sudo ./uninstall.sh

Using Xbox 360 controllers with xone

xone doesn't support Xbox 360 controllers at all. On top of that, xone needs to disable xpad driver to work properly, which would normally support Xbox 360 controllers. This is due to xpad also trying to handle Xbox One controllers, which xone aims to support.

To fix that, there is a fork of xpad driver, called xpad-noone that has disabled support for Xbox One controllers, so it can coexist with xone driver. If you're using Xbox 360 controllers, it is recommended to use it to replace the standard xpad driver.

Installation on Steam Deck

An installation script for the Steam Deck is available here. It handles all the prerequisites and other quirks, along with installing xone-noone.

You can run it by executing the following command: wget -O /tmp/bootstrap.sh https://t.ly/kEf0 && sh /tmp/bootstrap.sh

Wireless pairing

Xbox devices have to be paired to the wireless dongle. They will not automatically connect to the dongle if they have been previously plugged into a USB port or used via Bluetooth.

Instructions for pairing your devices can be found here (see the section on Xbox Wireless).

Kernel interface

LED control

The guide button LED can be controlled via sysfs:

echo 2 | sudo tee /sys/class/leds/gip*/mode
echo 5 | sudo tee /sys/class/leds/gip*/brightness

Replace the wildcard (gip*) if you want to control the LED of a specific device. The modes and the maximum brightness can vary from device to device.

Pairing mode

The pairing mode of the dongle can be queried via sysfs:

cat /sys/bus/usb/drivers/xone-dongle/*/pairing

You can enable (1) or disable (0) the pairing using the following command:

echo 1 | sudo tee /sys/bus/usb/drivers/xone-dongle/*/pairing

Troubleshooting

Uninstall the release version and install a debug build of xone (see installation guide). Run sudo dmesg to gather logs and check for any error messages related to xone. If xone is not being loaded automatically you might have to reboot your system.

Error messages

  • Direct firmware load for xow_dongle.bin failed with error -2
    • Download the firmware for the wireless dongle (see installation guide).

Input issues

You can use evtest and fftest to check the input and force feedback functionality of your devices.

Other problems

Please join the Discord server in case of any other problems.

License

xone is released under the GNU General Public License, Version 2.

Copyright (C) 2021 Severin von Wnuck

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.