.. meta:: 
    :title: Isaac Sim ROS Tutorials
    :keywords: lang=en isaac isaac-sim ros

.. _isaac_sim_app_tutorial_ros_turtlebot:


==============================
URDF Import: Turtlebot
==============================

|isaac-sim| have several tools to facilitate integration with the ROS system. We have both ROS and ROS2 bridges in forms of Omnigraph nodes, an URDF importer, as well as connection to Gazebo/Ignition. This tutorial series gives examples of how to use these tools.



Learning Objectives
=======================


In this example, we will import a `Turtlebot3 <https://emanual.robotis.com/docs/en/platform/turtlebot3/overview>`_ into Isaac Sim using the URDF importer. 

If you already have a robot with rigged joints and properties in USD format, and you wish to jump straight into using our ROS bridges, go to the next tutorial in the series :ref:`isaac_sim_app_tutorial_ros_drive_turtlebot`.


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

**Prerequisite**

- Completed :ref:`isaac_sim_app_install_ros` so that ROS is available, ROS extension is enabled, and necessary environment variables are set.
- Basic understanding ROS workspace.
- Nucleus downloaded to access Isaac Environments


Importing TurtleBot URDF
=============================

- Download and build the Turtlebot3 package if you haven't done so already. You can build it inside the :ref:`ROS workspace <isaac_ros_workspace>`. You can also use your own ROS workspace. If you choose to use your own workspace, make sure to source that workspace  before launching |isaac-sim|, so that the path to it is part of ``ROS_PACKAGE_PATH``.

.. code-block::

    git clone -b <distro>-devel https://github.com/ROBOTIS-GIT/turtlebot3.git turtlebot3

- Locate the Xacro file for Turtlebot3 Burger in ``turtlebot3/turtlebot3_description/urdf/turtlebot3_burger.urdf.xacro``. Convert the ``.xacro`` file to ``.urdf`` file by calling

.. code-block::

    rosrun xacro xacro -o <output_name>.urdf <input_file>.urdf.xacro

- If your URDF file contains calls to other ROS packages, such as when looking for mesh files of accessories, make sure the path to those ROS packages are also inside the ``ROS_PACKAGE_PATH`` before launching the simulator. 

#. For the purpose of this tutorial series, we will use an Isaac environment, but you can import the robot into any environment of your choosing. Open the environment by going to the *Content* tab below the viewport, and find *Isaac/Environments/Simple_Room/simple_room.usd*. If you do not want to use the provided environment, just make sure there is a *GroundPlane* and a *PhysicsScene* to your environment. Both can be found in *Create -> Physics*. You may also need some lighting, play with the various types of lighting in *Create -> Light* to get the desired effect.
#. On a new stage, drag the *simple_room.usd* onto the stage, and place it at the origin by zero out all the *Translate* components in the Transform Property. You many need to zoom in a bit to see the table inside the room.
#. Open the URDF importer *Isaac Utils > Workflows > URDF Importer*.
#. In the prompt window, inside *Import Option* section, uncheck *clear stage* to preserve the existing environment, uncheck *Fix Base Link* since this is a mobile robot, change *Joint Drive Type* to `Velocity` so that wheels can be properly driven later.
#. Inside *Import* section, first locate the URDF file you wish to import in the *Input File*. The ``Import`` button will only enable after you've selected the file.
#. Once the asset is imported into |kit|, a copy of the .usd version of the asset will be automatically saved. Specify the folder you wish to save the asset in *Output Directory* if it's different than the folder that the .urdf file is located in. A folder name matching the *.urdf* file will be created in the specified directory, and the *.usd* file will be inside the newly created folder.
#. Make sure to unselect everything on the stage by click on an empty space inside the Stage tab, or select */World* on the tree. Otherwise you might be importing the Turtlebot as a child of a random object on the tree.
#. Click *Import*.
#. When the Turtlebot is first imported, it will be on the table. Place it just above the floor of the room using the gizmo.
#. Press *Play* and you should see the Turtlebot fall onto the floor.


.. raw:: html

    <div style="width: 100%;display: inline-block;position: relative;">
        <div id="dummy" style="margin-top: 56%;">
        </div>
        <div align="center">
        <div id="kaltura_player_1" style="position:absolute;top:0;left:0;left: 0;right: 0;bottom:0;border:solid thin black;"></div>
        <script type="text/javascript" src="https://cdnapisec.kaltura.com/p/2935771/embedPlaykitJs/uiconf_id/46302491"></script>
        <script type="text/javascript">
            try {
            var kalturaPlayer = KalturaPlayer.setup({
            targetId: "kaltura_player_1",
            provider:
            { partnerId: 2935771, uiConfId: 46302491 }
            });
            kalturaPlayer.loadMedia(
            {entryId: '1_3qotb4yd'}
            );
            } catch (e)
            { console.error(e.message) }
        </script>
        </div>
    </div>


Tune the Robot
=============================

The URDF importer automatically imports material, physical, and joint properties whenever it is available and have matching categories in |isaac-sim|. However, in cases there are no available or matching categories, or if the units are different between the two systems, what gets automatically filled in may not be accurate and changes the robot's behavior. Here are the steps for tuning some of the common paramters.


**Frictional Properties**

If your robot's wheels are slipping, try changing the friction coefficients of the wheels and potentially the ground as well following steps 3.4.2 in :ref:`isaac_sim_app_tutorial_intro_simple_objects`


**Physical Properties**

If no explicit mass or inertial properties are given, the physics engine will estimate them from the geometry mesh. To update the mass and inertial properties, find the prim that contains the rigid body for the given link (You can verify this by finding "Physics > Rigid Body" under its property tab). If it already has a "Mass" category under its Physics property tab, modify them accordingly. If there isn't already a "Mass" category, you can add it by clicking on the ``+Add`` button on top of the Propery tab, and select "Physics > Mass".


**Joint Properties**

If your robot is oscillating at the joint or moving too slow, take a look at the stiffness and damping parameters for the joints. High stiffness makes the joints snap faster and harder to the desire target, and higher damping smoothes but also slows down the joint's movement to target. For pure position drives, set relatively high stiffness and low damping. For velocity drives, stiffness must be set to zero with a non-zero damping. We provide two tools to help with inspect the joints and tune the stiffness and damping parameters: :ref:`isaac_gain_tuner` and :ref:`isaac_articulation_inspector`. Please go to the perspective tutorials for details on how to use them.

 
.. note:: When the URDF importer finishes, the robot that appears on stage is usually loaded as a `reference <../common/glossary-of-terms.html>`_. This can be confirmed by an orange arrow on the robot prim on the stage tree |eyecon|. If you have problem changing the parameters and saving them, you may need to edit the original USD file that the reference is pointing to instead. The path to the original USD file can be found under the property tab `References -> Asset Path`.


Summary
========

This tutorial covered the following topics:

#. URDF import
#. Tuning the robot parameters

Next Steps
^^^^^^^^^^^^^^^^^^^^^^

Continue on to the next tutorial in our ROS Tutorials series, :ref:`isaac_sim_app_tutorial_ros_drive_turtlebot`, to learn how to add omnigraph nodes to move the robot, and ROS bridge nodes to connect to the ROS network.


Further Learning
^^^^^^^^^^^^^^^^^^^^^^

- More details :ref:`isaac_sim_urdf_importer`.
- More details on world building :ref:`isaac_sim_app_tutorial_gui_simple_robot`
- More details about :ref:`isaac_gain_tuner` and :ref:`isaac_articulation_inspector`


.. |eyecon| image:: /content/images/isaac_reference_eyecon.png
    :width: 30