Isaac ROS Common

Overview

The Isaac ROS Common repository contains a number of scripts and Dockerfiles to help streamline development and testing with the Isaac ROS suite.

Isaac ROS DevOps tools

Docker containers allow you to quickly set up a sensitive set of frameworks and dependencies to ensure a smooth experience with Isaac ROS packages. The Dockerfiles for x86_64 are based on the version 23.10 image from Deep Learning Frameworks Containers. On Jetson platforms, JetPack manages all of these dependencies for you.

Use of Docker images enables CI|CD systems to scale with DevOps work and run automated testing in cloud native platforms on Kubernetes.

For solutions to known issues, see the Troubleshooting section.

Isaac ROS Dev Scripts

run_dev.sh

Builds and launches development environment Docker container with host ROS workspace files mounted, or attaches to an existing running container.

Arguments

Arg

Long argument

Default

Description

-a

--docker_arg

(none)

Adds arguments to the docker run invocation of the dev container. For example, -a "-v /host_directory:/container_directory"

-b

--skip_image_build

0 (do not skip image build)

Avoids building the base image to reuse the existing image if one exists. Useful for running offline after base image has been built once already.

-d

--isaac_ros_dev_dir

The first directory that exists in order: ~/workspaces/isaac_ros-dev, /workspaces/isaac_ros-dev, or $SCRIPT_ROOT/../

The location of the host directory to mount into the dev container as /workspaces/isaac_ros-dev

-i

--image_key

ros2_humble

Image key suffix to be used for preparing base image. Platform aarch64 or x86_64 will be prepended and user appended for the final image key.

-v

--verbose

0 (not verbose)

Echoes several key commands to the console for debugging.

Config Keys

Shell values read from ~/.isaac_ros_common-config if exists.

Key

Type

Example(s)

Description

BASE_DOCKER_REGISTRY_NAMES

Array of string registry names

("nvcr.io/isaac/ros" "nvcr.io/nvidian/isaac-ros/ros")

Docker image names to search for tags for matching prebuilt images.

CONFIG_CONTAINER_NAME_SUFFIX

string

(blank)

Suffix to append for container name launched by script.

CONFIG_IMAGE_KEY

Period-delimited string for base image key

ros2_humble.third_party

Equivalent of -i/--image_key argument.

CONFIG_DOCKER_SEARCH_DIRS

Array of directory paths

$SCRIPT_ROOT/../docker

Array of directories to search for Dockerfiles matches for image keys.

build_image_layers.sh

Builds a Docker image by parsing an image key (period-delimited string of keys), matching local Dockerfiles corresponding to those keys, and building them in sequence, feeding the result of one as the base image of the next.

Arguments

Arg

Long argument

Default

Description

-a

--build_arg

(none)

Adds arguments to the docker build invocation of the dev container. For example, -a "USER_ARG=0"

-b

--base_image

(none)

Base image name to use as the root, usually not needed. If not specified, the first Dockerfile must have a default BASE_IMAGE argument value.

-c

--context_dir

(none)

Directory to use for docker context for the final layer and included as a docker search directory for matching Dockerfiles.

-i

--image_key

(required)

The image key to build. Platform key (aarch64 or x86_64) will get prepended and user will be appended if not included already.

-k

--disable_buildkit

0 (not disabling BuildKit)

Disables BuildKit when invoking docker build.

-n

--image_name

Derived from image key replacing periods with dashes and appending -image

Name to use for the Docker image being built.

-r

--skip_registry_check

0 (not skipping registry check)

If 1, skips checking any remote registries for prebuilt images with matching hashes of Dockerfiles locally (useful for offline mode if the image is built and just want cached Docker image).

-y

--ignore_composite_keys

0 (not ignoring composite keys)

If 1, image key matching only looks at Dockerfiles with a single image key. Dockerfiles with multiple keys will be ignored, such as Dockerfile.key1.key2.

Config Keys

Shell values read from ~/.isaac_ros_common-config if exists.

Key

Type

Example(s)

Description

ADDITIONAL_BUILD_ARGS

Array of strings

$SCRIPT_ROOT/../docker

Build arguments to pass to docker build.

BASE_DOCKER_REGISTRY_NAMES

Array of string registry names

("nvcr.io/isaac/ros" "nvcr.io/nvidian/isaac-ros/ros")

Docker image names to search for tags for matching prebuilt images.

CONFIG_DOCKER_SEARCH_DIRS

Array of directory paths

$SCRIPT_ROOT/../docker

Array of directories to search for Dockerfiles matches for image keys.

DOCKER_BUILDKIT

integer boolean

0 or 1

Enables or disables Docker BuildKit environment.

IGNORE_COMPOSITE_KEYS

integer boolean

0 or 1

Enables or disables matching Dockerfiles with composite keys, such as Dockerfile.key1.key2.

SKIP_REGISTRY_CHECK

integer boolean

0 or 1

Enables or disables checking remote registries for prebuilt images.

docker_deploy.sh

Packages prebuilt build artifacts from a ROS workspace and/or set of Debians into a runnable Docker image.

Arguments

Arg

Long argument

Default

Description

-a

--custom_apt_source

(none)

Adds your own apt-get sources so that Debian installations can pull from your Debian repositories.

-b

--base_image_key

${PLATFORM}.ros2_humble

Image key to use as base image before layering on build products.

-d

--include_dir

(none)

Host directory path that will be layered in as a root overlay into the final Docker image. Repeated.

-f

--launch_file

(none)

Launch file name to run by default on container entrypoint. Must be specified with -p.

-i

--install_debians

(none)

Comma-delimited string of Debians to installed with apt-get install on the base image.

-n

--name

isaac_ros_deploy

Name to use for the Docker image being built.

-p

--launch_package

(none)

ROS package name that hosts the target launch file. Must be specified with -f.

-s

--suffix_image_key

(none)

Image key to use as additional layers after the build products have been added.

-t

--include_tarball

(none)

Tarball to be staged as a root overlay on top of the base image. Repeatable.

-w

--ros_ws

(none)

Path to ROS workspace to layer in install/ directory from and add a rosdep install when building Docker image.

Config Keys

Shell values read from ~/.isaac_ros_common-config if exists.

Key

Type

Example(s)

Description

BASE_IMAGE_KEY

Period-delimited string

release_base_aarch64.ros2_humble

Base image to layer build products on top of.

CUSTOM_APT_SOURCES

Array of string apt sources

("deb https://mycool-apt-get-server.com/ros-debian-local focal main")

Custom apt sources to add for Debian installs.

DEPLOY_IMAGE_NAME

string

myimage

Name of Docker image built.

INSTALL_DEBIANS_CSV

Comma-delimited string

libnvvpi3,tensorrt,ros-humble-isaac-ros-all

List of Debians to install on top of base image.

INCLUDE_DIRS

Array of directory absolute paths

("/workspaces/myfiles" "/some/other/dir")

Host directories to include as a root overlay in final image.

INCLUDE_TARBALLS

Array of directory absolute file paths

("/workspaces/myfiles.tar.gz" "/some/other/files.tar.gz")

Paths to .tar.gz files containing root overlays.

ROS_WS

String path

/workspaces/isaac_ros-dev/ros_ws

Path to ROS workspace with built install/ directory to include.

LAUNCH_PACKAGE

string

isaac_ros_image_pipeline

ROS package name hosting the launch file to run by default in container.

LAUNCH_FILE

string

isaac_ros_image_flip.launch.py

Launch file to run by default in container.

Supported Platforms

This package is designed and tested to be compatible with ROS 2 Humble running on Jetson or an x86_64 system with an NVIDIA GPU.

Note

Versions of ROS 2 other than Humble are not supported. This package depends on specific ROS 2 implementation features that were introduced beginning with the Humble release. ROS 2 versions after Humble have not yet been tested.

Platform

Hardware

Software

Notes

Jetson

Jetson Orin

JetPack 6.0

For best performance, ensure that power settings are configured appropriately.


Jetson Orin Nano 4GB may not have enough memory to run many of the Isaac ROS packages and is not recommended.

x86_64

Ampere or higher NVIDIA GPU Architecture with 8 GB RAM or higher

Ubuntu 22.04+

CUDA 12.2+

Docker

To simplify development, we strongly recommend leveraging the Isaac ROS Dev Docker images by following these steps. This will streamline your development environment setup with the correct versions of dependencies on both Jetson and x86_64 platforms.

Note

All Isaac ROS Quickstarts, tutorials, and examples have been designed with the Isaac ROS Docker images as a prerequisite.

Customize your Dev Environment

To customize your development environment, reference this guide.

Updates

Date

Changes

2024-09-26

Updated for Isaac ROS 3.1

2024-05-30

Update to be compatible with JetPack 6.0

2023-10-18

Updated for Isaac ROS 2.0.0

2023-05-25

Refreshed ROS 2 Humble

2023-04-05

Experimental support for WSL2, merged image keys humble and nav2 into ros2_humble

2022-10-19

Minor updates and bugfixes

2022-08-31

Update to be compatible with JetPack 5.0.2

2022-06-30

Support ROS 2 Humble and miscellaneous bug fixes.

2022-06-16

Update run_dev.sh and removed isaac_ros_nvengine

2021-10-20

Migrated to NVIDIA-ISAAC-ROS, added isaac_ros_nvengine and isaac_ros_nvengine_interfaces packages

2021-08-11

Initial release to NVIDIA-AI-IOT