Vicon receiver for ROS 2

ros2-vicon-receiver is a ROS 2 package, written in C++, that retrieves data from Vicon software and publishes it on ROS 2 topics. The code is partly derived from a mixture of Vicon-ROS2 and Vicon bridge.

This is NOT an official ROS 2 package, but it has been successfully tested with ROS 2 Jazzy Jalisco on the operating systems Ubuntu 24.04 Noble Numbat (with and without Docker) and macOS 26 Tahoe (with Docker).

Table of Contents

• Vicon receiver for ROS 2
  • Table of Contents
  • Requirements
  • What’s new in v1.0.0 (Jazzy)
    • Migration notes
  • Compatibility
  • Package layout \& executable
  • Quick start
    • Option A — VS Code Dev Container (recommended for development)
    • Option B — Manual build from source
  • Node interface
    • Launch arguments (convenience wrappers)
    • Node parameters (set with --ros-args -p name:=value)
    • Published topics
      • Naming scheme
      • Message types
      • Notes
      • QoS
      • Example topic tree
  • Frames \& mapping
    • TF tree (template + notes)
      • Static transform (map → vicon)
      • Dynamic transforms
      • Tips
  • Example images
    • TF2 frame tree
    • RViz: TF and Pose (template)
  • Building \& linking details
  • Troubleshooting / FAQ
  • License \& attribution
  • Contributing

Requirements

• Vicon Tracker running on another machine, with DataStream enabled and reachable over the network (hostname/IP).
• Choose one setup path:
  • VS Code Dev Container:
    • Docker Engine (install guide)
    • Visual Studio Code + Dev Containers extension (Dev Container starting guide)
  • Manual build (on host):
    • ROS 2 Jazzy Jalisco installed and sourced (at least ros-jazzy-ros-base and ros-dev-tools packages, installation guide)
    • rosdep initialized and updated for managing ROS 2 package dependencies (installation guide)
    • common build tools: cmake, gcc, build-essential, python3 (on Ubuntu 24.04, a Python 3 virtual environment is recommended)
    • git package for cloning the repository

Note: you do not need system-wide Boost or the Vicon DataStream SDK; both are vendored per-architecture inside this repository.

What’s new in v1.0.0 (Jazzy)

• ROS 2 Jazzy compatibility
• TF publishing: TF information for tracked subjects is now available
• BREAKING: switched output from a custom message to geometry_msgs/msg/PoseStamped

Migration notes

• Update your subscribers to consume geometry_msgs/msg/PoseStamped instead of the legacy custom message.

Compatibility

• ROS 2: Jazzy
• OS / arch: Ubuntu 24.04; x86_64 and ARM64 tested
• Vicon stack: Vicon Tracker; Vicon DataStream SDK 1.12
• SDK & Boost: vendored per‑arch inside this repo (no system install needed)

Package layout & executable

• Package name: vicon_receiver
• Primary executable: vicon_client (C++)
• Launch file: client.launch.py

Quick start

Option A — VS Code Dev Container (recommended for development)

1. Open the repo in VS Code.
2. When prompted, Reopen in Container. The first time this may take a while as the container image is built.

   If the prompt does not appear, try opening the Command Palette (Ctrl+Shift+P) and selecting “Dev Containers: Rebuild and Reopen in Container”.

3. The container will install dependencies and build the workspace automatically.

   Important: Inside the Dev Container, use the ROS 2 shell aliases defined in ~/.bashrc. For builds, use ros2-build so the correct Python virtual environment and libraries are used (prefer this over calling colcon build directly).

File truncated at 100 lines see the full file