libsurvive_ros2

A Steam-free driver for republishing Lighthouse 1.0 and 2.0 pose and sensor data to ROS2

This is a lightweight ROS2 wrapper around the libsurvive project, which provides a set of drivers for 6DoF rigid body tracking using SteamVR 1.0 and 2.0 hardware. It also listens for inertial, button, configuration and device connection events, and forwards these to various topics.

This hardware is particularly useful to robotics projects, because it provides a cost effective method of obtaining ground truth with a positional accuracy typically in the sub-centimeter, sub-degree range. The final accuracy of course depends on the tracking volume, base station number and placement and level of occlusion, as well as calibration quality.

The driver in this repo is largely based on the ROS1 driver here. It has been migrated to ROS2, and refactored slightly – we use a thread to manage the blocking interaction with libsurvive, so that it doesn’t lock the ROS2 callback queue and prevent messages from propagating correctly.

When you build this code cmake will checkout and build the latest stable release of libsurvive and link against this library for you. This is to avoid having to discover it through pkg-config, and ensures that you are using a version that has been tested and is known to work well with ROS2.

Progress:

• code ported
• documentation added
• foxglove example
• test imu callback
• test connect callback
• fix timestamp errors
• fix button callback (only works on Tracker 2.0 wirelessly via watchman)
• add linting checks (nice to have)
• add unit tests
• fix composable node (not a functional blocker right now)
• convert to lifecycle node (nice to have)
• add circlce, mergify and dependebot integration

Installation instructions

This has only been tested on Ubuntu 22.04 and ROS Humble, although its fairly likely to work correctly with other distributions too. Pull requests are welcome if it does not!

Before you do anything, you will need to install these udev rules and reload the subsystem.

sudo curl -fsSL https://raw.githubusercontent.com/cntools/libsurvive/master/useful_files/81-vive.rules \
    -o /etc/udev/rules.d/81-vive.rules
sudo udevadm control --reload-rules && udevadm trigger

You can now choose to build the driver natively or in a container. The benefit of launching it within a container is that it won’t interfere with any pre-existing ROS installation on your machine. However, you will need docker-ce and the compose plugin for things to work.

Devcontainer build and test (easiest for development)

You can open this project as a Visual Studio Code Devcontainer. It will then prompt you for a target ROS distribution in the drop-down menu at the top of the IDE. When you select your desired distribution, the devcontainer engine will build a container for this ROS distribution, install our project dependencies, and compile the code. You can just open up a terminal and run:

ros@0d81683baf55:~/ros2_ws$ ros2 launch libsurvive_ros2 libsurvive_ros2.launch.py 
[INFO] [launch]: All log files can be found below /home/ros/.ros/log/2025-06-06-17-17-41-207302-0d81683baf55-2267
[INFO] [launch]: Default logging verbosity is set to INFO
[INFO] [libsurvive_ros2_node-1]: process started with pid [2304]
[libsurvive_ros2_node-1] Info: Loaded drivers: GlobalSceneSolver, HTCVive
[libsurvive_ros2_node-1] [INFO] [1749230261.309788197] [libsurvive.libsurvive_ros2_node]: Start listening for events..
[libsurvive_ros2_node-1] [INFO] [1749230261.309834518] [libsurvive.libsurvive_ros2_node]: Cleaning up.

Volume binding of the source tree happens with the correct permission. So, if you edit the source code in the container folder /home/ros/ros2_ws/src/libsurvive_ros2 your changes will propagate to your host folder, where you can eventually push them upstream. It is also possible to use git within the container, but this is more complicated and not recommended.

Containerized build and test (easiest and recommended)

Install docker and docker-compose: https://docs.docker.com/engine/install/ubuntu/

$ docker compose build
$ docker compose run libsurvive_ros2 colcon test

This will checkout a lightweight ROS2 rolling container, augment it with a few system dependencies, checkout and build the code and drop you into a bash shell as user ros at the home directory /home/ros/ros2_ws/src. If you’d rather build and test for ROS2 Foxy on arm64, as an example, you’d do this:

$ docker compose build --build-arg ARCH=arm64 --build-arg ROS_DISTRO=foxy
$ docker compose run libsurvive_ros2 colcon test  # optional, to test the package

Note that if you are building on a different architecture than the host you must follow the docker/QEMU installation instructions here before running the command above. Here is a link to a document outlining how this is done: https://docs.nvidia.com/datacenter/cloud-native/playground/x-arch.html

Native build and test (not recommended)

You’ll need ROS2 installed: https://docs.ros.org/en/humble/Installation.html

You’ll also need to follow the instructions here:

sudo apt-get install build-essential \
    cmake \
    freeglut3-dev \
    liblapacke-dev \
    libopenblas-dev \
    libpcap-dev \
    libusb-1.0-0-dev \
    libx11-dev \
    zlib1g-dev

Finally source ROS2, create a workspace, checkout, compile and test:

```sh $ mkdir ~/ros2_ws/src $ cd ~/ros2_ws/src $ git clone https://github.com/asymingt/libsurvive_ros2.git

File truncated at 100 lines see the full file