.. _isaac_sim_app_tutorial_gui_simple_robot:

=============================
Assemble a Simple Robot 
=============================

|isaac-sim|'s GUI interface features are the same ones used in |composer_long|, an application dedicated to world-building. In this tutorial series, we will focus on the GUI functions that are most relevant to robotic uses. For more sophisticated general world creation, please check out `Omiverse Create <../../app_composer/app_composer/overview.html>`_.

In this tutorial, we will rig a simple "robot" with three links and two revolute joints to introduce the basic concepts of joints and articulations. We will take the objects that were added to the stage in :ref:`isaac_sim_app_tutorial_intro_simple_objects`, and turn them into a mock mobile robot with rectangular body and two cylindrical wheels. While this step is not needed for robots that are imported from :ref:`isaac_onshape_importer_tutorials_importing` or :ref:`isaac_sim_urdf_importer`, these are important concepts to understand for tuning your robots and assembling objects with articulations.


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

This tutorial details how to rig a two-wheel mobile robot. We will cover how to

- Organize stage tree hierarchy
- Add joints between two rigid bodies
- Add joint drives and joint properties
- Add articulations

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

**Prerequisites**

- Please complete all :ref:`Introductory Tutorials <isaac_sim_app_tutorial_intro_interface>`.

Add Joints
===================

#. If you are continuing from the Introductory Tutorials and have your own *mock_robot.usd* saved, open it using *File> Open*. Otherwise, load the asset provided in *Isaac/Samples/Rigging/MockRobot/mock_robot_no_joints.usd*. Do not load it as a reference since you will need to make permanent modifications to the file.
#. To add a joint between two bodies, first click on the parent body and then the child body. For our mock robot, we will first select :code:`body`, then while holding ``Ctrl + Shift``, select :code:`wheel_left`. With both body highlighted, right-click and then select *Create > Physics > Joints > Revolute Joint*. A :code:`RevoluteJoint` will appear under :code:`wheel_left` on the stage tree. Rename it to :code:`wheel_joint_left`.
#. Double check in the *Property* tab that *body0* is the cube, and *body1* is the cylinder. 
#. Change the *Axis* of the joint to *Y*. 
#. If you look closely, the joint's two local frames are misaligned. To correct it, go to *Local Rotation 0* and make x = 0 degrees. Next, go to *Local Rotation 1* and make x = -90 degrees. The example here only shows an orientation misalignment, you may see translational misalignment depending on your robot.
#. Repeat steps 1-4 for the right wheel joint.

.. 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_jqyq5rhh'}
            );
            } catch (e)
            { console.error(e.message) }
        </script>
        </div>
    </div>

Before the joints were added, the three rigid bodies fell to the ground separately after pressing `Play`. Now that there are joints attached, the bodies will fall as if they are connected. You can drag the robot around by holding down the ``Shift`` key and clicking and dragging on any part of the robot in the viewport, and you can see that they move together like they are connected via revolute joints.

.. 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_2" 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_2",
            provider:
            { partnerId: 2935771, uiConfId: 46302491 }
            });
            kalturaPlayer.loadMedia(
            {entryId: '1_i80g9xdl'}
            );
            } catch (e)
            { console.error(e.message) }
        </script>
        </div>
    </div>

Add Joint Drive
===================

Adding the joint is only adding the mechanical connection. To be able to control and drive the joints, we need to add a joint drive API. Select both joints and click the ``+ Add`` button in the *Property* tab, and select *Physics > Angular Drive* to add drive to both joints simultaneously.

.. 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_3" 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_3",
            provider:
            { partnerId: 2935771, uiConfId: 46302491 }
            });
            kalturaPlayer.loadMedia(
            {entryId: '1_dbfh7jsq'}
            );
            } catch (e)
            { console.error(e.message) }
        </script>
        </div>
    </div>

- **Position Control:** for position controlled joints, set a high stiffness and relatively low or zero damping.
- **Velocity Control:** for velocity controller joints, set a high damping and zero stiffness.

For joints on a wheel, it makes more sense to be velocity controlled, so let's set both wheels' *Damping* to *1e4*and *Target Velocity* to *200*. 
If you are working with joints with limited range, those can be set in the *Property* tab, under the *Raw USD Properties > Lower (Upper) Limit*. 
Press `Play` to see our mock mobile robot drive off.

.. 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_4" 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_4",
            provider:
            { partnerId: 2935771, uiConfId: 46302491 }
            });
            kalturaPlayer.loadMedia(
            {entryId: '1_r8lrijw4'}
            );
            } catch (e)
            { console.error(e.message) }
        </script>
        </div>
    </div>

.. _isaac_sim_app_tutorial_gui_simple_robot_articulation:

Add Articulation
===================

Even though directly driving the joints can move the robot, it is not the most computationally efficient way. Making things into *articulations* can achieve higher simulation fidelity, fewer joint errors, and can handle larger mass ratios between the jointed bodies. You can read more regarding the physics simulation behind it in `Physics Core: Articulation <../../prod_extensions/prod_extensions/ext_physics.html#articulations>`_. 
To turn a series of connected rigid bodies and joints into articulation, we need to set an *articulation root* to anchor the articulation tree. According to instructions on defining articulation trees in `Physics Core: Articulation <../../prod_extensions/prod_extensions/ext_physics.html#articulations>`_ : 

.. pull-quote::

	For a fixed-base articulation, add the Articulation Root Component either to: 1) the fixed joint that connects the articulation base to the world, or 2) an ancestor of the fixed joint in the USD hierarchy. The second option allows creating multiple articulations from a single root component added to the scene: Each descendant fixed joint will be defining an articulation base link.
	For a floating-base articulation, add the Articulation Root Component either to: 1) the root rigid-body link or 2) an ancestor of the root link in the USD hierarchy.

In our case, we will add the articulation root to the robot body. Select :code:`body` on the tree, open ``+ Add`` in the *Property* tab, and add *Physics > Articulation Root*.

.. 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_5" 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_5",
            provider:
            { partnerId: 2935771, uiConfId: 46302491 }
            });
            kalturaPlayer.loadMedia(
            {entryId: '1_1cv8bym3'}
            );
            } catch (e)
            { console.error(e.message) }
        </script>
        </div>
    </div>


The resulting robot should match the asset provided in `Isaac/Samples/Rigging/MockRobot/mock_robot_rigged.usd`.

Summary
========
   
In this tutorial, we covered how to connect rigid bodies using joints, add joint drive to control the joints, as well as turning a chain of joints into an articulation.

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

Continue on to :ref:`isaac_sim_app_tutorial_gui_camera_sensors` to learn how to add a camera to the car.

Further Reading
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Please read `Physics Core <../../prod_extensions/prod_extensions/ext_physics.html>`_ for more details regarding joints and articulations.