Frametop 0.3.0-exp.7

Install

On a Steam Frame (SteamOS, VR variant). Download Frametop.zip below (about 1.1 GB), then either:

• With FrameDrop on a PC: drop Frametop.zip on your paired headset. In the headset, open Frametop in your library and press Play.
• On the headset: unpack Frametop.zip (in the desktop's Dolphin or Konsole) and run Frametop/frametop-install.sh.
• In a terminal on the headset: curl -fsSL https://frametop.github.io/frametop/get.sh | bash -s -- --release --experimental

A window asks what to install, and your SteamOS password for the two optional parts that need it (our own eye tracker and the Bluetooth fixes); the password is only used for this install. Nothing is compiled on the headset. Restart SteamVR once afterwards.

Before installing, the installer checks your SteamOS build against the builds Frametop was tested on, and stops if this release is known not to work there.

Full Changelog: v0.3.0-exp.6...v0.3.0-exp.7

Frametop 0.3.0-exp.6

What's new

• Better problem reports. scripts/report.sh (in ~/.local/share/frametop/releases/current for a release install) now covers Frametop's keyboard and the Steam menu: the Keyboard setting, the keyboards Frametop sees, whether the desktop's apps can ask for the keyboard, and which SteamVR panels are showing.
• scripts/report.sh --watch records for 60 seconds while you make a problem happen in the headset, like a window that won't drag or a keyboard that doesn't open: when the Steam menu opens and closes, which laser drags what, where typing goes, and when Frametop's keyboard opens or why it doesn't.
• The desktop and the input relay log those moments too, so a report made afterwards still shows them.
• The report now shows a release's version and container, and the SteamVR version that's running.

Install

On a Steam Frame (SteamOS, VR variant). Download Frametop.zip below (about 1.1 GB), then either:

• With FrameDrop on a PC: drop Frametop.zip on your paired headset. In the headset, open Frametop in your library and press Play.
• On the headset: unpack Frametop.zip (in the desktop's Dolphin or Konsole) and run Frametop/frametop-install.sh.
• In a terminal on the headset: curl -fsSL https://frametop.github.io/frametop/get.sh | bash -s -- --release --experimental

A window asks what to install, and your SteamOS password for the two optional parts that need it (our own eye tracker and the Bluetooth fixes); the password is only used for this install. Nothing is compiled on the headset. Restart SteamVR once afterwards.

Before installing, the installer checks your SteamOS build against the builds Frametop was tested on, and stops if this release is known not to work there.

Full Changelog: v0.3.0-exp.5...v0.3.0-exp.6

Frametop 0.3.0-exp.5

What's new

• SteamOS 0.4.5 is on the tested list (with SteamVR 2.18.2), so the installer no longer asks before it installs there.
• scripts/doctor.sh no longer reports FAIL container dev in a release. It checks the release's own container now.
• Remote displays: the PC setup (host/windows) downloads Frametop's Vibepollo build from its release, and upgrades an earlier one.

Everything from 0.3.0-exp.4 is in here too: the fixes for SteamOS 0.4.5 (the Bluetooth fixes and our eye tracker kept through SteamOS updates, Track Dominant Eye Only, no second Steam start in the desktop).

Install

On a Steam Frame (SteamOS, VR variant). Download Frametop.zip below (about 1.1 GB), then either:

• With FrameDrop on a PC: drop Frametop.zip on your paired headset. In the headset, open Frametop in your library and press Play.
• On the headset: unpack Frametop.zip (in the desktop's Dolphin or Konsole) and run Frametop/frametop-install.sh.
• In a terminal on the headset: curl -fsSL https://frametop.github.io/frametop/get.sh | bash -s -- --release --experimental

A window asks what to install, and your SteamOS password for the two optional parts that need it (our own eye tracker and the Bluetooth fixes); the password is only used for this install. Nothing is compiled on the headset. Restart SteamVR once afterwards.

Before installing, the installer checks your SteamOS build against the builds Frametop was tested on, and stops if this release is known not to work there.

Full Changelog: v0.3.0-exp.4...v0.3.0-exp.5

Frametop 0.2.2

Install

On a Steam Frame (SteamOS, VR variant). Download Frametop.zip below (about 1.1 GB), then either:

• With FrameDrop on a PC: drop Frametop.zip on your paired headset. In the headset, open Frametop in your library and press Play.
• On the headset: unpack Frametop.zip (in the desktop's Dolphin or Konsole) and run Frametop/frametop-install.sh.
• In a terminal on the headset: curl -fsSL https://frametop.github.io/frametop/get.sh | bash -s -- --release

A window asks what to install, and your SteamOS password for the two optional parts that need it (our own eye tracker and the Bluetooth fixes); the password is only used for this install. Nothing is compiled on the headset. Restart SteamVR once afterwards.

Before installing, the installer checks your SteamOS build against the builds Frametop was tested on, and stops if this release is known not to work there.

What's Changed

• Gaze: detect the eye-server.mmap layout at runtime (fixes eye tracking on SteamOS beta) by @0x1f6 in #26
• Uninstalls clear ft-camd's file capabilities by @0x1f6 in #30
• vnc-bridge: create the credentials directory before writing the password by @0x1f6 in #31
• fix-panels: the backup keeps the config as it was before the first repair by @0x1f6 in #32
• Input relay: standing down releases the driver buttons the pointer holds by @0x1f6 in #33
• ft-screens: ft-layout's log goes to the runtime directory, not /tmp by @0x1f6 in #34
• frametop-float: a watchdog re-arms the command poll after a lost reply by @0x1f6 in #35
• desktops: Copy Steam's nested desktop as native desktop by @SuperTuxii in #40
• input: Allow sending keys >= BTN_MISC and allow sending keys from nodes with volume role by @SuperTuxii in #41
• sync: create the Frame's repo dir before the first rsync by @dkiiv in #45
• ft-screens: Make the hit area of each control equal to its texture size by @SaberMage in #46

New Contributors

• @0x1f6 made their first contribution in #26
• @SuperTuxii made their first contribution in #40
• @dkiiv made their first contribution in #45
• @SaberMage made their first contribution in #46

Full Changelog: v0.2.1...v0.2.2

Frametop 0.2.1

Frametop 0.2.1 pauses itself while you play VR games, adds new shortcuts and a one-command uninstaller, and makes our own eye tracker the default for gaze mode. It also brings the Hand Recorder, which records your hands for Frametop's open hand dataset.

New

• Pause for VR games. Frametop pauses while a VR game runs, so the game gets the headset's CPU and GPU, and it comes back a few seconds after the game ends. While paused, the screens hide and the desktop nearly stops drawing, but its windows stay open. Click both thumbsticks together twice to pause or resume it yourself, in a game or not. The new Game optimization page of Frametop Input Settings has the settings (#19).
• Tap Meta for the Steam menu. Tapping Meta on any keyboard opens the Steam menu in the SteamVR dashboard, or closes the dashboard. In Frametop Input Settings (Keyboard page), any key combination or modifier tap can now run a Frametop or Steam action, open a profile, or run a command of your own.
• Lazy susan. Meta+Alt+Tab (or Meta+Alt+Shift+Tab) spins every screen and floating window around you together, so the next one glides to straight ahead (#22, thanks @ehippy).
• A reset button next to each screen's grab bar. It puts every screen back in its layout around you, like Meta+Shift+R, and a controller can click it during VR games.
• The keyboard's Mute key mutes the headset's sound (#24, thanks @SuperTuxii).
• A one-command uninstaller: curl -fsSL https://deejanuz.github.io/frametop/uninstall.sh | bash. It works in two steps around a restart, so it never takes away the keyboard, mouse, or desktop you're using while it runs. See Uninstall.
• The Hand Recorder records your hands with the headset's tracking cameras for Frametop's open hand dataset on Hugging Face. It's installed separately; see Install the Frametop Hand Recorder. It works on headsets with or without the Arcturus color passthrough module.
• Accessibility in the desktop. The desktop starts its own accessibility (AT-SPI) registry, so apps show up on its accessibility bus (#27, #28, thanks @JakeGreen2145).

Gaze mode (experimental)

• The installer now offers our own eye tracker as well, and by default gaze mode uses it whenever it's installed. It's more accurate than SteamVR's.
• A fresh install with our eye tracker can now take its first calibration. Before, it could never be calibrated, so gaze mode didn't work.
• The Gaze page says why gaze mode can't work yet, and the calibration opens by itself whenever it's missing. When a calibration dot isn't taken, the panel says why.
• The gaze service idles while gaze mode isn't in use, and it leaves SteamVR's eye tracking alone during VR games, where reading it made some games pause (reported in #13, thanks @curiousjtuber).

Smoother and lighter

• Scrolling and video in the desktop no longer judder. The screens now update once per display frame, in step with the headset's display, and hidden screens update once a second.
• The desktop has no blur or window animations by default, which leaves the GPU to SteamVR. You can turn them back on in the Frametop desktop's System Settings.
• Remote desktop uses much less CPU while no VNC viewer is connected.
• The eye tracker, the pointer, and the input relay use less CPU. The desktop no longer starts Discover's update notifier or IBus.

Fixes

• A taskbar saved on a screen the desktop no longer has comes back on the primary screen (#18).
• The installer works over SSH: it waits for a new build container to finish setting up (#9).
• Small controller movements no longer turn desktop clicks into drags (from #11, thanks @jlneal).
• A newly connected keyboard or mouse is picked up even when it takes a moment to become usable (#12), and a memory bug in how the screens catch the controller laser is fixed (#14). Thanks @curiousjtuber.
• Launching a missing app no longer breaks floating windows (#16, thanks @ehippy).
• Hide/Show Screens in the launcher no longer runs Reset Screen Layout (from #17, thanks @JRMurr).
• Profiles bring back Flatpak apps whose windows name a different app id.
• A controller button pressed on a screen no longer stays held when pausing or hiding the screen takes the laser away mid-click.
• Typing with SteamVR off no longer stops the input relay.
• SteamVR's tools (vrcmd, vrpathreg) and OpenVR apps work from a terminal in the Frametop desktop.
• scripts/report.sh now includes the gaze service, our eye tracker, and the desktop's panels and outputs. scripts/doctor.sh flags a lost taskbar.

Known limitations

• Frametop doesn't work on the SteamOS beta (0.4.3) yet: gaze mode can't read the eye tracker there, and the desktop has started without its taskbar (#15). Use the stable SteamOS release.
• Hand tracking (hands shown over the screens, pinch to click) is still deferred, and the installer doesn't offer it. The Hand Recorder only records for the dataset.

Update

curl -fsSL https://deejanuz.github.io/frametop/get.sh | bash

Tested on one Steam Frame (SteamOS 0.3.0 build 20260922, SteamVR 2.17.10). See the known limitations. If something goes wrong, run scripts/report.sh and open an issue. Questions and help: the Frametop Discord.

Frametop 0.2.0

Frametop 0.2.0 lets app windows float on their own, adds profiles that bring back your screens and apps, and installs with one command. It also offers gaze mode at install, with its calibration in the headset, and can turn the displays off when the headset isn't used.

New

• Floating windows. Any desktop window can float in VR as a panel of its own: press Meta+Shift+F, click the float button in its title bar, or pick Launch as Standalone in an app's right-click menu. The window stays part of the desktop, so drag and drop, the clipboard, the taskbar, and Alt+Tab keep working. Meta+scroll scales it, and an app floats where it floated last.
• Profiles. A profile saves where the screens are, which ones show, and which apps are open where. Opening one moves the screens, puts open windows in place, and starts the apps that aren't open. Nothing closes. The desktop can start in a profile, each profile has a launcher entry, and a profile can go on a key or a button.
• Hide screens one at a time (Frametop Display Settings, Visibility & pins). New windows that would open on a hidden screen float instead.
• Pin a screen to your head, like a HUD.
• Displays off when the headset isn't used, even on a stand that covers its proximity sensor, and the headset stays awake on the charger (Frametop Display Settings, Power).
• Frametop Remote Access, an app that turns the VNC view on and off and shows or changes its password. The VNC view shows the primary screen.
• A keyboard for text fields. Frametop's on-screen keyboard opens when you select a text field and no keyboard is connected (Frametop Input Settings, Keyboard).
• Ignored panels. The pointer passes through panels you pick, such as a performance overlay that follows your view.
• One-line install and update: curl -fsSL https://deejanuz.github.io/frametop/get.sh | bash. It asks for stable or experimental, and running it again updates.
• scripts/doctor.sh checks what Frametop needs from SteamOS after an update.

Gaze mode (experimental)

The installer now offers it, and it stays off until you turn it on on the Gaze page of Frametop Input Settings.

• Meta+J and Meta+K click where you look. Hold one and turn your head to correct the aim; held still, it drags.
• By default the mouse only corrects. Its buttons work like Meta+J and Meta+K. A double right click, or a double Meta+K, pans and tilts what you're dragging.
• Calibration runs in a panel fixed to the headset. A quick check runs when you put the headset on, Calibrate asks you to click on each dot, and Check headset fit shows how well the tracker sees your eyes.
• Each correction teaches the tracker, up to 55 degrees. A bigger correction starts a quick check.
• Our own eye tracker can replace SteamVR's (installed separately; see gaze/README.md).
• Gaze clicks on the Frame controllers were tried and dropped (why).

Fixes

• Keys the desktop holds that no keyboard holds are released within about a second. A stuck Meta key used to make typing open the overview.
• Frametop's SteamVR clients start only once SteamVR is up (#6, thanks @utrack).
• The input relay survives a malformed control message, a rows setting that the screens can't fill gets a working layout, and the volume keys try every key when one swap fails (from #8, thanks @0x1f6).
• Clicks land where the cursor is on scaled desktop screens.
• Resting controllers no longer take the laser from the mouse.
• Flatpak apps can save and upload files in the desktop.
• Frametop Input Settings warns when SteamVR hasn't loaded the pointer driver.
• Installer: the Bluetooth fixes' password prompt works during the install, services that need SteamVR wait for it, and the uninstall removes everything Frametop put in place.

Not in this release

Hand tracking (hands shown over the screens, pinch to click) is in the repo but deferred: it uses a lot of the headset's CPU and needs more work. The installer doesn't offer it.

Update

curl -fsSL https://deejanuz.github.io/frametop/get.sh | bash

Tested on one Steam Frame (SteamOS 0.3.0 build 20260922, SteamVR 2.17.10). See the known limitations. If something goes wrong, run scripts/report.sh and open an issue.

Frametop 0.1.1

Frametop 0.1.1 fixes typing and the volume keys, lines the desktop up with the screens around you, and adds mapping for the Frame controllers' buttons. It also brings two experimental pointer modes, head follow and gaze, which are off by default.

Changes

• Typing follows your last click. A keyboard used to type into the desktop and into the Steam app with focus at the same time, so a space typed on the desktop could pause music playing on the dashboard. Now keys go only to what you clicked last, the screens or a Steam panel.
• The volume keys can't end the VR session. A volume press with nothing focused could crash gamescope. Frametop now handles the volume keys of the headset and of keyboards itself, in 5% steps on the default output.
• Keys don't stick when the dashboard opens. A key held as the SteamVR dashboard opens is now released on the desktop too.
• The desktop is arranged like the screens. KWin's outputs follow where the screens sit around you, so the mouse pointer and dragged windows cross to the screen you see next to the one you're on.
• Frame controller buttons. Frametop Input Settings has a new Controllers page for mapping the Frame controllers' buttons to actions. It also has a Global input switch for the SteamVR setting that mapped buttons need.
• The 3D mouse reaches all of SteamVR's Settings page. It used to miss most of that page. On that page only, it now shows a laser beam and a larger hit dot.
• A screen's controls show when a laser lands on them, and they stay with the screen when the layout moves it.
• Controller rays aim along the laser instead of along the controller.
• A mouse or keyboard that reconnects between device scans is picked up.
• The Meta tap shortcut for the dashboard is off by default.
• Installer fixes: the desktop starts without the Steam client's environment, the build container setup works on the headset, and reinstalling leaves an unchanged SteamVR driver in place.

Experimental, off by default

• Head follow. The pointer comes along when you turn your head. Turn it on with POINTER_FOLLOW=1, or map a mouse button to Head follow on/off. It's only lightly tested.
• Gaze. The pointer goes where you look, and the mouse does the last bit. It uses the Frame's eye tracking. It isn't installed with the rest of Frametop; see gaze/README.md to set it up.

docs/hazards.md lists the ways the input changes could go wrong and what to check. Tools that watch every keyboard for a hotkey stop seeing a keyboard while it types into the desktop. SHARE_KEYS=1 passes its keys on to them. This is off by default, because any local program could read those keys.

Update

cd ~/frametop && git pull && ./install.sh

Tested on one Steam Frame (SteamOS 0.3.0 build 20260922, SteamVR 2.17.10). See the known limitations. If something goes wrong, run scripts/report.sh and open an issue.

Frametop 0.1.0

The first release of Frametop, a multi-monitor desktop and 3D mouse for the Valve Steam Frame.

Frametop puts a KDE Plasma desktop with several screens into SteamVR. Each screen is its own monitor with its own resolution, so an ultrawide can sit between two portrait screens at whatever size and distance you like. You can move, resize, curve, and roll the screens, pin one to your wrist, and put them all back with a shortcut. During a VR game they hide unless the SteamVR dashboard is open (or stay up, if you prefer), and your controllers stay in the game.

A Bluetooth mouse drives all of SteamVR as a small dot anchored in the room, and hands the laser back to your controllers when you pick one up. Two settings apps, Frametop Display Settings and Frametop Input Settings, cover the screens and the input devices, and the Bluetooth fixes let LE mice and keyboards like the Swiftpoint Z3 reconnect after they sleep.

To install, follow the README. This is an early release, tested on one Steam Frame (SteamOS 0.3.0 build 20260922, SteamVR 2.17.10); see the known limitations. If something goes wrong, run scripts/report.sh and open an issue.