Home

Awesome

<p align="center"> <img src="assets/logo.png" alt="Logo"> </p> <p align="center"> <a href="https://github.com/medusalix/xow/actions"> <img src="https://img.shields.io/github/workflow/status/medusalix/xow/Continuous%20Integration" alt="Build Badge"> </a> <a href="https://github.com/medusalix/xow/releases/latest"> <img src="https://img.shields.io/github/v/release/medusalix/xow" alt="Release Badge"> </a> <a href="https://discord.gg/FDQxwWk"> <img src="https://img.shields.io/discord/733964971842732042" alt="Discord Badge"> </a> </p> <p align="center"> <img src="assets/screenshot.png" alt="Screenshot"> </p>

This project is in maintenance mode

Upgrading to xone is highly recommended!

About

xow is a Linux user mode driver for the Xbox One wireless dongle. It communicates with the dongle via libusb and provides joystick input through the uinput kernel module. The input mapping is based on existing kernel drivers like xpad.

Supported devices

xow supports both versions of the wireless dongle (slim and bulky one) and the Surface Book 2's built-in adapter. The following Xbox One controllers are currently compatible with the driver:

Model numberYearAdditional informationStatus
15372013Original controllerWorking
16972015Audio jackWorking
16982015Elite controllerWorking
17082016Bluetooth connectivityWorking
17972019Elite controller series 2Working
19142020Share button and USB-CUntested

Releases

Linux distributions

Packaging status

Third-party hardware

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

Installation

Prerequisites

Guide

  1. Clone the repository:
git clone https://github.com/medusalix/xow
  1. Build and install xow:
cd xow
make BUILD=RELEASE
sudo make install

NOTE: Please use BUILD=DEBUG when asked for your debug logs.

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

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

  1. Enable and start the systemd service (runs xow at boot time):
sudo systemctl enable xow
sudo systemctl start xow

NOTE: Running xow manually is strongly discouraged. A reboot might be required for xow to work correctly.

Updating

Make sure to completely uninstall xow before updating:

sudo systemctl stop xow
sudo systemctl disable xow
sudo make uninstall

Interoperability

You can enable the dongle's pairing mode by sending the SIGUSR1 signal to xow:

sudo systemctl kill -s SIGUSR1 xow

NOTE: Signals are only handled after a dongle has been plugged in. The default behavior for SIGUSR1 is to terminate the process.

Troubleshooting

Error messages

Using an outdated version of libusb can cause various issues. Make sure to update libusb to the latest version.

Pairing problems

The controller only remembers the last device it was connected to. It will not automatically establish a connection to the dongle if it was previously plugged into a USB port or paired via bluetooth, even if the same computer was used.

Configuration issues

USB incompatibilities

Some USB controllers are known to cause issues with xow. Plugging your dongle into a USB port that uses an ASMedia controller will lead to problems. Most Intel USB controllers work well with xow. Power management issues can arise when using a USB 3 controller. These can lead to timeouts of the USB communication. The use of a USB hub can mitigate these problems.

Other problems

In case of any other problems, please open an issue with all the relevant details (dongle version, controller version, logs, captures, etc.).

NOTE: Please refrain from creating issues concerning input remapping, deadzones or game compatibility as these topics are outside the scope of this project.

How it works

The dongle's wireless chip (MT76xx) handles the WLAN connection with individual controllers. The packet format follows Microsoft's undisclosed GIP (Game Input Protocol) specification. Most of the reverse engineering was done by capturing the communication between the dongle and a Windows PC using Wireshark. As no datasheets for this chip are publicly available, I have used datasheets of similar wireless radios for assistance. Special thanks to the authors of OpenWrt's mt76 kernel driver. It would have been impossible for me to create this driver without mt76's source code. If anyone has a greater understanding of the GIP or the weird quirks I had to add to make the driver work, please contact me.

License

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

Copyright (C) 2019 Medusalix

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.