Getting Started

First, clone this repo including submodules.

git clone --recursive https://github.com/open-planning/roboplan-ros.git
cd roboplan-ros

—

Pre-built

RoboPlan ROS will soon be installable from pre-packaged binaries. For now, users should build from source using one of the methods below.

Compiling

We support a handful of methods for building the ROS 2 wrappers from source.

Pixi

For isolated development work we recommend the Pixi package management tool. ROS and all required dependencies are installable through conda and Robostack.

Different versions of ROS (humble, jazzy, and kilted) are supported with pixi environments. The build relies on the pixi-build-ros backend to manage ROS dependencies from the workspace.

First, install Pixi using these instructions.

Once set up, you can run the pixi tasks as follows.

# Install the frozen environment
pixi install -e jazzy --frozen

# Setup the environment
pixi run -e jazzy setup-colcon

# Build (optionally with symlink installs)
pixi run -e jazzy build
pixi run -e jazzy build-symlink

# Run tests, must manually run build prior to executing
pixi run -e jazzy test

# Show test results
pixi run -e jazzy test-result

Once the workspace is built, it can be used as a “normal” ROS 2 workspace. That is, the workspace can be sourced and used as expected.

# Activate the jazzy environment
pixi shell -e jazzy

# Build with the existing install dirs
colcon build

# Source it
source install/setup.bash

# Or test,
colcon test

# Or launch an example
ros2 launch roboplan_ros_franka franka_example_planning.launch.yaml

The examples from the upstream repository should also be available, as well:

python3 roboplan/roboplan_examples/python/example_scene.py

NOTE: All ROS distros will share build/install directories by default. Be sure to rm -rf build/* install/* when switching between ROS versions or things will break.

NOTE: The pixi-build-ros backend requires that all package.xml files be referenced in the [dev] block of the pixi.toml file. For now, this includes the packages in the roboplan submodule. This could be resolved with pixi add roboplan-python, but for now we stick with the source build for development purposes.

—

Docker Development

A Docker Compose workflow is also provided.

To build and run,

# Build the image, defaults to jazzy but can be overridden by setting $ROS_DISTRO
docker compose build ros

# Start the container
docker compose up ros

# Attach to the running container
docker compose exec ros bash

This will drop the user into a pre-compiled colcon workspace with the source mounted in the image. Users can edit, rebuild, and launch applications from inside the container as needed.

—

ROS 2 baremetal (colcon)

Lastly, as a colcon package, the wrappers can be compiled in any valid ROS 2 workspace.

mkdir -p ~/roboplan_ws/src
cd ~/roboplan_ws/src
git clone --recursive https://github.com/open-planning/roboplan-ros.git

NOTE: To compile the bindings you should install nanobind from pip:

pip3 install nanobind

Source your favorite ROS distro and build the workspace.

source /opt/ros/jazzy/setup.bash
cd ~/roboplan_ws
rosdep install --from-paths src -y --ignore-src
colcon build

NOTE: Additional dependencies may be required outside of rosdistro. We recommend referring to the upstream documentation, or to the included .docker/Dockerfile for information on a base system setup.

—