clearpath_simulator

clearpath_simulator is the simulation half of the stack. It mirrors clearpath_robot but targets Gazebo instead of real hardware, reusing the same robot.yaml, clearpath_config parser, and clearpath_common descriptions so a robot behaves the same in sim and on hardware.

flowchart LR
    yaml["robot.yaml"] --> config["clearpath_config"]
    config --> geng["clearpath_generator_gz<br/>(this repo)"]
    geng --> out["~/clearpath<br/>generated launch / params"]
    common["clearpath_common<br/>description + control"] --> gz
    out --> gz["clearpath_gz<br/>(this repo)"]
    gz --> sim["Gazebo simulation"]

• clearpath_generator_gz — generates the Gazebo launch and parameter files from the parsed config.
• clearpath_gz — simulation bringup, worlds, and assets (launched via simulation.launch.py).

Documentation

• Install the simulator and run a simulation.
• Navigation demos — Nav2 / SLAM on top of the simulated robot.
• Generators — how the simulation launch/param files are produced.

Setup

Prerequisites:

• Install ROS 2 Jazzy

Gazebo Harmonic

See Gazebo Installation for more information on installing Gazebo.

sudo apt-get install ros-${ROS_DISTRO}-ros-gz

Workspace

mkdir ~/clearpath_ws/src -p
cd ~/clearpath_ws/src
git clone https://github.com/clearpathrobotics/clearpath_simulator.git
cd ~/clearpath_ws
rosdep install -r --from-paths src -i -y
colcon build --symlink-install

Setup path

mkdir ~/clearpath

Copy your robot.yaml into ~/clearpath

Launch

ros2 launch clearpath_gz simulation.launch.py

Worlds

The clearpath_gz package includes several simulation worlds. To select a specific world, use the world launch parameter, e.g.

ros2 launch clearpath_gz simulation.launch.py world:=pipeline

Available worlds are:

Generator Tests

Changes to the generators in this repository (clearpath_generator_gz) 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.

Creating Map Tiles

File truncated at 100 lines see the full file

Contributing to clearpath_simulator

Thanks for your interest in improving clearpath_simulator! This is the simulation half of the stack: it mirrors clearpath_robot but targets Gazebo instead of real hardware, reusing the same robot.yaml, clearpath_config parser, and clearpath_common descriptions so a robot behaves the same in sim and on 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. Install ROS 2 Jazzy and Gazebo, then build the workspace:

   sudo apt-get install ros-${ROS_DISTRO}-ros-gz
   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

• clearpath_generator_gz — generates the Gazebo launch and parameter files from the parsed config.
• clearpath_gz — simulation bringup, worlds, and assets (launched via simulation.launch.py).

Testing your changes

Launch a simulation and confirm your change behaves as expected:

ros2 launch clearpath_gz simulation.launch.py

To test a specific world, use the world launch argument (see the Worlds section of the README for the full list):

ros2 launch clearpath_gz simulation.launch.py world:=pipeline

Build and run any package tests through colcon:

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

Generator tests

Changes to the generators in this repository (clearpath_generator_gz) 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_simulator_ci. The jobs differ in whether or not 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