clearpath_common

ROS 2 common packages for Clearpath Robotics platforms.

This repository provides the core platform bringup, control, diagnostics, robot description assets, and generator utilities used across Clearpath robotic platforms.

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_common holds the platform-agnostic building blocks shared by both real robots (clearpath_robot) and simulation (clearpath_simulator): the URDF descriptions, controllers, diagnostics, and — importantly — the common generator that turns a parsed robot.yaml into launch/description output.

flowchart LR
    yaml["robot.yaml"] --> config["clearpath_config<br/>YAML parser"]
    config --> genc["clearpath_generator_common<br/>(this repo)"]
    config --> genr["clearpath_generator_robot"]
    config --> geng["clearpath_generator_gz"]
    genc --> out["/etc/clearpath<br/>generated launch / params / description"]
    genr --> out
    geng --> out
    out --> common["clearpath_common description + control<br/>(this repo)"]
    out --> robot["clearpath_robot"]
    out --> sim["clearpath_simulator"]
    genc -. "expected output" .-> tests["clearpath_generator_tests"]

clearpath_generator_common is the shared generator base: clearpath_generator_robot and clearpath_generator_gz build on it. Its generators and templates live under clearpath_generator_common/clearpath_generator_common and produce bash environment setup, robot description (URDF/xacro), the discovery server config, and the manipulator SRDF.

Packages

• clearpath_common: Metapackage for core common stack.
• clearpath_bt_joy: Bluetooth joystick watchdog. Monitors HID report-rate on /dev/hidrawN and publishes a stop flag when link quality drops below threshold. Only for PS5 at the moment.
• clearpath_control: Platform controllers, localization, and teleoperation launch files.
• clearpath_customization: Templates and generators for project bringup/description customization.
• clearpath_description: Clearpath URDF descriptions metapackage.
• clearpath_diagnostics: Diagnostic updater and aggregator launch/config.
• clearpath_generator_common: Common Python generator utilities and templates.
• clearpath_manipulators: Manipulator integration package.
• clearpath_manipulators_description: Manipulator description assets.
• clearpath_mounts_description: Mount description assets.
• clearpath_platform_description: Common platform meshes, URDF, and description launch.
• clearpath_sensors_description: Sensor description assets.

Requirements

• Ubuntu with ROS 2 installed.
• colcon and standard ROS 2 build tools.
• A robot setup directory at /etc/clearpath (or a custom setup_path) for runtime configuration files. For more details, see docs.clearpathrobotics.com.

Build

From your ROS 2 workspace root:

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

Generator Tests

Changes to the generators in this repository (clearpath_generator_common) may affect the generated output for launch files, parameter files, and descriptions. 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.

Documentation

• Generators — how clearpath_generator_common turns robot.yaml into bash/description/launch/param files.
• Robot YAML overview — the input configuration format.
• Clearpath ROS 2 documentation — full platform documentation.

License

BSD. See LICENSE.

Contributing to clearpath_common

Thanks for your interest in improving clearpath_common! This repository holds the platform-agnostic building blocks shared by both real robots (clearpath_robot) and simulation (clearpath_simulator): URDF descriptions, controllers, diagnostics, and the common generator (clearpath_generator_common) that turns a parsed robot.yaml into launch/description output. Because these packages sit at the center of the stack, changes here can ripple through the rest of the system, so 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

This repository is a collection of packages (see the Packages section of the README). A few of the most commonly touched:

• clearpath_generator_common — the shared generator base that clearpath_generator_robot and clearpath_generator_gz build on. Its generators and templates produce bash setup, robot description (URDF/xacro), the discovery server config, and the manipulator SRDF.
• clearpath_description, clearpath_platform_description, and the other *_description packages — URDF/xacro and mesh assets.
• clearpath_control — controllers, localization, and teleoperation launch.
• clearpath_diagnostics — diagnostic updater and aggregator.

Keep changes in the package that matches the layer they belong to, and avoid unrelated refactors in the same pull request.

Coding style

• Python: follow PEP 8 with a 100-character line limit.
• Keep changes focused and scoped to the package you are modifying.

Tests

Build and run the tests through colcon:

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

Please add or update tests for any behavior you change.

Generator tests

Changes to the generators in this repository (clearpath_generator_common) may affect the generated output for launch files, parameter files, and descriptions. 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.

Submitting a pull request

1. Make sure the workspace builds and colcon test passes.
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. If your change touches generator output, note the matching clearpath_generator_tests branch in the pull request description.

Reporting issues

File truncated at 100 lines see the full file