===============
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>`__.

      #. Install the complete `JetPack SDK <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: 2.1``.

         .. code:: bash

            cat /etc/nv_tegra_release

      #. Set the power mode to ``MAXN`` using `this guide <https://docs.nvidia.com/jetson/archives/r38.2.1/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.2.1/DeveloperGuide/SD/PlatformPowerAndPerformance/JetsonThor.html#maximizing-jetson-thor-performance>`__.

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

         .. code:: bash
            
            sudo usermod -aG docker $USER
            newgrp docker

      #. Setup Docker.

         .. include:: /_snippets/docker_buildx.rst

      #. 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>`
         - :doc:`Jetson VPI </getting_started/compute/jetson_vpi>`

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

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:

   NVIDIA hosts the Isaac ROS Apt Repository on two CDNs (Content Distribution Networks), one in the United States (``.com``) and one in China (``.cn``).

   Select the appropriate CDN based on your location and other considerations.

   :ir_apt:`<full>`

   .. tab-set::
      .. tab-item:: US CDN
         :sync: us

         :ir_apt_public_cdn:`<us>`

      .. tab-item:: China CDN
         :sync: china

         :ir_apt_public_cdn:`<china>`

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.

.. 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)
   * - Bare Metal (no official support)
     - *Manually* installed on host via ``apt``
     - *Manually* installed on host via ``pip``
     - None

This selection will inform subsequent steps in the setup process.

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

#. Install dependencies:

   .. code:: bash

      pip install termcolor --break-system-packages

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

         #. Install Docker following the `official instructions <https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository/>`__.

         #. Install the NVIDIA Container Toolkit following the `official instructions <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#with-apt-ubuntu-debian>`__.

         #. Configure ``nvidia-container-toolkit`` for Docker using the `official instructions <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuring-docker>`__.

         #. Restart Docker:

            .. code:: bash

               sudo systemctl daemon-reload && sudo systemctl restart docker

         #. Initialize the Isaac ROS CLI:

            .. code:: bash

               sudo isaac-ros init docker
         
         |

         .. dropdown:: Configuring Docker Environment

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

               To further customize the Isaac ROS development environment, refer to :doc:`this page </concepts/dev_env/index>`.

      
      .. tab-item:: Bare Metal

         The Isaac ROS CLI does not currently support bare metal mode.

         Users should reference the various Isaac ROS Dockerfiles to identify all dependencies and install them manually.

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/missions/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