clearpath_config

Clearpath Configuration YAML Parser

Find documentation on the Clearpath Configuration YAML and more about the Clearpath ROS 2 System on the Clearpath Documentation webpage.

Where this fits in the Clearpath ROS 2 stack

clearpath_config is the entry point of the Clearpath ROS 2 system. A single robot.yaml file describes an entire robot (platform, sensors, mounts, manipulators, and system settings). This package parses and validates that file into a Python object tree, which the Clearpath generators then turn into launch files, parameter files, and robot descriptions.

flowchart LR
    yaml["robot.yaml"] --> config["clearpath_config<br/>(this repo)<br/>YAML parser + validation"]
    config --> genc["clearpath_generator_common"]
    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<br/>control / description / diagnostics"]
    out --> robot["clearpath_robot<br/>real hardware"]
    out --> sim["clearpath_simulator<br/>Gazebo"]
    config -. "sample configs" .-> tests["clearpath_generator_tests<br/>validates generator output"]

Architecture

The top-level ClearpathConfig class loads the YAML and delegates each top-level key to a dedicated sub-config module. Every sub-config validates its own section and exposes typed accessors:

Shared plumbing (base classes, YAML read/write, type helpers) lives under clearpath_config/common/. Use read_yaml/write_yaml from common/utils/yaml.py rather than calling PyYAML directly, so ordering and formatting stay consistent with the generators.

Documentation

• Robot YAML overview — the user-facing reference for robot.yaml.
• Per-section references: serial number, system, platform, links, mounts, sensors.
• Generators — how the parsed config is turned into runtime files.

Configuration Examples

Under the sample folder there are example configurations that can be used as the starting point of your robot.yaml. Sample files whose names contain test (e.g. test_a300.yaml) are also the fixtures consumed by clearpath_generator_tests; adding or renaming one changes what CI validates.

Contributing

See CONTRIBUTING.md for how to set up your environment, run the linters and tests, and submit a pull request.

Contributing to clearpath_config

Thanks for your interest in improving clearpath_config! This package is the entry point of the Clearpath ROS 2 system: it parses and validates a robot’s robot.yaml into a typed Python object tree that the Clearpath generators consume. Because of that central role, changes here can ripple through the rest of the stack, 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. Install the pre-commit hooks (one-time setup):

   pip install pre-commit
   pre-commit install
   

Where things live

The top-level ClearpathConfig class delegates each top-level YAML key to a dedicated sub-config module (system, platform, links, manipulators, mounts, sensors). Shared plumbing (base classes, YAML read/write, type helpers) lives under clearpath_config/common/. See the Architecture section of the README for the full map.

A few conventions to keep in mind:

• Use read_yaml/write_yaml from common/utils/yaml.py rather than calling PyYAML directly, so ordering and formatting stay consistent with the generators.
• Each sub-config validates its own section and exposes typed accessors; keep new validation close to the section it belongs to.

Coding style

• Follow PEP 8; the CI enforces flake8 with a 100-character line limit.
• Docstrings and comments should follow pep257.
• Keep changes focused. Avoid unrelated refactors in the same pull request.

Linting and formatting

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

pre-commit run --all-files

Tests

Unit tests are written with PyTest following the Good Integration Practices. Every file to be tested has a corresponding file with the same name and the suffix _test.py.

Run the suite from the package root:

cd .../clearpath_config
python3 -m pytest

Please add or update tests for any behavior you change, and make sure the full suite passes before opening a pull request.

Sample configurations

The clearpath_config/sample/ folder holds example configurations. Sample files whose names contain test (e.g. test_a300.yaml) are the fixtures consumed by clearpath_generator_tests, so adding or renaming one changes what CI validates.

Generator tests

Changes to clearpath_config (config structure, defaults, or test samples) may affect the output of the Clearpath generators. The clearpath_generator_tests repository versions the expected generator 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

Two workflows run on every pull request:

• clearpath_config_ci — a ROS build/test (build_and_test against the released testing/main repos, plus a source_build of clearpath_config).
• Clearpath Config Python Package — flake8 linting and pytest.

clearpath_config sits at the root of the stack, so its own CI does not pull in upstream source

File truncated at 100 lines see the full file