===============
Getting Started
===============

Isaac ROS is a collection of NVIDIA® CUDA®-accelerated computing packages and AI models designed to streamline and expedite the development of advanced AI robotics applications.

NVIDIA Isaac ROS is built on open-source ROS 2. Through Isaac ROS, developers in the ROS community can take advantage of NVIDIA-accelerated libraries and AI models to fast track their AI robot development and deployment workflows.

System Requirements
-------------------

Supported Platforms
~~~~~~~~~~~~~~~~~~~

.. include:: /_snippets/supported_platforms_table.rst

ROS Support
~~~~~~~~~~~

All Isaac ROS packages are designed and tested to be compatible with `ROS 2 :ir_ros_distro:`<title>` <https://docs.ros.org/en/:ir_ros_distro:/index.html>`__.

Initialize Compute
------------------

.. tab-set::
   .. tab-item:: x86 Platforms
      :sync: x86

      #. Install the latest NVIDIA GPU Driver using the `official instructions <https://documentation.ubuntu.com/server/how-to/graphics/install-nvidia-drivers/index.html>`__.

      #. Verify the NVIDIA GPU Driver is installed correctly:

         .. code:: bash

            nvidia-smi

         Confirm that all relevant fields satisfy the :ref:`requirements <getting_started/index:System Requirements>`.

         - Driver Version
         - CUDA Version
         - GPU Memory

   .. tab-item:: Jetson Platforms
      :sync: jetson

      #. Complete the `Jetson AGX Thor Quick Start Guide <https://docs.nvidia.com/jetson/agx-thor-devkit/user-guide/latest/quick_start.html>`__.

      #. In the JetPack setup guide, complete only the `Install all components section <https://docs.nvidia.com/jetson/agx-thor-devkit/user-guide/latest/setup_jetpack.html#install-the-whole-jetpack-components>`__.

      #. After boot, confirm that you have installed the correct version of ``Jetpack`` by
         running the following command. Confirm that the output has the terms
         ``R38 (release), REVISION: 4.0``.

         .. code:: bash

            cat /etc/nv_tegra_release

      #. Set the power mode to ``MAXN`` using `this guide <https://docs.nvidia.com/jetson/archives/r38.4/DeveloperGuide/SD/PlatformPowerAndPerformance/JetsonThor.html#nvpmodel-gui>`__.

      #. Set the GPU and CPU clock speeds to max using `this guide <https://docs.nvidia.com/jetson/archives/r38.4/DeveloperGuide/SD/PlatformPowerAndPerformance/JetsonThor.html#maximizing-jetson-thor-performance-only>`__.

      #. Consider the following recommendations for a better experience:

         - :doc:`Jetson Storage Setup </getting_started/compute/jetson_storage>`
         - :doc:`Preempt Setup </getting_started/compute/preempt_setup>`

   .. tab-item:: DGX Spark Platforms
      :sync: dgx_spark

      No additional compute initialization is required for DGX Spark in this section.
      Continue to :ref:`Create a Workspace <getting_started/index:Create a Workspace>`.

Create a Workspace
------------------

.. tab-set::

   .. tab-item:: x86 Platforms
      :sync: x86

      Create a ROS 2 workspace for experimenting with Isaac ROS:

      .. code:: bash

         mkdir -p  ~/workspaces/isaac_ros-dev/src
         echo 'export ISAAC_ROS_WS="${ISAAC_ROS_WS:-${HOME}/workspaces/isaac_ros-dev/}"' >> ~/.bashrc
         source ~/.bashrc

   .. tab-item:: Jetson Platforms
      :sync: jetson

      #. Install the SSD using the instructions in :doc:`Jetson Storage Setup </getting_started/compute/jetson_storage>`.

      #. Create a ROS 2 workspace for experimenting with Isaac ROS:

         .. code:: bash

            mkdir -p  /mnt/nova_ssd/workspaces/isaac_ros-dev/src
            echo 'export ISAAC_ROS_WS="${ISAAC_ROS_WS:-/mnt/nova_ssd/workspaces/isaac_ros-dev/}"' >> ~/.bashrc
            source ~/.bashrc

   .. tab-item:: DGX Spark Platforms
      :sync: dgx_spark

      Create a ROS 2 workspace for experimenting with Isaac ROS:

      .. code:: bash

         mkdir -p  ~/workspaces/isaac_ros-dev/src
         echo 'export ISAAC_ROS_WS="${ISAAC_ROS_WS:-${HOME}/workspaces/isaac_ros-dev/}"' >> ~/.bashrc
         source ~/.bashrc

Configure Isaac ROS Apt Repository
----------------------------------

The NVIDIA Isaac ROS Apt Repository hosts the following categories of packages for all users:

- Isaac ROS CLI package for managing Isaac ROS development environments
- Pre-built Isaac ROS packages for currently-supported platforms
- Auxiliary packages to improve developer experience or to support a legacy OS

To configure the Isaac ROS Apt Repository, follow the steps below:

#. Set the locale on your host system to UTF-8:

   .. code:: bash

      locale  # check for UTF-8

      sudo apt update && sudo apt install locales
      sudo locale-gen en_US en_US.UTF-8
      sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
      export LANG=en_US.UTF-8

      locale  # verify settings

#. Install the dependencies:

   .. code:: bash

      sudo apt update && sudo apt install curl gnupg
      sudo apt install software-properties-common
      sudo add-apt-repository universe

#. Source the Isaac ROS Apt Repository:

   Select your platform to see the appropriate APT repository sourcing instructions.

   .. apt_platform_tabs::

Select Environment Isolation Mode
---------------------------------

Based on your use case, decide on an appropriate level of isolation between Isaac ROS and your host system:

.. tip::

   **Docker** is the recommended option for most users. It provides the highest level of isolation from your host system.

   In Virtual Environment or Bare Metal mode, you may need to remove existing packages from your host system to avoid version conflicts with Isaac ROS and its dependencies.

.. list-table::
   :header-rows: 1
   :widths: 25 25 25 25

   * - Mode
     - Debian packages
     - Python ``pip`` packages
     - Isolation
   * - **Docker (recommended)**
     - Installed inside the container (host unaffected)
     - Installed inside the container (host unaffected)
     - High (full container isolation)
   * - Virtual Environment
     - Installed on host via ``apt``
     - Installed into Isaac ROS virtual environment (isolated from system Python)
     - Medium
   * - Bare Metal
     - Installed on host via ``apt``
     - Installed into system Python ``site-packages``
     - None

This selection will inform subsequent steps in the setup process.

Initialize Isaac ROS CLI
------------------------

#. Install the Isaac ROS CLI:

   .. code:: bash

      sudo apt-get install isaac-ros-cli

#. Configure the environment isolation mode you selected earlier:

   .. tab-set::

      .. tab-item:: Docker
         :sync: docker

         #. Complete platform-specific Docker setup:

            .. tab-set::

               .. tab-item:: x86 Platforms
                  :sync: x86

                  #. Complete the Docker Engine setup using the `official Ubuntu instructions <https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository>`__.

                  #. Install and configure ``nvidia-container-toolkit`` for Docker using the official instructions:

                     - `Install NVIDIA Container Toolkit <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#with-apt-ubuntu-debian>`__
                     - `Configure Docker runtime <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuring-docker>`__

                  #. Add your user to the ``docker`` group:

                     .. code:: bash

                        sudo usermod -aG docker $USER
                        newgrp docker

               .. tab-item:: Jetson Thor Platforms
                  :sync: jetson

                  #. Complete the `Jetson AGX Thor Docker Setup guide <https://docs.nvidia.com/jetson/agx-thor-devkit/user-guide/latest/setup_docker.html>`__.

               .. tab-item:: DGX Spark Platforms
                  :sync: dgx_spark

                  #. Docker and NVIDIA Container Toolkit are already configured on DGX Spark. See the `DGX Spark container runtime documentation <https://docs.nvidia.com/dgx/dgx-spark/nvidia-container-runtime-for-docker.html#installation>`__.

                  #. Add your user to the ``docker`` group:

                     .. code:: bash

                        sudo usermod -aG docker $USER
                        newgrp docker

         #. Restart Docker:

            .. code:: bash

               sudo systemctl daemon-reload && sudo systemctl restart docker

         #. Run Docker pre-flight checks:

            .. code:: bash

               docker info | grep -E "Runtimes|Default Runtime"
               docker run --rm hello-world
               docker run --rm --gpus all ubuntu:24.04 bash -lc 'echo "NVIDIA runtime OK"'

            Confirm that Docker lists available runtime entries, ``hello-world`` exits successfully,
            and the GPU runtime check prints ``NVIDIA runtime OK``.

         #. Initialize the Isaac ROS CLI:

            .. code:: bash

               sudo isaac-ros init docker

         |

         .. dropdown:: Customizing the Docker Image

               The default Isaac ROS Docker image contains a core set of dependencies for basic Isaac ROS usage.

               To add additional dependencies (e.g., RealSense camera support), refer to the :ref:`Docker Mode Configuration <concepts/dev_env/index:Docker Mode Configuration>` documentation.

      .. tab-item:: Virtual Environment
         :sync: venv

         #. Configure your host environment for Isaac ROS:

            .. include:: _snippets/host_env_setup.rst

         #. Initialize the Isaac ROS CLI:

            .. code:: bash

               sudo isaac-ros init venv

      .. tab-item:: Bare Metal
         :sync: baremetal

         .. caution::

            The ``baremetal`` mode is only recommended for advanced users.

            This mode installs Isaac ROS packages and their dependencies into your system Python environment.

            Without proper care, this has the potential to **break your host system**.

         #. Configure your host environment for Isaac ROS:

            .. include:: _snippets/host_env_setup.rst

         #. Initialize the Isaac ROS CLI:

            .. code:: bash

               sudo isaac-ros init baremetal

            Acknowledge the prompt, then confirm to continue.

            .. dropdown:: Unattended/Non-Interactive Installation

               In some cases, it may be desirable to skip the prompt when initializing the ``baremetal`` mode.

               To perform a non-interactive installation, use the ``--yes`` flag:

               .. code:: bash

                  sudo isaac-ros init baremetal --yes

.. dropdown:: Configuring the Isaac ROS Development Environment

   The Isaac ROS CLI uses layered configuration files to manage settings across all isolation modes.

   To use these configuration files and customize your development environment, refer to the :doc:`Isaac ROS Development Environment </concepts/dev_env/index>` page.

Integrate External Data Sources (Optional)
------------------------------------------

Many Isaac ROS demos include pre-recorded rosbag data to help you get started as quickly as possible.

Optionally, these demos can also be integrated with external data sources, including cameras and the Isaac Sim simulation platform.

.. dropdown:: Sensors

   Isaac ROS provides setup instructions for specific camera models from the following product lines:

   - :doc:`RealSense <sensors/realsense_setup>`
   - :doc:`StereoLabs ZED <sensors/zed_setup>`

   Calibrate your cameras depending on your type of camera and the object it is on:

   - :doc:`Monocular Camera <sensors/camera_calibration>`
   - :doc:`Stereo Camera on Robot Arm <sensors/isaac_for_manipulation_camera_calibration>`
   - :doc:`Stereo Camera on Mobile Robot <sensors/amr_extrinsic_calibration>`

.. dropdown:: Isaac Sim

   .. _gs_isaac_sim:

   `Isaac Sim <https://developer.nvidia.com/isaac-sim>`__ is NVIDIA's robotics simulation platform powered by Omniverse.

   Isaac Sim can be used to run and test the ROS 2 applications. There are two ways we can configure the system:

   - **Software in the Loop (SIL)** refers to a configuration where the software being tested is not running on the target hardware platform. For example, Isaac ROS packages being tested on x86 before deployment on a Jetson device is SIL.

   - **Hardware in the Loop (HIL)** refers to a configuration where the software is being tested on the target hardware platform. For example, Isaac ROS packages being tested on a Jetson device before deployment is HIL.

   In both the configurations, Isaac Sim runs on a ``x86_64`` machine providing sensor data and world information.

   .. tab-set::

      .. tab-item:: Isaac Sim 5.0 and Isaac Sim 5.1

         .. include:: isaac_sim/_snippets/isaac_sim_5_x.rst

   .. dropdown:: Isaac Sim Tutorial Links

      .. _gs_isaac_sim_tutorial_links:

      Isaac ROS includes a number of tutorials that demonstrate integration with Isaac Sim.

      Each of these links takes you to a tutorial that is listed under :doc:`Repositories and Packages </repositories_and_packages/index>`. They are linked here as a reference and to help you find them faster.

      .. note::

         These tutorials were last validated with `Isaac Sim 5.0 <https://docs.isaacsim.omniverse.nvidia.com/5.0.0/overview/release_notes.html>`__ and `Isaac Sim 5.1 <https://docs.isaacsim.omniverse.nvidia.com/5.1.0/overview/release_notes.html>`__.

      -  :doc:`Tutorial for AprilTag Detection with Isaac Sim </concepts/fiducials/apriltag/tutorial_isaac_sim>`
      -  :doc:`Tutorial for Visual SLAM with Isaac Sim </concepts/visual_slam/cuvslam/tutorial_isaac_sim>`
      -  :doc:`Tutorial for Nvblox with Isaac Sim </concepts/scene_reconstruction/nvblox/tutorials/tutorial_isaac_sim>`
      -  :doc:`Tutorial for DNN Object Detection with Isaac Sim </concepts/object_detection/detectnet/tutorial_isaac_sim>`
      -  :doc:`Tutorial for SGM Stereo Disparity with Isaac Sim </concepts/stereo_depth/sgm/tutorial_isaac_sim>`
      -  :doc:`Tutorial for DNN Stereo Depth Estimation with Isaac Sim </concepts/stereo_depth/ess/tutorial_isaac_sim>`
      -  :doc:`Tutorial for Occupancy Grid Localizer with Isaac Sim </concepts/localization/lidar/tutorial_isaac_sim>`
      -  :doc:`Tutorial for DNN Image Segmentation with Isaac Sim </concepts/segmentation/unet/tutorial_isaac_sim>`
      -  :doc:`Tutorial for Isaac ROS Mission Client </concepts/cloud_control/isaac_ros_mission_client>`
      -  :doc:`Tutorial for RT-DETR with Isaac Sim </concepts/object_detection/rtdetr/tutorial_isaac_sim>`
      -  :doc:`Tutorial for FoundationPose with Isaac Sim </concepts/pose_estimation/foundationpose/tutorial_isaac_sim>`
      -  :doc:`Tutorial for NITROS Bridge with Isaac Sim </concepts/nitros_bridge/tutorial_isaac_sim>`
      -  :doc:`Tutorial for cuMotion MoveIt Plugin with Isaac Sim </concepts/manipulation/cumotion_moveit/tutorial_isaac_sim>`
      -  :doc:`Tutorials for Isaac for Manipulation Reference Workflows with Isaac Sim </reference_workflows/isaac_for_manipulation/tutorials/tutorial_isaac_sim>`

Run an Isaac ROS Demo
---------------------

You're now ready to run an Isaac ROS demo!

Navigating the Isaac ROS Site
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Isaac ROS offers a collection of GitHub **Repositories**, each focused on a general robotics problem area. Every repository has its own page under the :doc:`repository index </repositories_and_packages/index>`.

- Isaac ROS repositories are further organized into ROS 2 **Packages**, each focused on a specific solution implementation or use case. Each package has its own page under the repository-level page.

- Most packages contain a **Quickstart**, which is a self-contained example that allows you to quickly test out the package's core functionality. Quickstarts are located on each package's page.

- Additionally, many packages contain more advanced **Tutorials** that dive deeper into the package's functionality. When available, tutorials are listed below the Quickstart on each package's page.

- Package pages also contain **Troubleshooting** and **API** sections to help you use Isaac ROS in your own applications.

- Robotics fundamentals, NVIDIA technology, and other **Concepts** are explained under the :doc:`concepts index </concepts/index>`.

Browse the available Isaac ROS :doc:`Repositories and Packages </repositories_and_packages/index>` to find your first quickstart.

Troubleshooting
---------------

See the :doc:`troubleshooting </troubleshooting/dev_env>` section for help with setting up your development environment.

.. toctree::
   :maxdepth: 1
   :hidden:

   compute/index
   sensors/index