An experimental SteamVR driver that lets you control the Steam Frame's laser pointer with a regular mouse, across every VR overlay (Steam UI, the KDE desktop, the SteamVR dashboard, popups), instead of the mouse being trapped inside the desktop window.

The Frame's laser pointer is drawn by SteamVR's compositor. The compositor aims it with whatever tracked device supplies a pose, normally a controller. A physical mouse never reaches that system: gamescope consumes it and clamps it to whichever window has focus.

This driver adds a virtual controller to SteamVR:

• Position: follows your head.
• Direction: aimed by mouse movement.
• Buttons: your mouse buttons.

The compositor then treats it like any other laser-pointing hand.

When laser mode turns on, the ray starts where you're looking. When it's off, the virtual device reports itself as disconnected, so your real controllers keep the laser.

• A Steam Frame (aarch64, SteamOS VR variant) with SteamVR at /opt/steamvr.
• A USB or Bluetooth mouse. Your user must be able to read /dev/input/event*; the default steamos user is in the input group.
• gcc or clang, cmake and ninja. They are not guaranteed to be on a stock image; installing them may require disabling SteamOS read-only mode.
• The OpenVR driver header is not vendored. The build uses the copy SteamVR ships at /opt/steamvr/tools/hellovr_vulkan_linux/src/openvr/headers. Override it with -DOPENVR_HEADERS=<dir>.

cmake -S . -B build -G Ninja && cmake --build build
./install.sh      # registers driver/mouselaser with vrpathreg (backs up openvrpaths.vrpath first)
# then REBOOT the headset

install.sh refuses to run if another driver named mouselaser is already registered from a different folder.

Check that it loaded:

grep -a 'mouselaser:' ~/.local/share/Steam/logs/vrserver.txt | tail
# expect: "version 0.3.1-experimental", "activated as device N, role 1", "using /dev/input/eventX (<your mouse>)"

cmake -S . -B build -DMOUSELASER_TESTS=ON && cmake --build build && ./build/wheel_sim

This simulates the wheel → thumbstick logic at 120 Hz, without SteamVR, and exits non-zero if a single notch or a smooth spin misbehaves. It is handy when changing the wheel* defaults.

./uninstall.sh    # then reboot

Add any of these to ~/.config/openvr/config/steamvr.vrsettings under a "driver_mouselaser" section. They are read once, when SteamVR starts.

Tuning the wheel:

• One notch skips two list items: lower wheelSmoothHoldMs.
• Scrolling stops abruptly: raise wheelSmoothDecayMs.
• Fast spins aren't fast enough: raise wheelSmoothImpulse.

This is expected. SteamVR lists every driver that isn't resources-only under Settings → Developer → Manage Add-ons (exact menu names may differ). That entry is useful:

• Its toggle is a kill switch. It writes "driver_mouselaser": {"enable": false} to steamvr.vrsettings, which is the same enable setting the driver honours. Takes effect after a reboot.
• Safe mode. SteamVR can block add-ons in "safe mode", apparently when it crashes after they were added. The Unblock button on that page re-enables them, once you've fixed or updated the driver.

If SteamVR won't come up properly after installing, there are four options: 0. In VR, open Manage Add-ons, switch mouselaser off, then reboot.

1. SSH or RDP in (xrdp runs on the Frame), run ./uninstall.sh or vrpathreg removedriver <path>/driver/mouselaser, and reboot.
2. Set "driver_mouselaser": { "enable": false } in steamvr.vrsettings, then reboot.
3. Restore the backup: cp ~/.config/openvr/openvrpaths.vrpath.bak-mouselaser ~/.config/openvr/openvrpaths.vrpath.

• The ray starts just below your head (originOffsetY) and points where you aim, so you see the beam almost end-on. Expect to rely mostly on the cursor dot on overlays.
• If a real controller holds the same hand role its own laser pointer seems to stop working.
• Wheel feel is approximate. A wheel isn't a stick: it only sends notches. Smooth mode only simulates a held stick, so it still won't feel exactly like a real thumbstick. Tune it with the wheel* settings.
• Settings are only read when SteamVR starts.
• Two harmless log lines:
  • steam.client (mouselaser) has no configured binding: only the compositor bindings are provided, and Steam's own binding for the Frame controllers is haptics-only anyway.
  • Driver mouselaser has no suitable devices: logged at load time, presumably because the driver provides no HMD. The device is added right after.

• docs/how-it-works.md: the driver internals, the pose math and the bindings.
• docs/steam-frame-background.md: what we learned about the Frame's display and input stack that led here.
• docs/development-log.md: where this came from, what was verified, and what is next.
• CLAUDE.md: context and ground rules for AI coding sessions on this repo.

MIT © 2026 Andalu30 and contributors.

Third-party notes:

• OpenVR SDK header (openvr_driver.h, © Valve Corporation, BSD-3-Clause in the public OpenVR SDK). It is not included in this repo. The build uses the copy SteamVR ships on the headset.
• SteamVR is proprietary Valve software. This project doesn't contain or redistribute any of it. The input profile and bindings files follow SteamVR's documented JSON formats so the driver can interoperate.
• Not affiliated with or endorsed by Valve. "Steam", "SteamVR" and "Steam Frame" are trademarks of Valve Corporation.