clearpath_desktop

Packages for working with Clearpath platforms from a ROS 2 desktop / offboard computer — the operator’s workstation rather than the robot itself.

For supported platforms, sensors, and manipulators plus additional details, please see: https://docs.clearpathrobotics.com/docs/ros/

Where this fits in the Clearpath ROS 2 stack

The robot runs clearpath_robot (or clearpath_simulator) and publishes its topics over the network. clearpath_desktop runs on a separate computer on the same network to visualize, teleoperate, and consume high-bandwidth data from that robot. It reuses the same robot.yaml and clearpath_common descriptions so the desktop’s view matches the robot’s actual configuration.

flowchart LR
    robot["robot<br/>(clearpath_robot / clearpath_simulator)"] -- "ROS 2 network" --> desktop["clearpath_desktop<br/>(offboard workstation)"]
    desktop --> viz["RViz visualization<br/>(clearpath_viz)"]
    desktop --> live["live URDF<br/>(clearpath_config_live)"]
    desktop --> offboard["decompressed sensor data<br/>(clearpath_offboard_sensors)"]

Packages

Requirements

• A desktop with ROS 2 installed, on the same network as the robot.
• Matching ROS domain / middleware settings so the desktop can discover the robot’s topics.

Build

From your ROS 2 workspace root:

rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash

Notes

• These packages are meant to run off the robot. On-robot bringup lives in clearpath_robot.
• Discovery depends on network configuration (ROS domain ID, discovery server / middleware). If the desktop sees no topics, verify these match the robot’s system settings in robot.yaml.

Documentation

• Offboard PC setup — installing ROS 2 on the workstation.
• Visualizing with RViz2.
• Networking — connecting the desktop to the robot.

License

BSD. See LICENSE.

Contributing to clearpath_desktop

Thanks for your interest in improving clearpath_desktop! These packages run on a ROS 2 desktop / offboard computer — the operator’s workstation rather than the robot itself — to visualize, teleoperate, and consume data from a running Clearpath robot. Please read the notes below before opening a pull request.

Getting started

1. Fork the repository and clone your fork.
2. Create a feature branch off jazzy:

   git checkout -b my-feature jazzy
   

1. Build the workspace and source it:

   rosdep install --from-paths src --ignore-src -r -y
   colcon build --symlink-install
   source install/setup.bash
   

1. Install the pre-commit hooks (one-time setup):

   pip install pre-commit
   pre-commit install
   

Linting

This repository uses pre-commit to run linting and formatting checks (trailing whitespace, end-of-file, YAML/JSON checks, markdownlint, and flake8) before each commit. Run them against the whole tree before pushing:

pre-commit run --all-files

Where things live

See the Packages section of the README for the full map. In short:

• clearpath_viz — RViz visualization launchers.
• clearpath_config_live — live URDF updater that tracks the robot’s current config.
• clearpath_offboard_sensors — launch files for decompressing and consuming high-bandwidth sensor data offboard.

Keep changes in the package that matches the feature you are working on, and avoid unrelated refactors in the same pull request.

Testing your changes

Because these packages run off the robot, testing them requires a running robot or simulation on the same network. A quick way to validate changes is to launch clearpath_simulator and confirm the desktop tools discover and display its topics. If the desktop sees no topics, verify the ROS domain / middleware settings match the robot’s system settings in robot.yaml.

Build and run any package tests through colcon:

colcon build --symlink-install
colcon test --packages-select <package_name>
colcon test-result --verbose

Submitting a pull request

1. Make sure the workspace builds and any tests pass.
2. Push your branch and open a pull request against jazzy.
3. Write a clear description of what the change does and why. Link any related issues.
4. Note how you verified the change (e.g. against the simulator or a specific platform).

Reporting issues

Please open issues on the GitHub issue tracker and fill out the bug report template, which walks you through the details we need to reproduce the problem.

License

By contributing, you agree that your contributions will be licensed under the BSD-3-Clause license that covers this project.