ROS 2 Essentials

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, Isaac Lab, 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/.

System Requirements

Make sure to install the required software prerequisites before using this repo.

The code may still work on lower-spec systems, such as those without GPUs or on older operating systems. However, these are not tested and may require manual adjustments. Proceed with caution.

Setup

For a standard clone:

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

For a faster depth-1 clone:

git clone --depth 1 https://github.com/j3soon/ros2-essentials.git
cd ros2-essentials
./scripts/post_install.sh
# and optionally restore the full git history some time later:
git fetch --unshallow

Note that the post_install.sh script should be run after each change to the repository (such as switching to another branch or pulling the latest changes).

• Use --recreate-links to force replacement of non-hard-link files under workspace docker/modules/.
• Use --recreate-volumes to invalidate Gazebo/Isaac Sim/Isaac ROS cache volumes after related updates or testing.
• Use --remove-containers to auto-remove containers that block volume recreation.

Troubleshooting: If you encounter an error like "failed to solve: failed to compute cache key: failed to calculate checksum of ref ...: "/modules/install_ros.sh": not found when building Docker images, it means post_install.sh hasn’t been run. This script creates necessary hard links for the Docker build process.

Then, configure the container user ID to match your host user ID by modifying the host ~/.bashrc (or ~/.zshrc) to include the following line:

export USER_UID=$(id -u)

This step is optional if you have user ID 1000 on host.

Next, choose a workspace from the table below and follow its documentation to get started. The rest of this document contains optional information. The search bar at the top right corner of the documentation site and GitHub repository is a good way to navigate to the relevant documentation and commits.

Updating the Repository

To update to the latest commit of the repository, run the following commands:

git pull
./scripts/post_install.sh --recreate-links --recreate-volumes --remove-containers

Make sure to run the post_install.sh script after pulling the latest changes to ensure that the hard links are properly set up. In addition, you should be prepared to rebuild the Docker images of the workspaces you are using, as some updates may require rebuilding the images to take effect.

Building Docker images can be time-consuming. Start the build before taking a break so they can finish while you’re away.

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.

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

Pre-configured Modules

File truncated at 100 lines see the full file

Contribution Guide

We welcome all kinds of contributions, including but not limited to bug reports, documentation improvements, new features, and bug fixes. Please ensure to always open an issue to discuss the changes you want to make before sending a pull request.

Overview

1. Ensure there is an opened GitHub issue corresponding to the changes you want to make.
2. Self-assign the GitHub issue.
3. Fork the repository by visiting ros2-essentials and clicking the “Fork” button.
4. Clone the forked repository to your local machine, e.g., git clone git@github.com:username/ros2-essentials.git
5. Create a new branch for your changes, e.g., git checkout -b feat/your-feature-name for a feature branch or git checkout -b fix/your-bug-name for a bug fix branch.
6. Make your changes and ensure they are tested. To ensure reproducibility, consider re-clone your pushed branch and rerun the post_install.sh script to clear all untracked files and cached data.
7. Push your local changes to your forked repository, e.g., git push origin feat/your-feature-name.
8. Create a pull request to merge your changes into the main repository’s main branch.

Guidelines

1. Commit messages should follow the conventional commit format.
2. Commit description should include as much details as possible. Try to include references you consulted and your rationale behind the changes. This will be essential for reviewers to understand the changes and for future reference. (e.g., 058ff59)
3. If copied files from other sources, please include the source in the commit message. If copied from GitHub, include the permalink (link with commit ID) and the branch name. (e.g., 6a2dac1)
4. Each commit should be atomic and self-contained.
5. When updating template_ws defaults, follow up with a separate unify workspace style commit (preferred message: feat: Unify workspaces style) that applies the minimal template-alignment changes across all workspaces. Keep this separate from the template update commit.
6. If anyone helped you during the development, please include them in the commit message using the Co-authored-by format (e.g., 4f9832d due to this comment). These include, but are not limited to, feedback from reviewers, in-person discussions, and pair programming sessions.
7. Refrain from force-pushes after a reviewer has started reviewing your changes. The only exception is for new contributors when a reviewer has explicitly asked you to rebase your branch or modify commit messages.
8. Use USDA instead of USD file format whenever possible for better readability and version control. (e.g., PR#101)

Use git log and search for related commits to understand the commit message format.

Scripts

When creating a new workspace, use the scripts/create_workspace.sh <workspace_name> script to set up the workspace structure.

Linting

Basic linting is done by running the following script:

tests/test_all.sh

Pull Request References

• Creating a new module, see PR#93 and PR#95.
• Creating and updating a workspace, see PR#83, PR#85, and PR#101.
• Updating Isaac Sim/Lab, see PR#92.
• Using OmniGraph and USDA, see PR#83.