clearpath_robot

ROS 2 packages for interfacing with Clearpath Platforms (real hardware).

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

clearpath_robot is the on-robot half of the stack: it runs on the physical platform’s onboard computer, talks to the motor controllers and sensors, and brings the robot up as a set of systemd services. It consumes the description/control assets from clearpath_common and the files generated from robot.yaml.

flowchart LR
    yaml["robot.yaml"] --> config["clearpath_config"]
    config --> genr["clearpath_generator_robot<br/>(this repo)"]
    genr --> out["/etc/clearpath<br/>generated launch / params"]
    common["clearpath_common<br/>description + control"] --> bringup
    out --> bringup["systemd services<br/>(clearpath_robot)"]
    bringup --> hw["motor drivers + sensors<br/>(real hardware)"]

Packages

Runtime model

The robot boots via systemd. clearpath-robot.service is the top-level unit that generates the launch files (via clearpath_generator_robot) and starts the child services (platform, sensors, manipulators, discovery, …). The generated output and the source robot.yaml live in /etc/clearpath (the setup path). Useful commands on a robot:

sudo systemctl status clearpath-robot     # overall bringup status
sudo systemctl restart clearpath-robot    # regenerate + restart everything
journalctl -u clearpath-platform -f       # follow a single service's logs
ros2 run clearpath_robot generate         # regenerate launch/params from robot.yaml

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

• This package assumes it is running on the robot’s onboard computer with /etc/clearpath populated. For a desktop/offboard workflow use clearpath_desktop, and for Gazebo use clearpath_simulator.
• After editing robot.yaml, the generated files are stale until you regenerate (restarting clearpath-robot.service does this for you).

Documentation

• Robot installation & services — bringup and the systemd services.
• Generators — how robot.yaml becomes launch/param files.
• Driving / teleoperation and controller pairing.

Generator Tests

Changes to the generators in this repository (clearpath_generator_robot) may affect the generated output for launch files and parameter files. The clearpath_generator_tests repository versions the expected output and validates it through CI.

Before merging, ensure a corresponding branch with the same name exists in clearpath_generator_tests with regenerated samples. See the Development Workflow section of clearpath_generator_tests for the full process.

Contributing to clearpath_robot

Thanks for your interest in improving clearpath_robot! This is the on-robot half of the stack: it runs on the physical platform’s onboard computer, talks to the motor controllers and sensors, and brings the robot up as a set of systemd services. Because it drives real hardware, 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, flake8, and cspell spell-checking) 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:

• clearpath_robot — bringup scripts and the systemd services that start the robot on boot.
• clearpath_generator_robot — generates the robot-side launch and parameter files (builds on clearpath_generator_common).
• clearpath_hardware_interfaces and clearpath_motor_drivers — hardware and motor controller drivers.
• clearpath_sensors — default sensor launch/param files.
• clearpath_tests — on-robot hardware/functional test suite.

Testing your changes

Most of this repository interacts with real hardware and the systemd bringup, so validate changes on a robot where possible:

sudo systemctl restart clearpath-robot     # regenerate + restart everything
sudo systemctl status clearpath-robot      # overall bringup status
journalctl -u clearpath-platform -f        # follow a single service's logs
ros2 run clearpath_robot generate          # regenerate launch/params from robot.yaml

The clearpath_tests package provides an on-robot functional test suite — see its README. Build and run any package unit tests through colcon:

colcon test --packages-select <package_name>
colcon test-result --verbose

Be careful with changes that move the platform — ensure the area is clear and an e-stop is within reach.

Generator tests

Changes to the generators in this repository (clearpath_generator_robot) may affect the generated output for launch and parameter files. The clearpath_generator_tests repository versions the expected output and validates it through CI.

Before merging, ensure a corresponding branch with the same name exists in clearpath_generator_tests with regenerated samples. See the Development Workflow section of that repository for the full process.

Continuous integration

Every pull request runs clearpath_robot_ci. The jobs differ in whether they pick up upstream changes — commits on a branch with the same name as your branch in one of the repositories listed in dependencies.repos (for example clearpath_common or clearpath_config). The repos-dep-update-action swaps those matching branches in for the “Head Branch” jobs, so those are the jobs that reflect your upstream work.

File truncated at 100 lines see the full file