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

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.

Link Documentation to ROS2 Workspaces

```sh

File truncated at 100 lines see the full file