.. _isaac_sim_app_install_ros: ======================================================== ROS & ROS 2 Installation ======================================================== |isaac-sim| provides both a ROS and ROS 2 bridge for ROS system integration. The same set of common components are used to define the types of data being published/received by the simulator. ============== ======== ==================== Platform ROS ROS2 ============== ======== ==================== Ubuntu 20.04 Noetic Foxy, Humble(Beta) Ubuntu 22.04 NA Humble Windows 10 NA Foxy (Beta) ============== ======== ==================== For the ROS bridge, |isaac-sim_short| runs a custom roscpp build of **ROS Noetic** internally so that it works properly with the |omni| framework and Python 3. This is backwards compatible with **ROS Melodic**. For the ROS 2 bridge, |isaac-sim_short| is currently compatible with **ROS 2 Foxy**. Using **Ubuntu 20.04** is recommended for ROS 2. .. important:: For ROS, in the steps below replace ``noetic`` with ``melodic`` if you are installing on Ubuntu 18.04 .. important:: For ROS2, in the steps below replace ``foxy`` with ``humble`` if you are installing on Ubuntu 22.04 Running Native ROS ======================= #. Download ROS following the instructions on the official website: - `ROS Noetic Ubuntu 20.04 `_ **or for Ubuntu 18.04** `ROS Melodic Ubuntu 18.04 `_ - `ROS 2 Foxy Ubuntu 20.04 `_ #. Source the ROS environment in the terminal. You must perform this step each time before using any ROS commands. **ROS** .. code-block:: source /opt/ros/noetic/setup.bash **ROS 2** .. code-block:: source /opt/ros/foxy/setup.bash #. For **ROS** only: Start ``roscore`` in a ROS-sourced terminal. Isaac Sim does not run ``roscore`` by default to be more flexible for use cases where Isaac Sim is being integrated with existing ROS workflows. .. Running In Docker .. ======================= .. **Isaac Sim and ROS inside same Docker** .. Start the docker container following the instructions in :ref:`Docker Container Setup ` and :ref:`Running Headless Container ` .. When starting the |isaac-sim| container append ``--network=host`` to the starting arguments to expose all ports between the host and container. This will allow you to communicate with the ros master instance inside of the container from the docker host. .. Once the |isaac-sim_short| container is running, open a new terminal on the docker host and run the following. Replace ``CONTAINER_NAME`` with the name or identifier for your running container. This command will start an interactive bash session inside of the running container. .. .. code-block:: .. docker exec -it CONTAINER_NAME bash .. In this terminal run the following commands to install additional dependencies needed to run the ROS bridge extension and ROSCore. Note that these steps are not persistent and will need to be re-run if the docker container is restarted. .. .. code-block:: .. apt-get install libapr1 lsb-release -y .. sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' .. apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654 .. apt update && apt install ros-noetic-ros-base -y .. Once ROS is installed, start ``roscore``, enable ROS extension, and you can now run your ROS applications and ROS examples. .. **Isaac Sim and ROS in separate Docker** .. TODO: .. When communicating with another host (i.e real robot, an existing ROS stack on a different computer, etc), set the ``ROS_IP`` and ``ROS_MASTER_URI`` environment variables to match the host machine before starting |isaac-sim|. .. **Remote Isaac Sim, local ROS** .. TODO .. _isaac_sim_app_enable_ros: Enabling the ROS / ROS 2 Bridge Extension ========================================= To enable the ROS/ROS2 bridge extension, go to the extension manager menu *Window->Extensions* and search for ROS bridge. Only one of the ROS Bridge extensions can be enabled at any given time. .. image:: /content/images/isaac_ros_install_enable.gif :align: center **ROS2 Bridge prep** If you intend to use a ROS2 bridge, before launching |isaac-sim_short|, you need to set the Fast DDS middleware with the following steps: #. Create a file named ``fastdds.xml`` under ``~/.ros/``, paste the following snippet link into the file. .. code-block:: bash Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. NVIDIA CORPORATION and its licensors retain all intellectual property and proprietary rights in and to this software, related documentation and any modifications thereto. Any use, reproduction, disclosure or distribution of this software and related documentation without an express license agreement from NVIDIA CORPORATION is strictly prohibited. UdpTransport UDPv4 UdpTransport false #. Run ``unset LD_LIBRARY_PATH`` in the terminal. #. Run ``export FASTRTPS_DEFAULT_PROFILES_FILE=~/.ros/fastdds.xml`` #. (Optional) Run ``export ROS_DOMAIN_ID=(id_number)`` before launching |isaac-sim_short|. You will have a chance later to decide whether to use this ROS_DOMAIN_ID inside your environment, or explictly use a different id number for any given topic. #. Launch |isaac-sim_short|. .. warning:: Do not source ROS2 in the terminal running |isaac-sim_short|, standalone python scripts or Isaac Cortex as that can cause errors during startup because of conflicting symbols. .. note:: You can only enable one type of ROS2 bridge in a single |isaac-sim_short| session. So if you want to enable ROS2 Humble bridge (Experimental) after disabling ROS2 Foxy bridge (or vice versa), you will need to shutdown |isaac-sim_short| and start a new session in order to enable the second bridge. .. note:: For convenience ``fastdds.xml`` is also located at the root of the foxy_ws folder Setting Up Workspaces ======================= .. _isaac_ros_workspace: Clone the Isaac Sim ROS Workspace Repository from `` .. note:: For |isaac-sim_short| 2022.2.1 the old ros*_workspace folders are still provided with the installer, going forward `` will be where future updates are made. ROS 1 ################# A few ROS packages are needed to go through the Isaac Sim ROS / ROS 2 tutorial series. To make it easy, entire ROS and ROS2 workspaces with the necessary packages are included. Follow the steps below to build it and source the overlay of this package if you want to use the provided workspace directly. You are also welcome to copy and paste the individual packages into your own workspace and built it there, and make sure that workspace is inside ``ROS_PACKAGE_PATH``. #. Ensure your native ROS has been sourced if it has not been already: .. code-block:: bash source /opt/ros/noetic/setup.bash You can check if the sourcing is successful by checking the ``ROS_PACKAGE_PATH`` environment variable. .. code-block:: bash echo $ROS_PACKAGE_PATH /opt/ros/noetic/share #. One of the packages included in the Isaac Sim ROS workspace ``isaac_moveit`` uses MoveIt on a Franka Emika "Panda" Arm. To ensure this package builds, first install MoveIt from pre-built binaries (Debian): .. code-block:: bash sudo apt install ros-$ROS_DISTRO-moveit #. Then follow the steps outlined `here `_ to install the ``panda_moveit_config`` package in your :ref:`ROS workspace `. #. Resolve any package dependencies from the root of the ROS workspace by running the following command: .. code-block:: bash cd noetic_ws rosdep install -i --from-path src --rosdistro noetic -y #. In the ROS-sourced terminal, build the Isaac ``noetic_ws`` folder, then source the overlay. .. code-block:: bash catkin_make source devel/setup.bash This will put the Isaac Sim ROS workspace in your ``ROS_PACKAGE_PATH``. You can use ``echo $ROS_PACKAGE_PATH`` again to see that the path to the Isaac Sim ROS workspace has been added in front of the original one. #. Alternatively, you can move the individual ROS packages from the ``noetic_ws/src`` folder into your own ROS workspaces and build it. Go to the `ROS website `_ for tutorials on building your own ROS packages. If you want to give Isaac Sim access to your existing packages, make sure to set the ``ROS_PACKAGE_PATH`` environment variable to include the desired ROS workspace in the same terminal before starting up |isaac-sim|. .. _isaac_included_ros_packages: Included ROS 1 Packages ************************* The following is a list of sample ROS packages created for |isaac-sim|: - **carter_2dnav**: Contains the required launch file and ROS navigation parameters for the NVIDIA Carter robot. - **carter_description**: A description of the NVIDIA Carter robot model. - **cortex_control**: Tools for establishing communication between Cortex and controllers. - **cortex_control_franka**: Contains launch files and python nodes used to control a physical Franka robot with Cortex. - **isaac_moveit**: Contains the required launch and config files for running ROS MoveIt. - **isaac_ros_messages**: A custom set of messages for 2D/3D bounding boxes and pose service messages. - **isaac_ros_navigation_goal**: Used to automatically set random or user-defined goal poses in ROS Navigation. - **isaac_tutorials**: Contains launch files, RViz config files, and scripts for the tutorial series. - **isaac_vins**: Contains launch, parameters, and config files required to run VINS Fusion with Unitree A1 Quadruped robot. .. _isaac_ros2_workspace: ROS 2 ############### #. To build the ros2 workspace, you may need to install additional packages: .. code-block:: bash # For rosdep install command sudo apt install python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential # For colcon build command sudo apt install python3-colcon-common-extensions #. Ensure your native ROS2 has been sourced if not already. .. code-block:: bash source /opt/ros/foxy/setup.bash #. Resolve any package dependencies from the root of the ROS2 workspace by running the following command: .. code-block:: bash cd foxy_ws rosdep install -i --from-path src --rosdistro foxy -y #. Build the workspace: .. code-block:: bash colcon build Under the root directory, new ``build``, ``install``, and ``log`` directories will be created. #. To start using the ROS2 packages built within this workspace, open a new terminal and source the workspace with the following commands: .. code-block:: bash source /opt/ros/foxy/setup.bash cd foxy_ws source install/local_setup.bash .. _isaac_included_ros2_packages: Included ROS 2 Packages ************************* A list of sample ROS2 packages created for |isaac-sim|: - **carter_description**: Description of the NVIDIA Carter robot model. - **carter_navigation**: Contains the required launch file and ROS2 navigation parameters for the NVIDIA Carter robot. - **isaac_ros2_messages**: A custom set of ROS2 messages for 2d/3d bounding boxes and pose service messages. - **isaac_ros_navigation_goal**: Used to automatically set random or user-defined goal poses in ROS2 Navigation. - **isaac_tutorials**: Contains launch files, RViz2 config files, and scripts for the tutorial series. .. important:: Remember to source your ROS2 workspace each time a new terminal is opened or whenever a new ROS2 package is included. But do not source it in the terminal you are launching Isaac Sim. .. _isaac_ros2_windows: ROS 2 Windows Beta ================== There is experimental ROS2 Foxy support on windows Follow `the ros2 windows install instructions `_ for installing ROS2 Foxy on Windows. Please note that Windows support is currently a Beta version and has been tested to work with the ROS2 installation from this source only. Once the installation is complete, unlike Linux, we need to source ROS2 before running Isaac Sim. Similar to the instructions for `Opening a developer command prompt `_: You will need to do the following to activate a ROS2 command prompt for windows. #. From the start menu, look for ``x64 Native Tools Command Prompt for VS 2019``. #. Run the shortcut as administrator. #. Once the developer command prompt is open, run ``c:\opt\ros\foxy\x64\setup.bat`` #. Run ``set FASTRTPS_DEFAULT_PROFILES_FILE=C:\\fastdds.xml`` #. cd #. Run ``isaac-sim.bat`` #. Enable ``omni.isaac.ros2_bridge`` from the extension manager window. .. note:: We recommend setting ``FASTRTPS_DEFAULT_PROFILES_FILE`` in your environment variables so you don't need to set it in the individual command prompt windows Setting up your workspace ######################### When building the ROS2 workspace you may encounter path length errors, we recommend enabling `long path support `_. Note that you may need to re-open your command prompt after enabling for this setting to take effect. Alternatively copy the foxy_ws folder to ``C:\foxy_ws`` to reduce the overall path lengths when building the environment #. Resolve any package dependencies from the root of the ROS2 workspace by running the following command: .. code-block:: bash cd foxy_ws rosdep install -i --from-path src --rosdistro foxy -y .. note:: At the time of writing this guide you will see the following error that can be ignored .. code-block:: bash #. Build the workspace: .. code-block:: bash colcon build #. Activate the workspace: .. code-block:: bash install\setup.bat #. Set the FASTRTPS profile if it has not already been set before running any ros commands .. code-block:: bash set FASTRTPS_DEFAULT_PROFILES_FILE=C:\\fastdds.xml .. note:: - In some cases commands like ``rviz2`` might not work, run them via ``ros2 run``. For example you may need to use ``ros2 run rviz2 rviz2`` to run rviz. - If images and other messages are not showing up in rviz2 set the reliability and durability policy to ``System Default`` for the topic .. important:: While most of our ROS2 tutorials and samples should work on windows, windows support is still in Beta and you might encounter issues. Tutorials and samples using RTX Lidar with ROS2 will not work on windows currently. .. _isaac_ros2_humble: ROS 2 Humble Beta ================= There is an experimental ROS2 Humble bridge that can be enabled in the extension manager. Note that only one ROS2 bridge can be enabled at a time. If the Foxy ROS2 bridge is enabled, you must restart |isaac-sim| in order to use the Humble ROS2 Bridge. The two bridges cannot be toggled one after the other. All messages/publishers/subscribers supported in ROS2 Foxy, are supported on ROS2 Humble On Ubuntu 20.04 you will need to install humble from source - `ROS 2 Humble Ubuntu 20.04 `_ Because the Isaac ROS Gems are only supported on humble, The :ref:`isaac_sim_app_tutorial_external_ros_gems` tutorial requires the use of the Humble bridge. .. _isaac_ros_tutorials: ROS Tutorials ================= To start using |isaac-sim| with ROS, complete the ROS Tutorial series starting with :ref:`isaac_sim_app_tutorial_ros_turtlebot`. .. _isaac_ros2_tutorials: ROS2 Tutorials ================= To start using |isaac-sim| with ROS2, complete the ROS2 Tutorial series starting with :ref:`isaac_sim_app_tutorial_ros2_turtlebot`. .. Troubleshooting .. =======================