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.

Submitting a pull request

1. Make sure the workspace builds and the simulation launches correctly.
2. Push your branch and open a pull request against jazzy.
3. Write a clear description of what the change does and the platform/world you tested against.
4. If your change touches generator output, note the matching clearpath_generator_tests branch.

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

File truncated at 100 lines see the full file