{"id":13820270,"url":"https://github.com/medusalix/xow","last_synced_at":"2025-05-16T05:04:12.220Z","repository":{"id":42680374,"uuid":"229464145","full_name":"medusalix/xow","owner":"medusalix","description":"Linux driver for the Xbox One wireless dongle","archived":false,"fork":false,"pushed_at":"2022-04-24T16:22:09.000Z","size":1186,"stargazers_count":1440,"open_issues_count":50,"forks_count":89,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-05-16T05:03:36.098Z","etag":null,"topics":["dongle","linux","usb","user-mode","wireless","xbox","xbox-one"],"latest_commit_sha":null,"homepage":"https://medusalix.github.io/xow","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/medusalix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-21T17:59:19.000Z","updated_at":"2025-05-15T14:43:09.000Z","dependencies_parsed_at":"2022-09-22T00:31:40.667Z","dependency_job_id":null,"html_url":"https://github.com/medusalix/xow","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medusalix%2Fxow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medusalix%2Fxow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medusalix%2Fxow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medusalix%2Fxow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/medusalix","download_url":"https://codeload.github.com/medusalix/xow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471061,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dongle","linux","usb","user-mode","wireless","xbox","xbox-one"],"created_at":"2024-08-04T08:01:00.539Z","updated_at":"2025-05-16T05:04:12.199Z","avatar_url":"https://github.com/medusalix.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/logo.png\" alt=\"Logo\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/medusalix/xow/actions\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/workflow/status/medusalix/xow/Continuous%20Integration\" alt=\"Build Badge\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/medusalix/xow/releases/latest\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/v/release/medusalix/xow\" alt=\"Release Badge\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://discord.gg/FDQxwWk\"\u003e\n        \u003cimg src=\"https://img.shields.io/discord/733964971842732042\" alt=\"Discord Badge\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshot.png\" alt=\"Screenshot\"\u003e\n\u003c/p\u003e\n\n# This project is in maintenance mode\n\nUpgrading to [xone](https://github.com/medusalix/xone) is *highly recommended*!\n\n## About\n\nxow is a Linux user mode driver for the Xbox One wireless dongle.\nIt communicates with the dongle via `libusb` and provides joystick input through the `uinput` kernel module.\nThe input mapping is based on existing kernel drivers like [xpad](https://github.com/paroj/xpad).\n\n## Supported devices\n\nxow supports both versions of the wireless dongle (slim and bulky one) and the Surface Book 2's built-in adapter.\nThe following Xbox One controllers are currently compatible with the driver:\n\n| Model number | Year | Additional information    | Status       |\n|--------------|------|---------------------------|--------------|\n| 1537         | 2013 | Original controller       | **Working**  |\n| 1697         | 2015 | Audio jack                | **Working**  |\n| 1698         | 2015 | Elite controller          | **Working**  |\n| 1708         | 2016 | Bluetooth connectivity    | **Working**  |\n| 1797         | 2019 | Elite controller series 2 | **Working**  |\n| 1914         | 2020 | Share button and USB-C    | **Untested** |\n\n## Releases\n\n### Linux distributions\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/xow.svg)](https://repology.org/project/xow/versions)\n\n- [RPM packaging instructions](https://gitlab.com/yajoman/xow-rpm) (for distributions like Fedora)\n\n### Third-party hardware\n\n- EmuELEC (starting with [version 3.3](https://github.com/EmuELEC/EmuELEC/releases/tag/v3.3))\n- Steam Link (starting with [build 747](https://steamcommunity.com/app/353380/discussions/0/1735510154204276395))\n\nFeel free to package xow for any Linux distribution or hardware you like.\nAny issues regarding the packaging should be reported to the respective maintainers.\n\n## Installation\n\n### Prerequisites\n\n- Linux (kernel 4.5 or newer)\n- curl (for proprietary driver download)\n- cabextract (for firmware extraction)\n- libusb (libusb-1.0-0-dev for Debian)\n- systemd (version 232 or newer)\n\n### Guide\n\n1. Clone the repository:\n\n```\ngit clone https://github.com/medusalix/xow\n```\n\n2. Build and install xow:\n\n```\ncd xow\nmake BUILD=RELEASE\nsudo make install\n```\n\n**NOTE:** Please use `BUILD=DEBUG` when asked for your debug logs.\n\n3. Download the firmware for the wireless dongle:\n\n```\nsudo xow-get-firmware.sh\n```\n\n**NOTE:** The `--skip-disclaimer` flag might be useful for scripting purposes.\n\n4. Enable and start the `systemd` service (runs xow at boot time):\n\n```\nsudo systemctl enable xow\nsudo systemctl start xow\n```\n\n**NOTE:** Running xow manually is **strongly discouraged**. A reboot might be required for xow to work correctly.\n\n### Updating\n\nMake sure to completely uninstall xow before updating:\n\n```\nsudo systemctl stop xow\nsudo systemctl disable xow\nsudo make uninstall\n```\n\n## Interoperability\n\nYou can enable the dongle's pairing mode by sending the `SIGUSR1` signal to xow:\n\n```\nsudo systemctl kill -s SIGUSR1 xow\n```\n\n**NOTE:** Signals are only handled *after* a dongle has been plugged in. The default behavior for `SIGUSR1` is to terminate the process.\n\n## Troubleshooting\n\n### Error messages\n\n- `InputException`: No such file or directory\n    - The `/dev/uinput` device has to be available. The `uinput` kernel module needs to be loaded.\n- `InputException`: Permission denied\n    - The permissions for `/dev/uinput` have to allow read and write access. The `udev` rules need to be installed and any conflicts with existing rules have to be resolved.\n- `Mt76Exception`: Failed to load firmware\n    - Another driver might have already loaded the dongle's firmware. The dongle needs to be unplugged to reset its internal memory, followed by a restart of xow's `systemd` service.\n- `LIBUSB_ERROR_TIMEOUT`\n    - See the [USB incompatibilities](#usb-incompatibilities) section.\n- `LIBUSB_ERROR_BUSY` or `LIBUSB_ERROR_NO_DEVICE`\n    - Only a single program can communicate with the dongle at once. Any existing drivers that might interfere with xow need to be disabled. This includes running multiple instances of xow.\n- `LIBUSB_ERROR_ACCESS`\n    - The permissions for the dongle's USB device have to be set correctly. This is also handled by the `udev` rules.\n\nUsing an outdated version of `libusb` can cause various issues. Make sure to update `libusb` to the latest version.\n\n### Pairing problems\n\nThe 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.\n\n### Configuration issues\n\n- Certain games do not detect wireless controllers\n    - Enable the *compatibility mode* in the service configuration, reload the `systemd` daemon and restart the service.\n    Controllers connected to the dongle will appear as Xbox 360 controllers.\n- Buttons/triggers/sticks are mapped incorrectly\n    - Try the options listed on [this page](https://wiki.archlinux.org/index.php/Gamepad#Setting_up_deadzones_and_calibration) to remap your inputs.\n- Input from the sticks is jumping around\n    - Try the options listed on [this page](https://wiki.archlinux.org/index.php/Gamepad#Setting_up_deadzones_and_calibration) to set your deadzones.\n\n### USB incompatibilities\n\nSome 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.\nPower 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.\n\n### Other problems\n\nIn case of any other problems, please open an issue with all the relevant details (dongle version, controller version, logs, captures, etc.).\n\n**NOTE:** Please refrain from creating issues concerning input remapping, deadzones or game compatibility as these topics are outside the scope of this project.\n\n## How it works\n\nThe dongle's wireless chip (MT76xx) handles the WLAN connection with individual controllers.\nThe packet format follows Microsoft's undisclosed GIP (Game Input Protocol) specification.\nMost of the reverse engineering was done by capturing the communication between the dongle and a Windows PC using [`Wireshark`](https://www.wireshark.org).\nAs no datasheets for this chip are publicly available, I have used datasheets of similar wireless radios for assistance.\nSpecial thanks to the authors of OpenWrt's [`mt76`](https://github.com/openwrt/mt76) kernel driver.\nIt would have been impossible for me to create this driver without `mt76`'s source code.\nIf anyone has a greater understanding of the GIP or the weird quirks I had to add to make the driver work, please contact me.\n\n## License\n\nxow is released under the [GNU General Public License, Version 2](LICENSE).\n\n```\nCopyright (C) 2019 Medusalix\n\nThis program is free software; you can redistribute it and/or\nmodify it under the terms of the GNU General Public License\nas published by the Free Software Foundation; either version 2\nof the License, or (at your option) any later version.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedusalix%2Fxow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmedusalix%2Fxow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedusalix%2Fxow/lists"}