NDI Optical Tracking Systems ROS2 Driver

This repository contains a ros2_control driver for Northern Digital Inc. (NDI) manufactured optical tracking systems. This driver is a streamlined and updated version of ICube-Robotics/ndisys_ros2. A comparison of this driver and ICube-Robotics' driver is shown below.

Feature	This driver	ICube-Robotics' driver
Compatible ROS2 distro	Jazzy (targets on Ubuntu 24.04)	Humble (targets on Ubuntu 22.04)
Data structure of trackers' pose	Uses the pose_broadcaster from ros2_controllers to publish trackers' pose in a standard ROS2 PoseStamped format	Implements a rigid pose broadcaster to publish trackers' pose in a self-defined format
ROS2 TF broadcasting	Supported via pose_broadcaster	Supported via self-implemented broadcaster
Shipped with NDI Combined API (C++)	Yes (v1.9.7)	Yes

Compatible devices

NDI optical tracking systems.

System requirements

ROS2 Jazzy on Linux (this driver is developed and tested on Ubuntu 24.04 LTS).

Packages in this repository

• ndi_bringup: This package contains the configuration files used to launch the driver (using polaris vega as an example). It serves not only as an entry point for the driver, but also as a reference for users to configure the driver for their own systems.
• ndi_description: This package contains the .rom file and ros2_control macros for describing the NDI optical tracking systems.
• ndi_hardware: This package contains the ros2_control hardware interface for NDI optical tracking systems. This package is built upon NDI's Combined API (C++) v1.9.7, which is shipped with this package at ndi_hardware/external.

Getting started

1. Clone this repository in your ros2 workspace. Taking ~/ndi_ros2_ws as an example:

   mkdir -p ~/ndi_ros2_ws/src
   cd ~/ndi_ros2_ws/src
   git clone https://github.com/zixingjiang/ndi_ros2_driver.git

   Currently, the pose_broadcaster package used by this driver and the new ros2_control features it depends on have not yet been synced to the ROS2 Jazzy release (probably in mid-November 2024), for now we have to them from source. To do this, you need to import the ros2_control and ros2_controllers packages into your workspace using the provided .repos file.

   vcs import . < ndi_ros2_driver/ndi_ros2_driver.jazzy.repos

   Since ros2_control is currently under active development, you may not be able to build it from the latest source code against the released ROS2 Jazzy package due to being out of sync. Therefore, it is recommended that you checkout ros2_control to version 4.19.0.

   cd ros2_control
   git checkout 4.19.0

2. Install dependencies.

   cd ~/ndi_ros2_ws
   rosdep update --rosdistro=$ROS_DISTRO
   sudo apt update
   rosdep install --from-paths ./ -i -y --rosdistro ${ROS_DISTRO}

   If you see pose_broadcaster-related error from ndi_bringup, don't worry. This is because the pose_broadcaster package is not yet in the ROS2 Jazzy release. We will build it from source in the next step.

3. Build pose_broadcaster.

   # build ros2_control packages from source
   colcon build --packages-select \
       controller_interface \
       controller_manager \
       controller_manager_msgs \
       hardware_interface \
       hardware_interface_testing \
       joint_limits \
       ros2_control \
       ros2_control_test_assets \
       ros2controlcli \
       rqt_controller_manager \
       transmission_interface 
   
   # install the ros2_control packages we just built
   # we will use them to build pose_broadcaster later
   source install/setup.bash
   
   # build pose_broadcaster
   colcon build --packages-select pose_broadcaster

4. Build and source the workspace. Now we can build and install the driver.

   colcon build --packages-select \
       ndi_bringup \
       ndi_description \
       ndi_hardware
   
   source install/setup.bash

5. Connect to NDI optical tracking system and bringup the driver. Connect the NDI system with your PC through Ethernet. The ndi_bringup package contains the launch file for a polaris vega system with two trackers loaded (tracker_1: 8700339.rom, tracker_2: 8700340.rom). You can start the driver with the following command. Remainder: you should replace <you_ndi_ip> with your setup.

   ros2 launch ndi_bringup polaris_vega.launch.py ip:=<your_ndi_ip> gui:=true

   By setting gui:=true you can start a Rviz visualization of the tracking data.

   

6. Access the data. After starting the driver with the above launch file, you can access the tracking data through the following two methods:

   1. ros2_control state interfaces. Taking tracker_1 as an example, its pose can be accessed in
      • tracker_1/position.x
      • tracker_1/position.y
      • tracker_1/position.z
      • tracker_1/orientation.x
      • tracker_1/orientation.y
      • tracker_1/orientation.z
      • tracker_1/orientation.w
   2. ROS2 topics. Taking tracker_1 as an example, its pose can be accessed in topic /tracker_1_pose_broadcaster/pose.

Use this driver in your own project

If you want to use this driver in your own project, it is recommended to take ndi_bringup as an example and write your own bringup package. You may find this guide helpful.

Acknowledgement

This driver is written with reference to ICube-Robotics/ndisys_ros2.