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.

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.

Setup

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

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). In addition, the script can be run with the -f or --force flag to force removal of hard links if needed.

and 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.

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

Modules with Default: ✔️ are installed by default in all workspaces.

Edit the build.args section in the *_ws/docker/compose.yml file and rebuild the workspace to add or remove modules.

Building Documentation

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create and activate python virtual environment
uv venv --python 3.10
source .venv/bin/activate
# Install dependencies and start serving
cd docs
uv pip install -r requirements.txt
# (Optional) Comment out the `git-committers` block in `docs/mkdocs.yml` to speed up build.
mkdocs serve
# Go to https://127.0.0.1:8000 to view the site.

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.
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. If anyone helped you during the development, please include them in the commit message using the Co-authored-by format. (e.g., 4f9832d)
6. Refrain from force-pushes after a reviewer has started reviewing your changes.

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

Linting

Basic linting is done by running the following script:

tests/test_all.sh