Vive wrist preview and recording setup on Ubuntu

Updated: 2026-09-17

This guide connects a Lighthouse-based Vive tracker to the actuator-free vive-preview position/orientation display and vive-record trajectory UI. Run SteamVR and the tool on the same computer and under the same desktop user account.

Back to the Tianji guide

#Command Table

Focus the vive-preview window to use these shortcuts. If a teleoperation dataflow is also running, its global c binding will also request shutdown when you press C to clear the preview trail.

#What is needed

• A charged Vive tracker and its USB dongle.
• Powered, compatible Lighthouse base stations with a clear view of the tracker.
• Native Steam and SteamVR installed on Ubuntu.
• A desktop session for the preview window; --headless prints poses instead.

The USB receiver alone does not compute the tracker position. SteamVR supplies poses to OpenVR, which the preview reads. The Python OpenVR package is already managed by this project's uv environment.

For Tracker 3.0, HTC lists SteamVR Base Station 1.0 and 2.0 compatibility in its hardware specifications.

#Install Steam and SteamVR

Use Valve's native Ubuntu .deb from the Steam download page. Valve recommends this package for Ubuntu SteamVR; its Linux support guide explains graphics driver and desktop requirements. Use an X11 desktop session if the SteamVR display cannot start under GNOME Wayland.

On this computer, the installer was downloaded to /home/weison/Downloads/steam_latest.deb (Steam launcher 1.0.0.87, amd64). To install it and enable Steam's 32-bit dependencies:

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install ~/Downloads/steam_latest.deb
steam

Let Steam finish updating and sign in through the Steam window. In Library, enable the Tools filter, find SteamVR, and install it. Launch SteamVR once to create its runtime registration and configuration files. Keep it running when using the preview. The launcher includes Valve's USB access rules; see the official package description.

The preview uses OpenVR's background application mode, which requires an already-running VR service; it does not start SteamVR itself. See Valve's OpenVR API documentation.

#Use a tracker without a headset

If you have a headset, use the normal SteamVR setup. For tracker-only operation, start with the configuration from ~/robot_api/vive/README.md below. This recipe still needs verification against the SteamVR version installed on this computer; a null headset supplies the headset component while Lighthouse supplies the real tracker poses.

Exit SteamVR before editing its settings. The usual native installation uses ~/.local/share/Steam/config/steamvr.vrsettings; another Steam library location may differ. The config entry in ~/.config/openvr/openvrpaths.vrpath identifies the registered configuration directory.

Back up the existing steamvr.vrsettings file, then merge these keys into its existing JSON. Preserve unrelated keys and avoid duplicate sections.

{
  "driver_null": {
    "enable": true,
    "displayFrequency": 60,
    "renderHeight": 1512,
    "renderWidth": 1344,
    "windowHeight": 1080,
    "windowWidth": 1920
  },
  "steamvr": {
    "activateMultipleDrivers": true,
    "enableHomeApp": false,
    "forcedDriver": "",
    "requireHmd": false
  },
  "power": {
    "pauseCompositorOnStandby": false
  }
}

Restart SteamVR after saving. Valve documents enabling driver_null and requireHmd: false for headset-free setups in its driver example. These settings do not produce synthetic tracker measurements.

#Pair the tracker

1. Plug the tracker dongle into this computer and power the base stations.
2. In SteamVR, open Devices → Pair Controller. Choose HTC Vive Tracker; use I want to pair a different type of controller if necessary.
3. For Vive Tracker 3.0, hold its power button for about two seconds until its light blinks blue. Wait for green, indicating successful pairing.
4. Move the tracker where its sensors can see the base stations.

HTC provides a pairing tutorial and a support page with a pairing video. Button behavior can differ with tracker models; use the matching model's guide.

#Check and preview real poses

From the repository, with SteamVR still running:

cd /home/weison/dynamic-mani
uv sync --locked
uv run vive-preview --list
uv run vive-preview --headless --duration 5
uv run vive-preview
# Same display with a one-take recorder armed:
uv run vive-record

The list should show the tracker serial with connected=True and pose_valid=True. The terminal check should show "tracking": true with numeric position_m and quaternion_xyzw arrays. To select a particular tracker, pass --serial with its serial from --list.

The window shows position, orientation, coloured axes, and a movement trail. R recenters the displayed position, C clears the trail, and Q closes it. The preview uses the shared Z-up teleoperation frame, metres, and xyzw quaternions. Its coordinates come from SteamVR's standing tracking universe; recentering the view does not calibrate SteamVR's room origin or floor height. No robot drivers start. In vive-record, press Space to begin and again to stop. The overlay shows recording state, captured pose count, and destination. Closing while actively recording also saves when at least two valid poses were captured. The resulting directory is accepted directly by the UR5e replay pipeline:

uv run dmani --robot ur5e --replay out/vive-recordings/<take>

Always preview a take in simulation before using the dummy or hardware sink. Replay sends the recorded wrist poses through the normal mapper and IK; it does not play recorded arm joints.

#Align Vive motion with the robot

Vive's raw OpenVR frame has +Y up and -Z forward; see Valve's coordinate convention. The tracker adapter converts this to the shared right-handed bus frame:

vive-preview displays this bus frame, including a canonical wrist triad whose local axes use the same convention. The bright moving triad shows wrist orientation; the dim fixed triad shows world axes. Its readout is not raw OpenVR coordinates or robot-base coordinates.

The mapper uses movement relative to engagement: wrist translation in the bus world frame and wrist rotation about those same world axes. The idle end-effector orientation and the way the tracker is mounted do not change which direction the robot moves. Engaging or resuming pins the pose without changing the movement axes.

Z-up conversion alone cannot know the room's heading relative to the robot. Run uv run calibrate to select a live pose matching the displayed default pose: Space captures, Enter saves. For Tianji, add --config configs/tianji.yml --side right. See the live heading calibration guide for the forward-axis selection and motion preview. This saves the fixed alignment in the existing teleop section of the rig YAML (configs/ur5e_wuji.yml or configs/tianji.yml):

teleop:
  ramp_time_sec: 1.0
  pos_scale: 1.0
  wrist_to_robot_rpy_deg: [0.0, 0.0, 0.0]

These are extrinsic roll, pitch, yaw in degrees: rotate about fixed X, then Y, then Z. The rotation maps bus vectors into ik.base_link and applies to both translation and rotation. The default assumes their axes already agree. For example, [0, 0, 90] maps bus +X to robot +Y, bus +Y to robot -X, and leaves upward motion unchanged. Both Tianji arms share this base alignment.

Check the alignment in simulation by moving along each fixed preview axis and comparing the target motion with the robot base axes. Adjust yaw if the horizontal directions differ; use the calibration program to capture a new reference. Normal engagement does not recalibrate heading. Restart the dataflow after editing the rig YAML. The preview's R key only recenters its display.

#Troubleshooting by stage

Runtime initialization errors exit with status 2 before opening a window or printing pose records. A missing tracker is retried while the preview is open. A bounded terminal run also exits with status 2 if no valid poses arrive.

uv run vive-preview --demo checks only the viewer with explicitly labelled synthetic motion; it does not verify hardware tracking.