{"id":19564184,"url":"https://github.com/wheaney/xrlinuxdriver","last_synced_at":"2026-03-05T21:25:55.855Z","repository":{"id":173433510,"uuid":"650759352","full_name":"wheaney/XRLinuxDriver","owner":"wheaney","description":"Linux service for interacting with XR devices","archived":false,"fork":false,"pushed_at":"2026-03-03T20:13:14.000Z","size":90062,"stargazers_count":393,"open_issues_count":11,"forks_count":40,"subscribers_count":16,"default_branch":"main","last_synced_at":"2026-03-03T22:25:25.846Z","etag":null,"topics":["ar","head-tracking","hmd-driver","linux-controller-driver","linux-driver","steam-deck","user-space-driver","virtual-controller","viture","vr","xr","xreal","xreal-air"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wheaney.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"wheaney","patreon":null,"open_collective":null,"ko_fi":"wheaney","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2023-06-07T18:42:43.000Z","updated_at":"2026-03-03T20:05:14.000Z","dependencies_parsed_at":"2023-10-13T02:03:54.769Z","dependency_job_id":"8e27960d-2ddf-4363-85d4-c91f00123950","html_url":"https://github.com/wheaney/XRLinuxDriver","commit_stats":null,"previous_names":["wheaney/nrealairlinuxdriver","wheaney/xrealairlinuxdriver","wheaney/xrlinuxdriver"],"tags_count":135,"template":false,"template_full_name":null,"purl":"pkg:github/wheaney/XRLinuxDriver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wheaney%2FXRLinuxDriver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wheaney%2FXRLinuxDriver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wheaney%2FXRLinuxDriver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wheaney%2FXRLinuxDriver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wheaney","download_url":"https://codeload.github.com/wheaney/XRLinuxDriver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wheaney%2FXRLinuxDriver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30150282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T21:15:50.531Z","status":"ssl_error","status_checked_at":"2026-03-05T21:15:11.173Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["ar","head-tracking","hmd-driver","linux-controller-driver","linux-driver","steam-deck","user-space-driver","virtual-controller","viture","vr","xr","xreal","xreal-air"],"created_at":"2024-11-11T05:20:34.537Z","updated_at":"2026-03-05T21:25:55.833Z","avatar_url":"https://github.com/wheaney.png","language":"C","readme":"# XR Linux Driver\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/U7U8OVC0L)\n\n[![Chat](https://img.shields.io/badge/chat-on%20discord-7289da.svg)](https://discord.gg/azSBTXNXMt)\n\n## What is this?\n\nThis driver allows your Linux device (including Steam Deck) to automatically recognize supported XR glasses (see [Supported Devices](#supported-devices)) when they're plugged in, and convert the movements of the glasses into mouse movements and an external broadcast that games or any application can utilize.\n\nIf you're looking for a 3dof virtual display, this driver by itself does not provide that functionality; instead, see [Breezy](https://github.com/wheaney/breezy-desktop) or [use the Steam Deck plugin](#steam-deck-via-decky-loader) which installs Breezy under the hood.\n\n## Supported Devices\nCheck below to see if your device is supported. **Note: be sure you're on the latest firmware for your device.**\n\n| Brand    | Model             | Support?            | Recommend?   | x86_64 (AMD64) | AARCH64 (ARM64) | Firmware updates                                          | Notes                                                                                                                                   |\n| -------- | ----------------- | -----------------   | ------------ | -------------- | --------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| VITURE   | One,One Lite, Pro | :heavy_check_mark: | :+1: | :heavy_check_mark: | :heavy_check_mark: | [Official update site](https://static.viture.com/dfu-util/). Requires Chrome on Windows/Mac. | Official collaboration. [Closed source SDK available](https://www.viture.com/developer/viture-one-sdk-for-linux). |\n| TCL/RayNeo | NXTWEAR S/S+; Air 2 | :heavy_check_mark: | :+1:          | :heavy_check_mark: |             |                                                       | Official collaboration, closed source SDK.                                                                                              |\n| Rokid    | Max, Air          | :heavy_check_mark: | :+1: | :heavy_check_mark:              |             |                                                       | Official collaboration, closed source SDK.                                                                                              |\n| XREAL    | Air 1, 2, 2 Pro   | :heavy_check_mark: | :-1: | :heavy_check_mark: | :heavy_check_mark: | [Officlal update site](https://www.xreal.com/support/update/). Requires Chrome. | Unwilling to collaborate. [Unofficial, open-source SDK](https://gitlab.com/TheJackiMonster/nrealAirLinuxDriver). Exhibits drift, noise. |\n| XREAL    | Air 2 Ultra   | **Partially** (see notes) | :-1: | :heavy_check_mark: | :heavy_check_mark:    | same                                                  | No side-by-side mode. No widescreen mode on Breezy GNOME. Same limiatations as other XREAL models above.                                |\n\n## Usage\n\n### Steam Deck via Decky Loader\n\nFor Steam Deck users, the driver is available via the [Decky plugin loader](https://github.com/SteamDeckHomebrew/decky-loader). Just search \"xr\" in the Decky store to install and use without leaving Gaming Mode. You can now enable or disable the driver and manage other driver settings via the Decky sidebar menu.\n\nYou may still opt to do a manual installation using the instructions below if you enter Desktop Mode.\n\n### Manual installation\n\n*Note: this installation is for just the base driver with mouse/joystick support. If you're looking for virtual display mode, check out the [breezy-desktop setup](https://github.com/wheaney/breezy-desktop#setup).*\n\n1. [Download the setup script](https://github.com/wheaney/XRLinuxDriver/releases/latest/download/xr_driver_setup) and set the execute flag (e.g. from the terminal: `chmod +x ~/Downloads/xr_driver_setup`)\n2. Run the setup script as root (e.g. `sudo ~/Downloads/xr_driver_setup`)\n  \nYour device should now automatically recognize when your glasses are plugged in and translate their movements to mouse movements. If you're not seeing this, check the log at `$XDG_STATE_HOME/xr_driver/driver.log` and report an Issue here with its contents.\n\n#### Turning automatic driver usage on or off\n\nTo disable the driver and turn off mouse movements without completely removing it, you can use the config script (e.g. `xr_driver_cli -d` to disable, and `-e` to re-enable). Run this script without arguments to see its usage. Configs are stored in the file `$XDG_CONFIG_HOME/xr_driver/config.ini`.\n\n### Practical Usage\n\nSince the device movements are converted to mouse movements, they should be recognized by any PC game that supports keyboard/mouse input. This will work most naturally for games where mouse movements is used to control \"look\"/camera movements. For point-and-click style games, you may want to disable the driver so your glasses act as just a simple display.\n\nTo adjust the sensitivity of mapping head movements to mouse movements, use the Decky UI on Steam Deck, or `xr_driver_cli --mouse-sensitivity 20` via the terminal.\n\nIf you're using keyboard and mouse to control your games, then the mouse movements from this driver will simply add to your own mouse movements and they should work naturally together.\n\nIf you're using a game controller, Valve pushes pretty heavily for PC games support mouse input *in addition to* controller input, so you should find that most modern games will just work with this driver straight out of the box.\n\nIf your game doesn't support blending mouse and controller movement well, the best option may be to convert your controller's input to keyboard and mouse. Read on for how to do this for Steam and non-Steam games.\n\n#### Steam\n\n1. Open your game's controller configuration in Steam\n2. Open the Layouts view\n3. Choose a keyboard/mouse template (e.g. \"Keyboard (WASD) and Mouse\"). Be sure to edit the configuration and set \"Gyro Behavior\" to \"As Mouse\" for any games where you want to use gyro.\n\n#### Non-Steam\n\nYou'll probably want to use a utility that does what Steam's controller layouts are doing behind the scenes: mapping controller buttons, joystick, and gyro inputs to keyboard/mouse inputs. One popular tool is [JoyShockMapper](https://github.com/Electronicks/JoyShockMapper).\n\n#### Enable joystick mode\n\nOne last alternative if mouse input just won't work is to enable the driver's joystick mode, using the Decky UI on Steam Deck, or `xr_driver_cli --use-joystick` via the terminal (you can revert this with `--use-mouse`). This will create a virtual gamepad whose right joystick is driven by movements from the glasses. This is less ideal because joystick movements are technically capped (you can only move a joystick so far...) and because it's a *second* controller on your PC. If the game you're trying to play is okay being driven by two controllers, then this may work, but if your game interprets another controller as a second player then its movements won't get combined with your real controller's movements.\n\n### Updating\n\nIf using Decky, updates are installed through Decky.\n\nOtherwise, just rerun the `xr_driver_setup` file. No need to redownload this script, as it will automatically download the latest installation binary for you.\n\n### Uninstalling\n\nIf you wish to completely remove the installation, run the following script as root: `~/.local/bin/xr_driver_uninstall`. For Steam Deck users, you can uninstall the plugin via the Decky interface, but you'll still need to manually run the terminal command from Desktop Mode to complete the uninstall until [this Decky feature request](https://github.com/SteamDeckHomebrew/decky-loader/issues/536) is addressed.\n\n## Development\n\n### Dependencies\n\nYou can build the binary using `cmake` and there are a few dependencies for now:\n - [hidapi](https://github.com/libusb/hidapi)\n - [json-c](https://github.com/json-c/json-c/)\n - [Fusion](https://github.com/xioTechnologies/Fusion)\n - [libevdev](https://gitlab.freedesktop.org/libevdev/libevdev)\n\nFusion and hidapi source are included as Git submodules that you'll need to check out using the `git submodules` command. json-c may already be installed with your distro, and you'll want to install libevdev (e.g. `sudo apt install libevdev-dev`).\n\n### Build \u0026 Testing\n\nFor local testing, you'll want to use the same package as for deployment: run `bin/package` to create the gzip, then run `sudo bin/xr_driver_setup $(pwd)/build/xrDriver.tar.gz` to install and test it.\n\n### Deployment\n\nTo create the deployment gzip file, run `bin/package`. Upload the resulting gzip file and the `bin/xr_driver_setup` file to a new Release.\n\n## Data Privacy Notice\n\nYour right to privacy and the protection of your personal data are baked into every decision around how your personal data is collected, handled and stored. Your personal data will never be shared, sold, or distributed in any form.\n\n### Data Collected\n\nIn order to provide you with Supporter Tier features, this application and its backend services have to collect the following pieces of personal information:\n\n* Your email address is sent to this application's backend server from either the payment vendor (Ko-fi) or from your device (at your request). Your email address may be used immediately upon receipt in its unaltered form to send you a transactional email, but it is then hashed prior to storage. The unaltered form of your email address is never stored and can no longer be referenced. The hashed value is stored for later reference.\n  * Other personal data may be sent from the payment vendor, but is never utilized nor stored. \n* Your device's MAC address is hashed on your device. It never leaves your device in its original, unaltered form. The hashed value is sent to this application's backend server and stored for later reference.\n\nHashing functions are a one-way process that serve to anonymize your personal data by irreversibly changing them. Once hashed, they can never be unhashed or traced back to their original values.\n\n### Contact\n\nFor inquires about data privacy or any related concerns, please contact:\n\nWayne Heaney - **wayne@xronlinux.com**\n\n## Credits\n\nThis driver wouldn't have been possible without the work of Tobias Frisch for his [base Linux driver](https://gitlab.com/TheJackiMonster/nrealAirLinuxDriver) that this uses under the hood, Matt Smith for his [Windows driver](https://github.com/MSmithDev/AirAPI_Windows/), and others that worked to [reverse engineer the glasses](https://github.com/edwatt/real_utilities/).\n","funding_links":["https://github.com/sponsors/wheaney","https://ko-fi.com/wheaney","https://ko-fi.com/U7U8OVC0L"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwheaney%2Fxrlinuxdriver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwheaney%2Fxrlinuxdriver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwheaney%2Fxrlinuxdriver/lists"}