Skip to content

ROS 2 Essentials

tests docs

A repo containing essential ROS2 Humble features for controlling Autonomous Mobile Robots (AMRs) and robotic arm manipulators. Please setup an Ubuntu environment before using this repo.

The goal of this repo is to allow seamless robot policy reuse between simulation and reality powered by Omniverse Isaac Sim and Isaac ROS. In general, the amd64 images support both simulation and real robot control, while the arm64 images only supports real robot control.

Please note that this repo is under rapid development. The code is not guaranteed to be stable, and breaking changes may occur.

The documentation is hosted on https://j3soon.github.io/ros2-essentials/.

Cloning the Repository

git clone https://github.com/j3soon/ros2-essentials.git
cd ros2-essentials

Pre-built Workspaces

Pre-built Docker images for each workspace can be pulled by running docker compose pull in the corresponding workspace directory. Pulling these images bypasses the time-consuming build process (for both Docker Compose and Dev Containers).

The docker image of the template workspace is share by most of the workspace, allowing saving spaces by sharing common packages. Click on the following workspaces to navigate to their respective documentation.

Workspace amd64 arm64 Notes Maintainer
Template ✔️ ✔️ Yu-Zhong Chen, Johnson
ORB-SLAM3 ✔️ Assume Zhan
RTAB-Map ✔️ Assume Zhan
ROS1 Bridge ✔️ ✔️ Skip linting Yu-Zhong Chen
Cartographer ✔️ ✔️ Assume Zhan
Clearpath Husky ✔️ ✔️ Real-world support Yu-Zhong Chen, Johnson
Yujin Robot Kobuki ✔️ ✔️ Real-world support Yu-Zhong Chen
Velodyne VLP-16 ✔️ ✔️ Real-world support Assume Zhan
Gazebo World ✔️ ❌️ Yu-Zhong Chen
ALOHA ✔️ ✔️ Simulation only Johnson

If you have trouble using a workspace, please open an issue and tag the current maintainers mentioned above.

System Requirements

Use Case Platform Hardware Software Notes
Simulation/Deployment x86_64 RTX GPU, 500GB+ SSD Ubuntu 22.04, NVIDIA Driver, Docker, NVIDIA Container Toolkit See this page for more details.
Deployment-Only Jetson Jetson Orin, 500GB+ SSD JetPack 6.0 See this page for more details.

Some functionalities may still work on lower-spec systems, such as those without GPUs or on operating systems other than Ubuntu 22.04. However, these configurations are not officially supported and may require manual adjustments. Use them with caution.

Building Documentation

# (Optional) Create and activate python virtual environment
virtualenv venv -p python3
source venv/bin/activate
# Install dependencies and start serving
cd docs
pip install -r requirements.txt
mkdocs serve
# Go to https://127.0.0.1:8000 to view the site.

Linking the README

rm docs/index.md
ln "${PWD}/README.md" docs/index.md

Acknowledgement

The code is mainly contributed by Johnson, Yu-Zhong Chen, Assume Zhan, Lam Chon Hang, and others. For a full list of contributors, please refer to the contribution list.

We extend our gratitude to ElsaLab and NVIDIA AI Technology Center (NVAITC) for their support in making this project possible.

Disclaimer: this is not an official NVIDIA product.

License

All modifications are licensed under Apache License 2.0.

However, this repository includes many dependencies released under different licenses. For information on these licenses, please check the commit history. Make sure to review the license of each dependency before using this repository.

The licenses for dependencies will be clearly documented in the workspace README in the future.

Supplementary

Installing Docker

Follow this post for the installation instructions.

Installing NVIDIA Container Toolkit

Follow this post for the installation instructions.