CommonRoad-Autoware Motion Planning Interface (CR2AW)

This project builds an interface between CommonRoad and Autoware.Universe. This enables to use various motion planners using the CommonRoad format within the Autoware software stack and rapidly transfer new algorithms from simulation to a real vehicle.

CR2AW is implemented as a ROS2 node which can be launched as a complete planning module within Autoware. This repository provides the source code, as well as the required launch and dependency files to run the CommonRoad planning module in Autoware.

📑 Table of Contents

• Table of Contents
• File structure
• Requirements and Dependencies
• Setup
• Launch
• Documentation
• Development Guide
• Authors
• Citation

📁 Repository structure

Below, we provide a basic overview over the most important components of the repository. For a detailed explanation of the software architecture, please see our paper.

.
├── cr2autoware/
│   ├── cr2autoware.py                        # CR2AW interface ROS2 node
│   ├── common
│   │   ├── ros_interface/                    # ROS publisher/subscriber specifications
│   │   └── utils/                            # utilities
│   ├── handlers/                             # implementation of handler classes
│   ├── interfaces/
│   │   ├── base/                             # base interface classes 
│   │   └── implementation/                   # implementation of interface classes
│   │
├── data                                      # directory to store sample CommonRoad map
├── launch
│   └── cr2autoware_node.launch.xml           # launch file for CR2AW node
├── param
│   ├── cr2autoware_param_file.param.yaml     # ROS param file for the CR2AW node
│   └── edgar_rp_config.yaml                  # config parameters for the reactive planner
├── scripts
│   ├── lanelet2cr.py                         # conversion script for a Lanelet2 map to CR format
│   └── cr2lanelet.py                         # conversion script for a CR map to Lanelet2 format
│
├── tum_commonroad_planning_launch/           # ROS launch package for the CommonRoad planning component
│   ├── launch/                               # launch file
│   ├── config/                               # ROS param files
│
├── tum.commonroad.planning.repos             # Dependencies pulled via VCS
├── cr2autoware_install.sh                    # Setup bash sript for CR2AW node
.

🔗 Requirements and Dependencies

System requirements

CR2AW runs together with Autoware: the minimum system requirements for running Autoware are described here. We recommend running Autoware within a dockerized setup.

Dependencies

Autoware

CR2AW was tested with Autoware.Universe version with release tag v1.0, which is accessible here.

Note: Updates to newer Autoware releases will follow regularly.

CommonRoad

The pip dependencies of CR2AW are listed in the requirements file requirements.txt.

The following CommonRoad dependencies are pulled from GitHub. They are included in the tum.commonroad.planning.repos file and are pulled via VCS (see Setup).

Tools	Version
commonroad-scenario-designer	develop:latest
commonroad-reactive-planner	master:latest

🔧 Setup

To setup Autoware, we recommend using the Docker Installation Setup, which is described in detail on the Autoware Documentation page. Our interface can be directly integrated into the setup procedure.

Following the Docker Installation Setup there are two setup options for Autoware: using pre-built Docker images or building the Docker image from scratch. You can use both options for CR2AW, simply make sure to use the Autoware release tag mentioned above (see here) and use images with the devel tag.

After setting up a working Autoware Docker on your machine, you need to run the following steps to include CR2AW within your Docker container:

1. Go to autoware root directory: cd autoware/
2. Copy the file: tum.commonroad.planning.repos into autoware/
3. Pull dependencies via vcs

   vcs import src < tum.commonroad.planning.repos

4. Go to root directory of commonroad-autoware-interface/

   cd src/universe/autoware.universe/planning/tum_commonroad_planning/commonroad-autoware-interface/

5. Run setup bash script for CR2AW. This installs all CommonRoad-related dependencies

   ./cr2autoware_install.sh

6. Go back to autoware root directory
7. Build the ROS packages for CR2AW and for the CommonRoad planning module launch via colcon

   colcon build --symlink-install --packages-select cr2autoware tum_planning_launch

8. Source the install workspace

   source install/setup.bash

Note (only for TUM internal setup): For setup guide using a microservice architecture (i.e., docker compose launch), where individual modules run in their own docker containers, please refer to README_FOR_DEVELOPERS.md

🚀 Launch and Usage

The CR2AW interface integrates into the standard launch procedure of Autoware and has been tested both with the Planning Simulation of Autoware and on our real vehicle EDGAR. Here we only describe how to launch CR2AW with Autoware's Planning Simulation.

A tutorial on how to use the Planning Simulation of Autoware is provided here. Please make sure that you have gone through this tutorial beforehand.

To replace the standard Autoware planning module by CR2AW, the following steps should be performed.

Map conversion

Autoware requires an HD map in the Lanelet2 format (see here). For CR2AW, we require the map in the CommonRoad format. Thus, we use the Lanelet2-CommonRoad map conversion from the CommonRoad-Scenario-Designer. We provide a script for the map conversion in ./src/cr2autoware/scripts/lanelet2cr.py

1. Change input path in lanelet2cr.py to your map directory which contains

   a) The lanelet2 map (*.osm file)

   b) A map configuration file map_config.yaml which specifies the lat/lon map origin of the lanelet2 map. Important: The lat/long origin must correspond to the origin coordinates of the associated MGRS grid cell in which your map is located. Currently, only maps which lie within one MGRS grid cell can be used with Autoware.

2. Run the conversion script

   python3 lanelet2cr.py

3. Check if the converted CommonRoad map (*.xml file) is in the map directory

In /src/cr2autoware/data/sample-map-planning/ we provide the converted map and the map_config.yaml for the sample-map-planning used in the Autoware tutorials.

Launch CommonRoad Planning module

Launching the CommonRoad Planning module within the Planning Simulation is done similarly to the instructions in the Autoware Tutorial. Note: all steps are performed within the Docker container running Autoware (unless you use a local installation of Autoware). We further assume that the autoware/ directory is located in the home directory ~.

1. Source the workspace:

   source ~/autoware/install/setup.bash

2. Launch the planning simulation. We use the launch file planning_simulator.launch.xml provided in tum_commonroad_planning_launch/launch where we deactivate the default Autoware planning module.

   ros2 launch tum_planning_launch planning_simulator.launch.xml map_path:=<YOUR_MAP_PATH> vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit

   where you replace <YOUR_MAP_PATH> accordingly.

3. Launch the CommonRoad planning module and CR2AW:

   ros2 launch tum_planning_launch tum_planning_component.launch.xml map_path:=<YOUR_MAP_PATH> vehicle_model:=sample_vehicle

   where you replace <YOUR_MAP_PATH> accordingly.

📚 Documentation

Please find a deployed version of the documentation here.

🔨 Development guide

Please see our README_FOR_DEVELOPERS.md for some additional notes on how to use CR2AW for development purposes.

👥 Authors

In alphabethic order by last name:

Maintainers: Yuanfei Lin, Tobias Mascetta, Gerald Würsching

Contributors: Hamza Begic, Hamza Ben Yaacoub, Aziz Bouziri, Andrii Chumak, Jan Franck, Till Grutschus, Koray Koca, Yuanfei Lin, Tobias Mascetta, Kaian Ni, Wei-Lin Pai, Sven Pflaumbaum, Florian Weiser, Gerald Würsching, Yashuai Yan, Alexander Zimmer

💬 Citation

If you use our code for research, please cite our paper:

@inproceedings{Wuersching2024b
  author = {Würsching, Gerald and Mascetta, Tobias and Lin, Yuanfei and Althoff, Matthias},
  title = {Simplifying Sim-to-Real Transfer in Autonomous Driving: Coupling Autoware with the CommonRoad Motion Planning Framework},
  booktitle = {Proc. of the IEEE Intelligent Vehicles Symposium},
  year={2024},
  pages = {tbd},
  abstract = {Validating motion planning algorithms for autonomous vehicles on a real system is essential to improve their safety in 
              the real world. Open-source initiatives, such as Autoware, provide a deployable software stack for real vehicles. 
              However, such driving stacks have a high entry barrier, so that integrating new algorithms is tedious. Especially new 
              research results are thus mostly evaluated only in simulation, e.g., within the CommonRoad benchmark suite. To address 
              this problem, we present CR2AW, a publicly available interface between the CommonRoad framework and Autoware. CR2AW 
              significantly simplifies the sim-to-real transfer of motion planning research, by allowing users to easily integrate 
              their CommonRoad planning modules into Autoware. Our experiments both in simulation and on our research vehicle showcase 
              the usefulness of CR2AW.},
}