Linux driver for the Xbox One wireless dongle
xow is a Linux user mode driver for the Xbox One wireless dongle. It communicates with the dongle via
libusband provides joystick input through the
uinputkernel module. The input mapping is based on existing kernel drivers like xpad.
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 number | Year | Additional information | Status | |--------------|------|---------------------------|--------------| | 1537 | 2013 | Original controller | Working | | 1697 | 2015 | Audio jack | Working | | 1698 | 2015 | Elite controller | Working | | 1708 | 2016 | Bluetooth connectivity | Working | | 1797 | 2019 | Elite controller series 2 | Working | | 1914 | 2020 | Share button and USB-C | Untested |
Feel free to package xow for any Linux distribution or hardware you like, as long as you do not publish any prebuilt executables. The build process embeds a copy of Microsoft's proprietary firmware into the binary, prohibiting any type of distribution. Any issues regarding the packaging should be reported to the respective maintainers.
Clone the repository (necessary for version tagging to work):
git clone https://github.com/medusalix/xow
Build xow using the following command:
NOTE: Please use
BUILD=DEBUGwhen asked for your debug logs.
Install xow as a
systemdunit (runs xow at boot time) and start the service:
sudo make install 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.
Make sure to completely uninstall xow before updating:
sudo systemctl stop xow sudo systemctl disable xow sudo make uninstall
You can enable the dongle's pairing mode by sending the
SIGUSR1signal to xow:
sudo systemctl kill -s SIGUSR1 xow
NOTE: Signals are only handled after a dongle has been plugged in. The default behavior for
SIGUSR1is to terminate the process.
InputException: No such file or directory
/dev/uinputdevice has to be available. The
uinputkernel module needs to be loaded.
InputException: Permission denied
/dev/uinputhave to allow read and write access. The
udevrules need to be installed and any conflicts with existing rules have to be resolved.
Mt76Exception: Failed to load firmware
Using an outdated version of
libusbcan cause various issues. Make sure to update
libusbto the latest version.
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.
systemddaemon and restart the service. Controllers connected to the dongle will appear as Xbox 360 controllers.
Some USB controllers are known to cause issues with xow. Plugging your dongle into a USB port that uses an
ASMediacontroller will lead to problems. Most
IntelUSB 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.
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.
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
mt76kernel 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.
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.