==================================
Isaac ROS Mission Client Tutorial
==================================

Docker Setup
------------

To streamline your development environment setup with the correct versions of dependencies on Jetson and x86_64 platforms, it is recommended that you leverage the Isaac ROS Dev Docker images. To do this, follow :doc:`the dev environment setup steps </getting_started/dev_env_setup>`.

**Note**: All Isaac ROS quick start guides, tutorials, and examples have been designed with the Isaac ROS Docker images as a prerequisite.

Tutorial with Isaac Sim
-----------------------

.. figure:: :ir_lfs:`<resources/isaac_ros_docs/getting_started/tutorial.png>`
   :width: 650px
   :alt: Tutorial Visual
   :align: center

This tutorial walks you through steps to send missions from `Mission Dispatch <https://github.com/nvidia-isaac/isaac_mission_dispatch>`_ to Isaac ROS Mission Client using the `VDA5050 protocol <https://github.com/VDA5050/VDA5050/blob/main/VDA5050_EN.md>`_. The Mission Client is attached to an Isaac Sim environment running the `Nav2 stack <https://navigation.ros.org/>`_. The summary of steps are as follows:

1. Set up Isaac Sim
2. Run Mission Client
3. Run Mission Dispatch
4. Send a position setup to Nav2 using Mission Dispatch and Mission Client

Tutorial Walkthrough
~~~~~~~~~~~~~~~~~~~~


1. Install and launch Isaac Sim following the steps in the :doc:`Isaac ROS Isaac Sim Setup Guide </getting_started/isaac_sim/index>`.
2. Select ``/World/Carter_v2_4_ROS/ros_lidars/publish_front_2d_lidar_scan`` in the *Stage* pane and change the topic name for front 2D lidar as shown below.

   .. figure:: :ir_lfs:`<resources/isaac_ros_docs/concepts/localization/lidar/isaac_sim_lidar_topic.png>`
        :align: center
        :width: 400px

3.  Select ``/World/Carter_v2_4_ROS/ros_lidars/front_2d_lidar_render_product`` in the *Stage* pane and set ``enabled`` to True.
   
4.  Press **Play** to start publishing data from the Isaac Sim.

    .. figure:: :ir_lfs:`<resources/isaac_ros_docs/getting_started/isaac_sim_sample_scene.png>`
        :align: center
        :width: 600px

5. Follow the instructions at the link to set up your :doc:`development environment </getting_started/dev_env_setup>`.

6. Clone this repository and its dependencies under `${ISAAC_ROS_WS}/src`:

    .. code-block:: bash

        cd ${ISAAC_ROS_WS}/src
        git clone :ir_clone:`<isaac_ros_common>`
        git clone :ir_clone:`<isaac_ros_mission_client>`

7. Start MQTT broker.

    The MQTT broker is used for communication between the Mission Dispatch and the robots. There are many ways to run an MQTT broker, including as a system daemon, a standalone application, or a Docker container. The following example uses `mosquitto` as the MQTT broker. Start the `mosquitto` broker by running the following:

      .. code-block:: bash

          cd ${ISAAC_ROS_WS}/src/isaac_ros_mission_client
          docker run -it --network host -v ${PWD}/utils/mosquitto.sh:/mosquitto.sh -d eclipse-mosquitto:latest sh mosquitto.sh 1883 9001

8. Launch the Docker container using the `run_dev.sh` script:

    .. code-block:: bash

        cd ${ISAAC_ROS_WS}/src/isaac_ros_common && ./scripts/run_dev.sh

9.  Inside the container, build and source the workspace:

    .. code-block:: bash

        cd /workspaces/isaac_ros-dev && \
            colcon build --symlink-install && \
            source install/setup.bash

10. (Optional) Run tests to verify complete and correct installation:

    .. code-block:: bash

        colcon test --executor sequential

11. Run the following launch files to spin up ``mission_client`` and Nav2:

    .. code-block:: bash

        ros2 launch isaac_ros_vda5050_nav2_client_bringup isaac_ros_vda5050_nav2_client.launch.py

12. Start `Mission Dispatch <https://github.com/nvidia-isaac/isaac_mission_dispatch#getting-started-with-deployment-recommended>`__ with Docker.

    - On the Postgres database:

      Set the following environment variable:

      .. code-block:: bash

          export POSTGRES_PASSWORD=<Any password>

      Start the Postgres database by running the following:

      .. code-block:: bash

          docker run --rm --name postgres \
            --network host \
            -p 5432:5432 \
            -e POSTGRES_USER=postgres \
            -e POSTGRES_PASSWORD \
            -e POSTGRES_DB=mission \
            -d postgres:14.5

    - Launch the Mission Database microservice:

      Start the API and database server with the official Docker container.

      .. code-block:: bash
        
          docker run -it --network host nvcr.io/nvidia/isaac/mission-database:isaac_ros

      To see what configuration options are, run:

      .. code-block:: bash

          docker run -it --network host nvcr.io/nvidia/isaac/mission-database:isaac_ros --help

      # For example, if you want to change the port for the user API from the default 5000 to 5002, add `--port 5002` configuration option in the command.

    - Launch the Mission Dispatch microservice:

      Start the Mission Dispatch server with the official Docker container.

      .. code-block:: bash

          docker run -it --network host nvcr.io/nvidia/isaac/mission-dispatch:isaac_ros

      # To see what the configuration options are, add --help option after the command.

.. note::

    Read `this tutorial <https://github.com/nvidia-isaac/isaac_mission_dispatch#getting-started-with-deployment-recommended>`_ for more deployment options for Mission Dispatch.

12. Open `http://localhost:5000/docs` in a web browser.
13. Use the `POST /robots` endpoint to create robot objects. See the video below for steps.
14. Get the status of the robots using the `GET /robot`
    endpoint. If the robots are connected, the state should reflect the actual position of the robots.

.. figure:: :ir_lfs:`<resources/isaac_ros_docs/getting_started/create_and_delete_robot.gif>`
   :width: 800px
   :alt: Isaac ROS Mission Client Sample Isaac Sim Output
   :align: center

.. note::

    When using the interactive documentation page, the default value for the the robot object
    ``name`` in the ``spec`` is 'string', you must change it from 'string' to another name that has
    more meaning, like 'carter01'. Delete the ``prefix`` entry as shown in the video.

15. Send a mission to the robot using the `POST /mission` endpoint. See the video below for steps.

.. figure:: :ir_lfs:`<resources/isaac_ros_docs/getting_started/create_and_query_mission.gif>`
   :width: 800px
   :alt: Isaac ROS Mission Client Sample Isaac Sim Output

.. note::

    By default, the value for the ``robot`` is 'string', so make sure to change it to
    the `name` you used for one of the robot objects you created earlier. For example, if you set the ``name`` of the robot
    object to 'carter01', use that to fill in the ``robot`` field for the mission. Also, delete the ``prefix``,
    ``selector``, ``sequence``, and ``action`` entries as shown in the video.

1.  Return to the Isaac Sim screen. Verify that you can see the robot move to the set goal position, as shown below.

.. figure:: :ir_lfs:`<resources/isaac_ros_docs/getting_started/sim_output.gif>`
   :width: 650px
   :alt: Isaac ROS Mission Client Sample Isaac Sim Output
   :align: center

2.  To cancel a mission, use the `POST /mission/{name}/cancel` endpoint. In the request body, ensure the ``name`` field is correctly set to the mission's name that you intend to cancel. Subsequently, observe that the robot stops its motion within Isaac Sim, and that the mission's state shifts to `CANCELED` on querying with the `GET /mission/{name}` endpoint. A mission that has been completed cannot be canceled.

Customize Your Dev Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To customize your development environment, reference :ref:`this guide <repositories_and_packages/isaac_ros_common/index:Isaac ROS Docker Development Environment>`.